1. Windows 本地跑 Hermes Agent 到底卡在哪Hermes Agent 是一个能读写文件、执行命令、调用外部工具的智能体框架适合想把 AI 从「聊天窗口」拉进真实工作流的开发者。它跑在 Linux 环境下最顺而 Windows 用户想用绕不开 WSL2 这层壳。很多人第一次装卡的不是 Hermes 本身而是 PowerShell 权限、WSL2 内核、Ubuntu 源、Node 版本这几道关。我自己在 Windows 11 上从零走了一遍最深的感受是报错基本都集中在「环境没对齐」而不是 Hermes 代码有问题。比如wsl --install提示需要重启、apt update卡在 0%、hermes setup找不到 node这些都不是玄学是步骤顺序和源配置的问题。这篇按「PowerShell 装 WSL2 → Ubuntu 配依赖 → 装 Hermes → 把 API 通道切到 TaoToken → curl 验证」的顺序写每一步都给可复制的命令和预期输出。你跟着敲遇到报错直接跳到第 5 节对照排查。适合人群会用命令行但没深入折腾过 WSL 的后端/全栈开发者以及想在本地跑 Agent 做自动化的人。核心检索词先明确Windows 安装 Hermes Agent、WSL2 部署智能体、Hermes Agent 接入 API 通道。这三个词贯穿全文你搜到的其他教程如果只讲一半大概率会在配置环节断掉。2. 前置准备TaoToken 通道与 WSL2 环境对齐2.1 为什么先把 API 通道定下来Hermes Agent 本身不带模型它需要指向一个兼容 OpenAI 协议的 API 端点。默认配置里填的是官方地址国内直连经常超时。TaoToken 提供的就是这个兼容层一个 Base URL、一个 Key、一组 Model ID填进去就能用。你可以在官网看接入说明API 地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时别自己加斜杠或路径。先把通道定下来再装 Hermes好处是装完直接改配置不用来回切。如果你还没 Key去控制台建一个模型 ID 用文档里列出的那几个别自己猜名字。2.2 WSL2 装之前确认三件事第一Windows 版本。Win10 2004 以上或 Win11 才支持wsl --install一条命令搞定。老版本要手动开功能麻烦得多。在 PowerShell 里跑winver看一眼。第二虚拟化。任务管理器 → 性能 → CPU看「虚拟化」是不是「已启用」。没启用要去 BIOS 开这一步不过WSL2 起不来。第三磁盘空间。Ubuntu 子系统加依赖加 Hermes预留 15GB 比较稳。C 盘快满的话先清。这三件事确认完再动 PowerShell。很多人跳过这步结果wsl --install跑完重启后报WslRegisterDistribution failed回头查半天其实就是虚拟化没开。2.3 管理员权限不是可选项WSL2 安装必须用管理员身份跑 PowerShell。普通窗口跑wsl --install会提示权限不足或者装到一半失败。开始菜单搜 PowerShell右键「以管理员身份运行」窗口标题栏会带「管理员」字样。这一步别省。3. 可复制配置从 PowerShell 到 Hermes settings3.1 PowerShell 装 WSL2 与 Ubuntu管理员 PowerShell 里执行wsl --install这条命令会启用虚拟机平台、装 WSL2 内核、下载 Ubuntu 发行版。跑完提示重启重启后 Ubuntu 会自动启动让你建 Linux 用户名和密码。密码输入时不显示正常现象输完回车即可。如果提示「已安装 WSL但未安装发行版」用wsl --install -d Ubuntu装完确认版本wsl -l -v输出里 Ubuntu 那行 STATE 是 Running、VERSION 是 2就对了。如果是 1跑wsl --set-version Ubuntu 2转过来。3.2 Ubuntu 依赖清单与源替换进 Ubuntu 终端先备份源再替换。Ubuntu 24.04 用的是ubuntu.sources格式sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak sudo sed -i s|http://archive.ubuntu.com|https://mirrors.aliyun.com|g /etc/apt/sources.list.d/ubuntu.sources sudo sed -i s|http://security.ubuntu.com|https://mirrors.aliyun.com|g /etc/apt/sources.list.d/ubuntu.sources sudo apt update sudo apt upgrade -y然后装依赖sudo apt install -y git curl nodejs npm build-essentialbuild-essential别漏Hermes 有些原生模块编译要用。装完确认 Node 版本node -v npm -vNode 低于 18 的话Hermes 可能跑不起来。用 nvm 升curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20npm 源也换一下装包快很多npm config set registry https://registry.npmmirror.com3.3 安装 Hermes Agent官方安装脚本curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash跑完source ~/.bashrc让 PATH 生效然后hermes --version有版本号输出就装好了。接着初始化hermes setup交互式配置里模型那步选「我有 API Key」然后填 TaoToken 的 Key。Base URL 这步是关键填https://taotoken.net/apiModel ID 填文档里列出的名字比如claude-sonnet-4-20250514这类别自己编。后面的消息网关、服务模式按需选个人电脑选手动启动24 小时在线选系统服务。3.4 settings 配置片段Hermes 的配置落在~/.hermes/settings.json你也可以直接改这个文件。关键字段{ provider: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 }, gateway: { mode: manual } }三件套对齐Base URL 是https://taotoken.net/apiKey 是控制台建的Model ID 是文档里的。这三个任何一个错请求都会失败。改完保存重启 gatewayhermes gateway4. 验证请求curl 确认通道连通配置改完别急着在 Hermes 里跑任务先用 curl 单独验通道。这一步能把「通道问题」和「Hermes 问题」分开。curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 ok}], max_tokens: 10 }预期返回一段 JSONchoices[0].message.content里有内容。如果返回 401是 Key 问题返回 404是路径或 Model ID 问题超时是网络或 Base URL 问题。curl 通了再回 Hermes 里跑hermes chat 列出当前目录文件能正常返回并执行工具调用说明整条链路打通。我实测下来curl 这步能省掉后面 80% 的排查时间因为 Hermes 的报错信息有时候会吞掉底层 HTTP 状态码。5. 常见报错排查401、proxy failed、reading choices5.1 401 Unauthorized最常见。原因三个Key 复制时带了空格、Key 已失效、Authorization 头格式不对。检查settings.json里 apiKey 字段前后别有空格。curl 测试时Bearer和 Key 之间一个空格别多别少。如果 Key 刚建去控制台确认状态是启用。5.2 local proxy failed / connection refused这个报错通常出现在 Hermes 启动时。原因是 gateway 没起来或者端口被占。先看hermes gateway有没有在跑再看 settings 里 gateway 的 host/port 配置。默认端口如果和别的服务冲突改一个。WSL2 里跑的服务Windows 侧访问要用localhost别用 127.0.0.1 之外的地址。5.3 reading choices 报错这个多半是返回体不是预期 JSONHermes 解析choices字段失败。原因Base URL 填错导致返回了 HTML 错误页或者 Model ID 不存在返回了错误结构。用第 4 节的 curl 单独测看返回的原始内容。如果返回的是 HTML说明 URL 路径不对确认是https://taotoken.net/api而不是别的。5.4 OAuth / 认证相关报错如果你在配置里选了需要 OAuth 的 provider但没走完授权流程会报这个。Hermes 的 provider 配置里TaoToken 走的是 API Key 模式不需要 OAuth。检查 settings 里有没有残留的 OAuth 字段删掉。CC Switch 或 Cline MCP 这类工具如果也配了同一个通道确认它们的 Base URL、Key、Model ID 三件套和 Hermes 一致别一个填了带路径的、一个填了不带路径的。5.5 apt update 卡住或 404源替换后如果 404说明 Ubuntu 版本和源格式不匹配。22.04 用sources.list24.04 用sources.list.d/ubuntu.sources。确认你的版本lsb_release -a然后按对应格式改。卡在 0% 通常是网络换源后重试。6. 把通道固定下来后续少折腾装完之后日常用 Hermes 就是hermes chat或hermes gateway两条命令。真正省心的是把配置固定Key 别硬编码在脚本里放~/.hermes/settings.json权限设 600。Model ID 如果换了只改这一个文件不用重装。如果你要长期跑 Agent 任务比如定时抓取、自动整理文件建议把 gateway 设成系统服务模式开机自启。个人电脑偶尔用手动启动就行省资源。通道这块TaoToken 的 API 地址https://taotoken.net/api记住不带路径后缀Key 在控制台管理模型对话页面可以快速测模型可用性。接入文档里有各语言的示例curl 那段直接抄。需要长期编码或跑 Agent 的Coding Plan 比按量更划算具体看你的调用频率。最后留一个实用技巧WSL2 的 Ubuntu 文件系统和 Windows 是隔离的Hermes 生成的文件在\\wsl$\Ubuntu\home\你的用户名\下Windows 资源管理器地址栏直接输这个路径就能访问不用来回拷贝。