1. 为什么我最后把 Hermes Agent 留在了本地
第一次接触 Hermes Agent 的时候，我其实没抱太大期待。AI 智能体平台这两年冒出来太多，装完能跑、跑完能用的没几个。Hermes Agent 是 Nous Research 出的开源智能体框架，简单说就是：你给它一个模型 API Key，它就能在本地起一个带 Web UI 的智能体平台，能聊天、能调工具、能挂消息网关、能跑定时任务。适合谁？适合想在自己机器上快速验证 Agent 能力、又不想被 Docker 编排和一堆环境变量折磨的开发者。
我试过在 Windows + WSL 里从零装一遍，整个过程最花时间的不是安装本身，而是搞清楚 Web UI 到底监听哪个端口、模型 Key 该填在哪一层。这篇就把这条路径完整走一遍：依赖清单、可复制的安装命令、配置文件片段、启动后访问 Web UI、创建第一个智能体对话的验证动作。目标很明确——10 分钟内确认平台可用。
需要提前说清楚一件事：Hermes Agent 本身是框架，它不绑定某一家模型服务。你可以接 Claude、OpenAI，也可以接兼容 OpenAI 协议的国内模型网关。我这次演示用的是 TaoToken 的 API 作为模型后端，因为它同时提供 Claude Code 和 OpenAI 兼容两种接入方式，配置起来比较省事。下面所有命令和配置都可以直接抄。
环境前提只有三条：一台能跑 Node.js 的机器（Windows 用 WSL、macOS、Linux 都行），Node.js 18 以上，以及一个可用的模型 API Key。不需要 Docker，不需要单独装数据库，Hermes 默认用本地 SQLite 存会话和记忆。
2. 装 Hermes Agent 前先把模型入口配好
很多人卡在第一步不是因为 Hermes 装不上，而是装完之后模型调不通。所以我把顺序调一下：先把模型入口准备好，再装 Hermes。这样装完直接就能对话，不用来回改配置。
我用的模型入口是 TaoToken。它的官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。注意 API 地址后面不加任何参数，直接就是根路径。它兼容 OpenAI 的/v1/chat/completions和 Anthropic 的/v1/messages两种协议，所以 Hermes 里无论选 OpenAI 还是 Claude 类型都能接。
先去控制台拿 Key。打开 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 页面创建一个新 Key。创建时建议给它起个能认出来的名字，比如hermes-local，方便以后区分。Key 只在创建时完整显示一次，复制下来存好。
拿到 Key 之后，先别急着装 Hermes，用 curl 验证一下这个 Key 能不能正常调模型。这一步能省掉后面 80% 的排障时间：
curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "claude-3-5-sonnet-20241022", "messages": [{"role": "user", "content": "只回复两个字：可用"}], "max_tokens": 16 }'如果返回的 JSON 里choices[0].message.content是「可用」，说明 Key 和网络都没问题。如果返回 401，说明 Key 复制错了或者被禁用；如果返回 404，检查一下 URL 是不是写成了/api/v1/chat/completions，少一个v1就会 404。
模型 ID 这块要注意：TaoToken 的模型列表在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 可以查到。Claude 系列用claude-3-5-sonnet-20241022这种带日期的完整 ID，OpenAI 系列用gpt-4o这种短 ID。Hermes 的配置向导里会让你填模型名，填错的话启动后对话会报model not found。
如果你打算长期跑 Agent 任务，比如定时任务、多轮工具调用，可以考虑 TaoToken 的 Coding Plan，它在长上下文和连续调用场景下更划算，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。不过第一次上手先用按量计费的 Key 就够了，跑通再说。
3. 可复制的安装与配置文件片段
现在开始装 Hermes Agent。官方安装脚本是一行命令，但国内网络直接跑容易卡在下载环节，所以我建议先配好 npm 镜像再装。
第一步，确认 Node.js 版本：
node -v npm -v如果低于 18，先升级。WSL 里可以用 nvm 装：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20第二步，配 npm 镜像并安装 Hermes：
npm config set registry https://registry.npmmirror.com npm install -g hermes-agent装完后跑健康检查：
hermes doctor你会看到一串检查项，包括 Node 版本、配置文件、模型连通性。第一次跑的时候模型那项大概率是红的，因为还没配 Key。
第三步，写配置文件。Hermes 的配置默认在~/.hermes/config.toml，你也可以用hermes setup走向导，但向导有时候会覆盖已有配置，所以我更推荐直接写文件。下面这份是我实测能跑通的配置，路径和字段名都跟当前版本一致：
# ~/.hermes/config.toml [model] provider = "openai" base_url = "https://taotoken.net/api/v1" api_key = "sk-你的Key" model = "claude-3-5-sonnet-20241022" max_tokens = 4096 temperature = 0.7 [web] enabled = true host = "0.0.0.0" port = 8648 [memory] enabled = true backend = "sqlite" path = "~/.hermes/memory.db" [gateway] enabled = false几个关键点解释一下。provider填openai是因为 TaoToken 的/v1/chat/completions走 OpenAI 协议，即使底层模型是 Claude 也这么填。base_url一定要带/v1，这是 OpenAI SDK 的约定，少了会 404。model填你在 TaoToken 模型列表里看到的完整 ID。web.port默认就是 8648，如果你机器上这个端口被占了，改成 8649 之类的。
如果你更习惯用 Claude 原生协议，也可以把 provider 改成anthropic，base_url 改成https://taotoken.net/api，model 不变。两种方式我都试过，OpenAI 协议在 Hermes 里兼容性更好，工具调用更稳。
第四步，装 Web UI。Hermes 本体自带命令行，但 Web UI 是单独一个包：
npm install -g hermes-web-ui hermes-web-ui start启动成功会打印一行Web UI running at http://localhost:8648。如果你在 WSL 里跑，Windows 浏览器直接访问http://localhost:8648就能打开，WSL2 会自动做端口转发。
4. 启动后验证 Web UI 与首个智能体对话
Web UI 起来之后，先别急着建 Agent，按顺序做三个验证动作，确认整条链路是通的。
第一个动作：打开http://localhost:8648，你应该看到一个左侧栏 + 中间对话区的面板。左侧栏顶部有「Agents」「Sessions」「Skills」「Settings」几个入口。如果页面白屏，按 F12 看 Console，大概率是hermes-web-ui没连上后端，检查hermes主进程有没有在跑。
第二个动作：进 Settings，确认模型配置读到了。这里会显示当前 provider、base_url、model。如果显示的是空或者默认值，说明~/.hermes/config.toml没被读到，检查文件路径和 TOML 语法。TOML 对引号很敏感，字符串必须用双引号。
第三个动作：创建一个最小 Agent 并对话。点左侧「Agents」→「New Agent」，填三个字段：
| 字段 | 填什么 | 说明 |
|---|---|---|
| Name | test-agent | 随便起，后面能改 |
| Model | claude-3-5-sonnet-20241022 | 跟 config.toml 里一致 |
| System Prompt | 你是一个简洁的助手，回答不超过三句话。 | 先简单点 |
保存后回到对话区，选中test-agent，输入「你好，介绍一下你自己」。正常的话你会看到 SSE 流式输出，字一个一个蹦出来。如果卡住不动，看终端里hermes进程有没有报错。
再做一个工具调用验证。在对话里输入「现在几点？用工具查一下」。Hermes 内置了时间工具，正常会触发一次 tool call，返回当前时间。这一步能验证模型是否支持 function calling。如果模型返回的是纯文本「我无法获取时间」，说明你用的模型 ID 不支持工具调用，换gpt-4o或claude-3-5-sonnet再试。
到这里，平台就算跑通了。整个过程如果网络顺利，从装 Node 到发出第一条消息，10 分钟是够的。我实测下来，最慢的一步是npm install -g hermes-agent，配了镜像之后大概 40 秒。
5. 报错排查：401、local proxy failed 与 reading choices
这一节把我踩过的坑列出来，你遇到报错直接对号入座。
401 Unauthorized。这是最常见的。原因有三个：Key 复制时带了空格、Key 被禁用、或者base_url和provider不匹配。排查方法：先用第 2 节那条 curl 命令单独测 Key，curl 通了说明 Key 没问题，问题在 Hermes 配置。重点检查config.toml里api_key那行有没有多余引号嵌套，比如api_key = ""sk-xxx""这种。
local proxy failed / connection refused。这个报错通常出现在你本地开了某个网络工具，Hermes 的请求被拦了。解决方法是检查环境变量HTTP_PROXY和HTTPS_PROXY，如果设了但代理没开，请求就会 refused。临时清掉：
unset HTTP_PROXY unset HTTPS_PROXY hermes restartError reading choices / choices is undefined。这个报错说明模型返回的 JSON 结构跟 Hermes 预期的不一样。常见原因是base_url少写了/v1，请求打到了根路径，返回的是 HTML 而不是 JSON。检查base_url = "https://taotoken.net/api/v1"这一行。另一个原因是模型 ID 写错了，服务端返回了错误对象，里面没有choices字段。用 curl 单独测一下你填的那个 model ID。
OAuth token expired。如果你在 Hermes 里配了 Claude 的 OAuth 登录而不是 API Key，会碰到这个。OAuth token 有效期短，过期后要重新授权。我的建议是本地开发直接用 API Key，别用 OAuth，省心。TaoToken 的 Key 是长期有效的，不存在过期问题。
Web UI 打不开，端口 8648 被占用。先查谁占了：
lsof -i :8648如果是别的进程，改config.toml里的web.port为 8649，然后hermes restart和hermes-web-ui restart。注意两个服务都要重启，只重启一个不生效。
Agent 回复到一半断了。看终端有没有max_tokens exceeded。Hermes 默认max_tokens可能偏小，在config.toml里调到 4096 或 8192。另外 TaoToken 的 Claude 模型单次输出上限跟模型本身有关，claude-3-5-sonnet支持到 8192，填大了也没用。
如果你用的是 Cline MCP 或者 Codex 的auth.json方式接入，记住三件套必须同时对上：Base URL 填https://taotoken.net/api/v1，Key 填sk-开头那串，Model ID 填完整带日期的版本号。这三个任何一个不对，都会报上面那些错。
6. 跑通之后，下一步可以做什么
平台跑通只是起点。Hermes 真正有意思的地方在于它的记忆系统和技能市场。你可以在 Web UI 的 Skills 页面搜关键词，找到合适的技能直接装，比如网页抓取、文件处理、定时总结。装完的技能会出现在 Agent 的工具列表里，对话时模型会自动调用。
如果你想让 Agent 常驻跑任务，比如每天早上总结一次新闻，可以在 Web UI 的 Cron 页面配一个定时任务，Cron 表达式写0 9 * * *，任务内容写你的 prompt。任务触发时 Hermes 会自己调模型执行，结果存在会话历史里。
模型入口这块，如果你后面要跑大量 Agent 任务，按量计费的 Key 可能会比预期贵。TaoToken 的 Coding Plan 在连续调用场景下有更划算的计费方式，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各种协议的完整示例。API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，需要新建或吊销 Key 的时候去那里。
最后说一个我自己的习惯：每次改完config.toml，先跑hermes doctor再重启服务。doctor 会告诉你哪一项配置没生效，比直接重启然后对着报错猜要快得多。这个习惯帮我省了不少来回折腾的时间。
