Hermes Agent 安装与 MCP 配置教程

手把手教学，在 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. 整体流程：一条主线看懂

1. 安装 Hermes Agent，确认终端里能用 hermes 命令。
2. 在 CMD、PowerShell 或终端执行 hermes dashboard，启动本地 Web UI。
3. 在 Agent 工具包控制台创建一把 API Key。
4. 在 Hermes 的 MCP 页面点 ADD SERVER，填入名称、传输方式、URL 和 Bearer token。
5. 回到 MCP 列表点测试按钮，确认服务能列出工具。
6. 在 CHAT 里发一句提示词，验证工具确实被调用。

安装 Hermes  →  hermes dashboard  →  准备 API Key
    →  MCP 页面 ADD SERVER  →  测试  →  CHAT 验证

2. 安装并启动 Hermes

第 1 步：安装 Hermes Agent

从 Hermes 官方渠道获取安装包，按安装向导完成安装。

安装完成后，打开 CMD、PowerShell 或系统终端，输入下面的命令确认命令已经可用：

hermes --version

Windows 用户如果提示 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 才能连接并调用工具。

1. 打开 Agent 工具包控制台的 API Key 页面：https://agent-toolkit.app.baizhi.cloud/api-keys
2. 创建一把新的 API Key，并按照使用场景选择合适的工具分组，例如航班查询、机场天气、网页搜索或图片生成。
3. 创建后立即复制密钥，并妥善保存。

后续配置时，把示例里的 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 服务启用并重新测试一次，不必重复安装。