部署 Hermes Agent：Windows 原生与 WSL2 完全指南（TaoToken 统一 Key 接入）

1. 为什么 Windows 上跑 Hermes Agent 总有人卡在第一步Hermes Agent 是一个开源 AI 智能体框架能调用多模型、读写文件、执行代码、跑终端命令还带一个可选的 Web UI。它适合谁适合想在本地搭一个能干活的 Agent、又不想把数据全丢到云端的开发者。但它在 Windows 上的部署体验说实话有点分裂官方推荐 WSL2可很多人手上只有原生 Windows装到一半就撞上 shell 路径、后台服务、端口监听这几堵墙。我自己在两种环境都完整走过一遍最直观的差异是Windows 原生能跑但 Gateway 不能作为后台服务常驻Web UI 经常显示“未连接”WSL2 里所有功能都正常代价是要多一层 Linux 子系统的理解成本。这篇就把两套路径拆开讲清楚环境准备、依赖安装、启动配置、模型接入、Web UI 验证每一步都给可复制的命令。核心检索词先摆出来Hermes Agent 在 Windows 原生与 WSL2 下的部署差异以及 Web UI 访问路径怎么打通。模型接入这块我用 TaoToken 的统一 Key/API 通道来演示因为它把多家模型的 Base URL 和鉴权收敛成一套省得你在配置文件里来回改地址。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 后面配置环节会具体用到。先说结论性的判断如果你只是临时试玩Windows 原生够用如果你打算长期挂着 Agent 跑任务、接消息平台、用 Gateway 后台服务直接上 WSL2别在原生环境里跟兼容性较劲。下面两套方案我都会给全你按自己的场景选。2. TaoToken 前置准备统一 Key 与 API 通道怎么拿在动 Hermes 之前先把模型通道准备好否则装完框架你会发现没模型可调又得回头折腾。TaoToken 的作用是把模型调用统一到一个入口一个 API Key、一个 Base URL就能切换不同模型不用为每家厂商单独维护一套鉴权和地址。对 Hermes 这种要在配置文件里写 base_url 和 api_key 的框架来说这种收敛很省事。获取步骤不复杂。打开 https://taotoken.net/api 这是 API 通道入口。注册登录后进控制台在 API Keys 页面创建一个新 Key复制出来先存好后面配置要用。注意 Key 只在创建时完整显示一次丢了就得重建。创建完 Key你还需要确认两件事Base URL 用哪个、Model ID 填什么。TaoToken 的 API 基地址是 https://taotoken.net/api 模型 ID 按你实际要用的填比如对话类模型直接写对应名称即可。Hermes 的配置里 provider 选 custom (direct API)然后把 Base URL 和 Key 填进去逻辑和填任何 OpenAI 兼容接口一样。这里有个容易踩的点很多人把官网地址和 API 地址搞混。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 用来注册、看文档、进控制台API 地址是 https://taotoken.net/api 填进配置文件的是这个。填错的话请求会打到网页端直接 404 或返回 HTMLHermes 那边就报解析错误。如果你后面要长期跑编码类 Agent 任务可以顺带了解下 Coding Plan它更适合高频调用场景只是验证模型通不通用模型对话页面测一下就行。这些入口在控制台里都能找到先把 Key 拿到手我们再进部署环节。3. 可复制配置Windows 原生与 WSL2 两套环境搭建这一节是全文最重的部分两套环境我都给完整命令。先讲共性的依赖再分方案。共性依赖有三个Python 3.10、Git、Node.js 18。Python 是 Hermes 本体运行环境Git 用于拉取仓库和某些插件的 shell 调用Node.js 支撑 Web UI 的前端构建。Windows 原生下这三个都去官网下安装包装完重启一次让环境变量生效。WSL2 下用 apt 装更干净。3.1 Windows 原生部署以管理员身份打开 PowerShell先放开执行策略再跑安装脚本Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex装完关掉 PowerShell 重开验证hermes --version能打印版本号就说明本体装好了。接着配置模型运行交互式命令hermes model在菜单里选 custom (direct API)然后依次填 Base URL、API Key、模型名。Base URL 填 https://taotoken.net/api API Key 填你刚创建的那串模型名填你要用的 Model ID。这一步也可以跳过交互直接编辑配置文件路径在用户目录下的.hermes/config.yamlmodel: default: your-model-id provider: custom base_url: https://taotoken.net/api api_key: sk-你的Key context_length: 128000Windows 原生有个硬限制hermes gateway不能作为后台服务安装会报Service installation not supported on this platform。所以你得开两个 PowerShell 窗口一个跑 Gateway 保持前台一个跑 Web UI# 窗口1 hermes gateway # 窗口2 hermes-web-ui start然后浏览器访问 http://localhost:8648 。如果显示未连接多半是 API Server 没开。在.env文件里加上这两行再重启 GatewayAPI_SERVER_ENABLEDtrue API_SERVER_KEY你自己设一个密钥Web UI 设置里填入同一个密钥即可。3.2 WSL2 部署推荐管理员 PowerShell 执行wsl --install重启后启动 Ubuntu设好用户名密码。进 Ubuntu 终端装依赖sudo apt update sudo apt install -y python3 python3-pip git curlNode.js 建议用 nvm 装版本可控curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18然后一键装 Hermescurl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.bashrc模型配置和原生一样hermes model选 custom或者直接改~/.hermes/config.yaml内容同上。WSL2 里 Gateway 可以直接前台跑也可以装成服务# 终端1 hermes gateway # 终端2 hermes-web-ui start关键差异在这WSL2 里 Gateway 默认监听127.0.0.1:8642Windows 浏览器访问 localhost 通常能通因为 WSL2 有端口转发。如果通不了把~/.hermes/config.yaml里的api_server.host改成0.0.0.0再重启 Gateway。改完从 Windows 浏览器访问 http://localhost:8648 就能进 Web UI。两套方案对照一下维度Windows 原生WSL2Gateway 后台服务不支持需前台窗口支持Web UI 连接稳定性一般需手动开 API Server好文件操作可能受容器后端影响正常推荐度临时试用长期使用4. 验证请求Web UI 对话与日志检查配置写完不算完得验证模型通道真的通了。最直接的方式是命令行问一句hermes chat -q 你好如果返回正常回复说明 Base URL、Key、Model ID 三件套都对。如果报 401是 Key 无效或没填对如果报连接超时检查 Base URL 是不是写成了官网地址。命令行通了之后再验证 Web UI。确保 Gateway 窗口有类似API server listening on ...的日志输出然后在浏览器测健康检查接口http://localhost:8642/health正常应返回{status:ok}。如果返回 401说明 API Server 开了鉴权但 Web UI 没填密钥两边对齐即可。健康检查通过后打开 http://localhost:8648 在 Web UI 里发一条消息看是否正常流式返回。日志检查是排障的核心。Gateway 窗口的日志会打印每次请求的模型、耗时、状态码。如果 Web UI 显示未连接但 health 接口正常多半是 Web UI 的 API 地址配置指向了错误端口。Web UI 默认连 8642Gateway 默认监听 8642这两个别搞混。再补一个验证动作让 Agent 执行一次文件操作比如让它创建一个测试文件然后去对应目录看文件是否真的存在。如果 Agent 说创建成功但你看不到说明它用了容器后端执行hermes config set terminal.backend local切回本地重启 Gateway 再试。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错部署过程里报错集中在几个点我按真实遇到的顺序列出来。401 Unauthorized最常见。三种可能——Key 填错、Key 过期、Base URL 和 Key 不匹配。先确认配置文件里的base_url是 https://taotoken.net/api 再确认 Key 是从控制台新建的。如果 Web UI 报 401 而命令行正常是 API Server 的密钥没同步到 Web UI 设置里。local proxy failed通常是网络层问题请求没出去。检查 Base URL 是否可达用 curl 测一下curl -I https://taotoken.net/api如果连不上是本地网络或 DNS 的问题跟 Hermes 无关。reading choices 报错模型返回体里没有choices字段说明请求打到了非兼容接口。九成是 Base URL 填成了官网地址而不是 API 地址。改回 https://taotoken.net/api 即可。OAuth 相关报错如果你在配置里误选了需要 OAuth 的 provider会卡在授权环节。Hermes 里选 custom (direct API) 就不走 OAuth直接用 Key。检查hermes model里选的是不是 custom。Service installation not supported on this platformWindows 原生不支持 Gateway 后台服务改用前台窗口跑别用hermes gateway install。Failed to spawn shell /bin/bash: File not foundGit Bash 没装或没进 PATH。装 Git for Windows 并把 bin 目录加进系统 PATH或者直接切 WSL2。API call failed: Arrearage账户欠费去控制台充值结清。WSL2 里 clone 仓库 TLS 错误网络访问 GitHub 不稳换镜像源拉取或者多试几次。排查顺序建议先 curl 测 Base URL 通不通再看配置文件三件套对不对最后看 Gateway 日志里的具体状态码。大部分问题在前两步就能定位。6. 接入文档与后续动作部署跑通之后你手上应该有一个能对话、能执行任务的本地 Agent 了。接下来如果要接消息平台、调更多模型、或者把 Gateway 挂成长期服务建议把接入文档过一遍里面把 Base URL、Key、Model ID 的对应关系讲得更细。需要新建或轮换 Key去 API Keys 页面操作想先验证模型效果用模型对话页面直接测打算长期跑编码类 Agent 任务看 Coding Plan 更合适。这几个入口都在控制台里按需取用。最后留一个实用习惯每次改完配置文件先重启 Gateway 再测别在旧进程上反复试。Hermes 的配置是启动时加载的改了不重启等于没改。这个坑我踩过不止一次写在这里帮你省点时间。