手把手教学，在 Hermes Agent 中接入 Agent 工具包
本教程介绍如何把远程 MCP 服务agent-toolkit接入 Hermes Agent，使 Hermes 可以直接调用 Agent 工具包提供的航班、天气、网页搜索、文档解析、图片生成等能力。
Hermes Agent 由 Nous Research 出品，安装后通过本地 Web UI 操作，不需要手工编辑配置文件。本文以Hermes Agent v0.20.0为例，不同小版本的菜单文案可能略有差异，路径以「侧边栏 → MCP → ADD SERVER」为准。
接入信息
| 项目 | 内容 |
|---|---|
| 客户端 | Hermes Agent 桌面版 |
| 配置入口 | 侧边栏MCP→ADD SERVER |
| 本地访问地址 | http://127.0.0.1:9119 |
| MCP 地址 | https://agent-toolkit.app.baizhi.cloud/mcp |
| 传输方式 | HTTP/SSE |
| 鉴权方式 | Bearer token |
| 服务名称 | agent-toolkit |
MCP 地址必须以
/mcp结尾。不要把接入指南里的占位密钥sk_******当成真实密钥填入，也不要把真实密钥发到聊天、截图或公开仓库。
1. 整体流程：一条主线看懂
- 安装 Hermes Agent，确认终端里能用
hermes命令。 - 在 CMD、PowerShell 或终端执行
hermes dashboard，启动本地 Web UI。 - 在 Agent 工具包控制台创建一把 API Key。
- 在 Hermes 的MCP页面点ADD SERVER，填入名称、传输方式、URL 和 Bearer token。
- 回到 MCP 列表点测试按钮，确认服务能列出工具。
- 在CHAT里发一句提示词，验证工具确实被调用。
安装 Hermes → hermes dashboard → 准备 API Key → MCP 页面 ADD SERVER → 测试 → CHAT 验证2. 安装并启动 Hermes
第 1 步：安装 Hermes Agent
从 Hermes 官方渠道获取安装包，按安装向导完成安装。
安装完成后，打开 CMD、PowerShell 或系统终端，输入下面的命令确认命令已经可用：
hermes --versionWindows 用户如果提示hermes不是内部或外部命令，先关闭并重新打开终端；仍然无法识别时，通常是安装目录没有加入系统 PATH，可以重新运行安装程序，或改用 Git Bash、WSL 等终端再试。
第 2 步：启动 Hermes 桌面
在同一个终端里执行：
hermes dashboard首次启动时，Hermes 会先在本地构建 Web UI，终端会输出一段构建日志。看到下面两行，说明桌面已经启动完成：
HERMES_DASHBOARD_READY port=9119 Hermes Web UI → http://127.0.0.1:9119此时用浏览器打开http://127.0.0.1:9119，就能看到 Hermes Agent 的 Web UI。
启动 Hermes 的这个终端窗口要一直开着。关掉窗口或按 Ctrl+C，Web UI 会立即停止服务，页面就会打不开。
9119只监听本机回环地址，属于本地服务。除非你明确知道风险，不要把端口转发或暴露到公网。
后续需要升级版本时，可以在侧边栏底部点Update Hermes；如果仪表盘无响应，也可以用Restart Gateway重新拉起本地网关。
3. 准备 API Key
Agent 工具包是远程 MCP 服务，需要使用真实 API Key 才能连接并调用工具。
- 打开 Agent 工具包控制台的 API Key 页面：https://agent-toolkit.app.baizhi.cloud/api-keys
- 创建一把新的 API Key，并按照使用场景选择合适的工具分组，例如航班查询、机场天气、网页搜索或图片生成。
- 创建后立即复制密钥，并妥善保存。
后续配置时，把示例里的sk_xxxxxxxxxxxx整段替换成这把真实密钥；不要保留占位字符，也不要在密钥前后多打空格。
4. 在 Hermes 中配置 MCP 服务
第 1 步：打开 MCP 配置页
在 Hermes Web UI 左侧菜单中点击MCP，进入 MCP 服务页。页面会显示当前已配置的服务列表，以及一段可一键安装的推荐服务列表。
第 2 步：点击 ADD SERVER 并填写配置
点击页面右上角的ADD SERVER，按下面的表格填写弹窗中的四个字段：
| 字段 | 填写内容 |
|---|---|
| NAME | agent-toolkit |
| TRANSPORT | HTTP/SSE |
| URL | https://agent-toolkit.app.baizhi.cloud/mcp |
| AUTHENTICATION | Bearer token |
| BEARER TOKEN | 你的真实 API Key，例如sk_xxxxxxxxxxxx |
填写时有几个容易出错的点：
- TRANSPORT要保持默认的
HTTP/SSE，不要选成stdio。 - AUTHENTICATION默认是
None，必须手动切换成Bearer token，否则会出现「能连上、但一调用就报鉴权失败」的情况。 - URL必须完整，结尾是
/mcp，不要漏掉路径，也不要多写一个斜杠。
弹窗底部会提示密钥的保存位置：真实 token 存在当前 profile 的
.env里，config.yaml只保留一条环境变量引用。所以以后要换密钥，应该在界面里改，而不是只去改config.yaml。
第 3 步：保存服务
确认四个字段无误后点击ADD，服务会出现在Your MCP servers列表中，右侧的Disable开关表示当前启用状态。
5. 测试并验证
第 1 步：测试服务连接
在服务列表里找到agent-toolkit，点击该行右侧的测试按钮（闪电图标）。测试通过后，服务条目下方会直接列出从 Agent 工具包拉取到的工具清单。
看到Tools:后面开始出现flight_prices、airport_weather、websearch_aisearch、image_generate_text_to_image、docparse_parse等工具名，就说明这一步已经通过。
如果显示为空、报错或一直是失败状态，先确认 URL、传输方式和 Bearer token 三项都正确，再点一次测试按钮。
第 2 步：在 CHAT 中用提示词验证
回到左侧菜单的CHAT，新建一个会话，发送一个明确要求使用该服务的提示词，例如：
请使用 agent-toolkit 里的天气工具，查询北京首都机场未来几天的天气，并简要说明适合携带的衣物。验证时重点看这几点：
- 执行过程中是否出现了对
agent-toolkit工具的调用，而不是只凭模型已有知识作答； - 工具返回结果后，Hermes 是否继续把结果整理成可读的答案；
- 回答里是否带有查询日期、信息来源，以及「待确认」这类不确定信息。
6. 案例：用 Hermes 调用 Agent 工具包做旅行规划
配置完成后，可以直接在 CHAT 里输入下面的提示词，Hermes 会根据任务需要调用 Agent 工具包的航班、天气、网页搜索等工具，再把结果整理成一份旅行计划。
我计划 [人数] 人从 [出发地] 去 [目的地]，[出发日期] 出发，[返程日期] 返回。 旅行偏好是 [省钱 / 少换乘 / 慢慢逛]，住宿希望在 [区域或预算]。 请使用 agent-toolkit 完成以下任务： 1. 查询往返航班，比较价格低、全程直飞和时间较合适的方案； 2. 查询到达机场的天气； 3. 选择一组推荐航班，并整理机场到住宿区域的交通建议； 4. 用 Markdown 输出出发前清单、往返时间线和 3—5 个主要景点的顺路安排。 请标注查询日期和信息来源。价格、航班和景点开放时间可能变化；查不到的信息写「待确认」，不要编造。一次常见的调用链如下，具体调用哪些工具取决于目的地、日期和当前密钥的工具分组：
| 查询内容 | 可能调用的工具 |
|---|---|
| 确认城市或机场代码 | city_search、airport_search |
| 查询往返航班和价格 | flight_prices |
| 查询中转路线 | flight_transfers |
| 查询机场天气 | airport_weather |
| 搜索景点和交通补充信息 | websearch_aisearch、web_extract |
| 生成行程图或配图 | image_generate_text_to_image |
检查计划是否可用时，重点看：是否明确调用了agent-toolkit；是否比较了多组航班再说明推荐理由；选定航班后，时间线、机场接驳和行程是否始终使用同一组航班；机票、签证、景点开放时间等易变信息是否被标为出发前复核项。
7. 常见问题
| 现象 | 处理方式 |
|---|---|
提示hermes不是内部或外部命令 | 关闭并重新打开终端；仍不识别时，重新运行安装程序，确认安装目录已加入系统 PATH。 |
浏览器打不开127.0.0.1:9119 | 确认执行hermes dashboard的终端窗口还开着；窗口被关掉或按过 Ctrl+C 时，重新执行一次启动命令。 |
| 端口 9119 被占用 | 关掉占用该端口的旧进程，或先结束上一次没有正常退出的 Hermes 进程，再重新启动。 |
MCP 列表里看不到agent-toolkit | 确认 ADD 弹窗里点过ADD并保存成功；必要时刷新页面或重启一次 Hermes。 |
| 服务显示失败或调用报鉴权错误 | 检查 URL 是否以/mcp结尾，TRANSPORT是否为HTTP/SSE，AUTHENTICATION是否已从None改成Bearer token，以及密钥是否完整、没有多余空格。 |
| 已连接但工具列表为空 | 点测试按钮重新拉取；仍为空时，检查这把 API Key 的分组是否包含你需要的那组工具。 |
| 换了密钥却不生效 | 到 MCP 页面重新编辑该服务并保存；密钥存在当前 profile 的.env中，只改config.yaml不会生效。 |
| API Key 泄露 | 立即在 Agent 工具包控制台作废旧密钥并重新生成，然后回到 MCP 页面更新 Bearer token。 |
8. 安全建议
- 不要把 API Key 写进项目代码、提交到 Git 或发布到公开截图中。
- Hermes 的 profile 目录里包含可直接调用服务的密钥，不要把这个目录上传到公开仓库。
9119是本地回环地址，默认只服务本机；不要为了图方便把它映射到公网端口。- 只为当前用途选择必要的工具分组，避免给不需要的工具开放额度。
- 旅行计划中的航班、票价、签证、景点开放时间和交通信息会变化，出发前应通过订单、航空公司和官方渠道再次确认。
完成以上步骤后，Hermes Agent 就可以通过远程 MCP 使用 Agent 工具包。以后如果工具清单发生变化，通常只需要保持 MCP 服务启用并重新测试一次，不必重复安装。
