
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 Agenthermes --version能打印版本号hermes setup里填的是 TaoToken 的 Base URL 和 Key发一条对话请求能正常返回内容。下面开始。2. 前置准备WSL2 环境与 TaoToken 通道在动手装 Hermes 之前有两件事要先落地一是 Windows 侧的 WSL2 基础环境二是模型调用的 API 通道。前者决定你能不能跑起来后者决定 Agent 能不能真正调用大模型。先说 Windows 侧。你的系统需要是 Windows 10 1903 以上或 Windows 11BIOS 里开启了虚拟化绝大多数笔记本默认开启并且当前账户有管理员权限。检查虚拟化是否开启可以在任务管理器「性能」标签页看 CPU 那一栏有没有「虚拟化已启用」。如果显示已禁用需要进 BIOS 打开 Intel VT-x 或 AMD-V。再说模型通道。Hermes Agent 本身不带模型它需要你提供一个兼容 OpenAI 接口规范的 API 端点。你可以直接填某一家厂商的地址但更省事的做法是接 TaoToken 的统一 API 通道——它把多家模型聚合成一个 Base URL换模型时只改 Model ID不用改代码和配置结构。对 Hermes 这种要在setup向导里反复切模型的场景这一点很实用。TaoToken 的接入信息如下后面配置环节会用到项目值官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Base URLhttps://taotoken.net/apiAPI Key 获取https://taotoken.net/api-keys接入文档https://taotoken.net/doc模型对话体验https://taotoken.net/chatCoding Planhttps://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.04wsl --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/apiAPI 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 对话验证通道确认没问题后启动 Hermeshermes进入对话界面随便问一句比如「帮我列一个 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 安装脚本卡住或中断网络问题导致脚本卡住时CtrlC 中断换国内源脚本重跑。已经装了一半的依赖不会冲突脚本会跳过已完成的步骤。如果反复失败先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 用起来做自动化和编码辅助。