Hermes Agent 从入门到上手：10分钟搭建你的 AI 智能体平台

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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加任何参数直接就是根路径。它兼容 OpenAI 的/v1/chat/completions和 Anthropic 的/v1/messages两种协议所以 Hermes 里无论选 OpenAI 还是 Claude 类型都能接。先去控制台拿 Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 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_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以查到。Claude 系列用claude-3-5-sonnet-20241022这种带日期的完整 IDOpenAI 系列用gpt-4o这种短 ID。Hermes 的配置向导里会让你填模型名填错的话启动后对话会报model not found。如果你打算长期跑 Agent 任务比如定时任务、多轮工具调用可以考虑 TaoToken 的 Coding Plan它在长上下文和连续调用场景下更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。不过第一次上手先用按量计费的 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 镜像并安装 Hermesnpm 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 改成anthropicbase_url 改成https://taotoken.net/apimodel 不变。两种方式我都试过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」填三个字段字段填什么说明Nametest-agent随便起后面能改Modelclaude-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 命令单独测 Keycurl 通了说明 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/v1Key 填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_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各种协议的完整示例。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 需要新建或吊销 Key 的时候去那里。最后说一个我自己的习惯每次改完config.toml先跑hermes doctor再重启服务。doctor 会告诉你哪一项配置没生效比直接重启然后对着报错猜要快得多。这个习惯帮我省了不少来回折腾的时间。