1. 为什么 Windows 跑 Hermes Agent 必须走 WSL2 这条路
Hermes Agent 是这两年在开源社区热度很高的自进化智能体，能自动沉淀技能、维护持久记忆，用得越久越贴合你的工作习惯。但它有一个硬门槛：官方只支持 Linux 和 macOS，没有原生 Windows 版本。你在 PowerShell 或 CMD 里直接pip install或者跑安装脚本，大概率会在依赖编译、systemd 进程管理、路径分隔符这几处连环报错。
原因不复杂。Hermes Agent 是重度 Python 项目，依赖uv做包管理，运行期还要拉起网关进程、读写 Unix 域套接字、调用ripgrep、ffmpeg这类 Linux 工具链。Windows 原生命令行缺少完整的 Linux 内核语义，很多系统调用对不上。WSL2 的做法是在 Windows 内核之上跑一个真实的 Linux 内核虚拟机，你拿到的 Ubuntu 环境和一台独立 Linux 服务器几乎没有差别，这也是目前 Windows 用户跑 Hermes Agent 唯一稳定可靠的路线。
这篇教程面向的是没怎么碰过 Linux 的 Windows 用户。我会从开启 WSL2 开始，一步步装 Ubuntu 22.04、部署 Hermes Agent、配置依赖，最后把模型通道接到 TaoToken 的统一 API 上，让 Agent 的调用链路在本地完整跑通。全程命令可以直接复制，遇到报错我会在第五节集中排。
先明确一下最终要达成的状态：Windows 里有一个 Ubuntu 22.04 的 WSL2 实例，里面装好 Hermes Agent，hermes --version能打印版本号，hermes setup里填的是 TaoToken 的 Base URL 和 Key，发一条对话请求能正常返回内容。下面开始。
2. 前置准备：WSL2 环境与 TaoToken 通道
在动手装 Hermes 之前，有两件事要先落地：一是 Windows 侧的 WSL2 基础环境，二是模型调用的 API 通道。前者决定你能不能跑起来，后者决定 Agent 能不能真正调用大模型。
先说 Windows 侧。你的系统需要是 Windows 10 1903 以上或 Windows 11，BIOS 里开启了虚拟化（绝大多数笔记本默认开启），并且当前账户有管理员权限。检查虚拟化是否开启，可以在任务管理器「性能」标签页看 CPU 那一栏有没有「虚拟化：已启用」。如果显示已禁用，需要进 BIOS 打开 Intel VT-x 或 AMD-V。
再说模型通道。Hermes Agent 本身不带模型，它需要你提供一个兼容 OpenAI 接口规范的 API 端点。你可以直接填某一家厂商的地址，但更省事的做法是接 TaoToken 的统一 API 通道——它把多家模型聚合成一个 Base URL，换模型时只改 Model ID，不用改代码和配置结构。对 Hermes 这种要在setup向导里反复切模型的场景，这一点很实用。
TaoToken 的接入信息如下，后面配置环节会用到：
| 项目 | 值 |
|---|---|
| 官网 | https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= |
| API Base URL | https://taotoken.net/api |
| API Key 获取 | https://taotoken.net/api-keys |
| 接入文档 | https://taotoken.net/doc |
| 模型对话体验 | https://taotoken.net/chat |
| Coding Plan | https://taotoken.net/coding-plan |
注意：Base URL 填
https://taotoken.net/api，不要在后面多加/v1，具体以接入文档为准。很多 401 和 404 报错都是路径拼错导致的。
如果你打算长期用 Hermes 做编码和自动化任务，可以顺带了解一下 Coding Plan，它在高频调用场景下比按量计费更划算。不过这一步不影响安装，先把环境跑通再说。
3. 可复制配置：WSL2 安装、Ubuntu 依赖与 Hermes 部署
这一节是全文的核心操作区，命令都可以直接复制。我按「Windows 开 WSL2 → 装 Ubuntu → Ubuntu 内装 Hermes → 配置模型」的顺序走。
3.1 开启 WSL2 与虚拟机平台
以管理员身份打开 PowerShell，执行两条启用命令：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完必须重启电脑。这一步不重启，后面设置 WSL2 默认版本或转换 Ubuntu 版本时会出现各种奇怪问题，别省这一步。
重启后回到 PowerShell，把 WSL2 设为默认版本：
wsl --set-default-version 2然后安装 Ubuntu 22.04：
wsl --install -d Ubuntu-22.04 --web-download--web-download参数会走网络下载而不是走微软商店缓存，国内网络环境下成功率更高。安装完成后从开始菜单启动 Ubuntu，首次进入会让你创建 Linux 用户名和密码，这个密码和 Windows 账户无关，但后面sudo要用，务必记住。
验证版本：
wsl -l -v看到 VERSION 列是 2 就对了。如果显示 1，执行wsl --set-version Ubuntu-22.04 2转换。
3.2 Ubuntu 内更新系统与安装 Hermes
进入 Ubuntu 终端，先更新系统包：
sudo apt update && sudo apt upgrade -y然后跑官方一键安装脚本：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash脚本执行过程中会问你两个可选工具，建议都装：
Install ripgrep for faster file search? [Y/n] y Install ffmpeg for TTS voice messages? [Y/n] yripgrep加速文件搜索，ffmpeg处理语音消息，后面接 IM 机器人时会用到。脚本跑完会进入配置向导，问你要不要现在配模型和 IM，这里可以先跳过，等装完统一配。最后问是否立即启动，选n。
如果网络不佳脚本卡住，换国内源脚本：
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash -x这个脚本会依次安装uv、Python 3.11+、克隆仓库到~/hermes-agent、创建虚拟环境、装依赖、把hermes命令加进 PATH。
装完重载环境变量并验证：
source ~/.bashrc hermes --version出现类似Hermes Agent v0.13.0的版本号就说明安装成功。
3.3 配置 TaoToken 模型通道
执行配置向导：
hermes setup在交互界面里，模型提供商选择自定义 OpenAI 兼容端点，然后填入三件套：
# ~/.hermes/config.toml 关键字段示意 [provider] name = "taotoken" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoToken密钥" model = "claude-sonnet-4-5"如果你更习惯用 JSON 结构管理配置，等价写法是：
{ "provider": { "name": "taotoken", "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model": "claude-sonnet-4-5" } }三个字段一个都不能少：Base URL 填https://taotoken.net/api，API Key 从 https://taotoken.net/api-keys 获取，Model ID 按你要用的模型填。换模型时只改 Model ID 这一行，Base URL 和 Key 不动，这就是统一通道的好处。
配置完成后重载一次环境变量，让 Hermes 读到新配置：
source ~/.bashrc4. 验证请求：确认 Hermes 调用链路跑通
配置写完不代表能用，得实际发一次请求验证。这一步分两层：先验证 TaoToken 通道本身通不通，再验证 Hermes 能不能通过它拿到回复。
4.1 先用 curl 验证 API 通道
在 Ubuntu 终端里直接打一条请求，确认 Base URL 和 Key 有效：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "回复两个字：通了"}] }'正常返回的 JSON 里choices[0].message.content会有内容。如果这里就报 401，说明 Key 有问题；报 404，说明路径拼错了，检查是不是多加了或漏了/v1。
4.2 启动 Hermes 对话验证
通道确认没问题后，启动 Hermes：
hermes进入对话界面，随便问一句，比如「帮我列一个 Python 读取 CSV 的示例」。如果能看到流式返回的内容，说明 Hermes 已经通过 TaoToken 成功调用到模型，整条链路打通。
4.3 启动网关与 Web 面板
如果你要接飞书、QQ、微信这类 IM，启动网关：
hermes gateway run想用图形界面管理，启动 Web 控制面板：
hermes dashboard然后浏览器访问http://127.0.0.1:9119，能看到面板就说明服务正常。
4.4 验证成功的判断标准
三个信号同时满足，才算真正跑通：hermes --version有版本号输出；hermes对话能拿到模型回复；hermes dashboard面板能打开。缺任何一个，回到第五节对照排查。
5. 本篇常见报错排查：401、local proxy failed 与命令找不到
装 Hermes 的过程里，报错集中在几个固定位置。我把最常见的几类列出来，对照着查。
5.1 401 Unauthorized
这是最高频的报错，几乎都和 Key 有关。先确认 Key 是从 https://taotoken.net/api-keys 复制的完整字符串，没有多余空格或换行。然后确认配置里api_key字段没有写成Bearer sk-xxx，只需要填sk-xxx本身，Bearer是请求头里加的，不要写进配置值。
如果 Key 确认没问题还是 401，检查是不是把 Key 填到了错误的 provider 段里。Hermes 支持多 provider，配置写串了会读到空 Key。
5.2 local proxy failed 或连接超时
这个报错通常出现在 WSL2 网络模式上。WSL2 默认走 NAT 网络，某些情况下访问外部 API 会超时。可以先在 Ubuntu 里curl https://taotoken.net/api测试连通性。如果 curl 也超时，检查 Windows 侧的网络是否正常，以及 WSL2 的 DNS 配置。
另一个常见原因是 Base URL 写成了https://taotoken.net/api/v1，而 Hermes 内部又拼了一次/v1，导致路径变成/api/v1/v1/...。统一填https://taotoken.net/api，让客户端自己拼版本路径。
5.3 reading choices 相关报错
报错信息里出现reading 'choices'或cannot read property of undefined，说明返回的 JSON 结构里没有choices字段。这通常是模型名写错了，服务端返回了一个错误对象而不是正常的补全结果。检查 Model ID 是否拼写正确，大小写敏感。换一个确认可用的 Model ID 再试。
5.4 hermes: command not found
装完脚本后直接敲hermes提示找不到命令，是因为 PATH 还没刷新。执行：
source ~/.bashrc如果还不行，检查~/.bashrc里有没有脚本追加的 PATH 行，没有的话手动加：
export PATH="$HOME/.local/bin:$PATH"然后重新source ~/.bashrc。
5.5 OAuth 或授权类报错
如果你在配置里选了需要 OAuth 的 provider，但走的是 TaoToken 通道，会出现授权失败。TaoToken 走的是 API Key 认证，不需要 OAuth 流程。在hermes setup里选自定义 OpenAI 兼容端点，不要选带 OAuth 的官方 provider 选项。
5.6 安装脚本卡住或中断
网络问题导致脚本卡住时，Ctrl+C 中断，换国内源脚本重跑。已经装了一半的依赖不会冲突，脚本会跳过已完成的步骤。如果反复失败，先sudo apt update再重试。
5.7 权限相关报错
不要用 root 用户跑安装脚本。Hermes 会往用户目录写配置和虚拟环境，root 环境下路径和权限都会出问题。用你创建 Ubuntu 时设的普通用户操作，需要提权时用sudo。
6. 把 Hermes 接到 TaoToken：长期使用的配置建议
环境跑通之后，剩下的是怎么用得顺手。这一节说几个实际使用中的配置要点。
第一，模型切换。Hermes 的配置里 Model ID 是独立字段，你可以在~/.hermes/config.toml里改一行就换模型，Base URL 和 Key 保持不变。比如从claude-sonnet-4-5换成别的模型，只动model字段，然后重启hermes即可。这种结构让你可以在不同任务间快速切换，写代码用推理强的模型，日常对话用响应快的模型。
第二，配置备份。~/.hermes/目录下存着配置、记忆和技能数据。建议定期备份这个目录，尤其是记忆和技能文件，那是 Hermes 越用越聪明的核心资产。迁移到新机器时，把这个目录拷过去就能恢复状态。
第三，网关常驻。如果你接了飞书或 QQ 机器人，希望 Hermes 7×24 在线，可以用nohup hermes gateway run &让网关在后台跑，或者配一个 systemd 服务。WSL2 实例在 Windows 重启后需要手动拉起，这一点和独立 Linux 服务器不同，注意别以为它一直在跑。
第四，Key 管理。TaoToken 的 Key 建议按用途分开，比如一个用于 Hermes 日常对话，一个用于批量任务。这样某个 Key 出问题时不影响其他场景，也方便在控制台看用量。Key 不要硬编码在会提交到 Git 的文件里，用环境变量或本地配置文件。
第五，验证习惯。每次改完配置，先跑一遍第 4.1 节的 curl 命令确认通道正常，再启动 Hermes。这样能把「通道问题」和「Hermes 配置问题」分开定位，省很多排查时间。
到这里，Windows 上通过 WSL2 跑 Hermes Agent 并接入 TaoToken 的完整链路就走完了。从开启 WSL2、装 Ubuntu 22.04、部署 Hermes、配置依赖，到填入 Base URL 和 Key、验证请求、排查报错，每一步都有对应的命令和判断标准。接下来你可以按自己的需求接 IM 机器人，或者把 Hermes 用起来做自动化和编码辅助。
