Hermes Agent MCP配置指南:从安装到调用Agent工具包全流程完整指南

作者：袖梨 2026-10-15

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Hermes Agent MCP配置指南:从安装到调用Agent工具包全……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

在这个场景下，Hermes Agent 由 Nous Research 出品，安装后借助本地 Web UI 操作，不需手工编辑设置文件。本文以 Hermes Agent v0.20.0 在这个场景下，为例，不同小版本的菜单文案可能略有差异，路径以「侧边栏 → MCP → ADD SERVER」为准。

接入信息

项目	内容
客户端	Hermes Agent 桌面版
设置入口	侧边栏 MCP → ADD SERVER
本地访问地址	`（链接已移除）`
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 --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

此时用浏览器打开 （链接已移除），就能看到 Hermes Agent 的 Web UI。

实际处理时，启动 Hermes 的这个终端窗口要一直开着。关掉窗口或按 Ctrl+C，Web UI 会立即停止服务，页面就会打不开。

9119 只本机回环地址，属于本地服务。除非你明确知道风险，不要把端口转发或暴露到公网。

后续需升级版本时，能够在侧边栏底部点 Update Hermes；如果仪表盘无响应，也能够用 Restart Gateway 重新拉起本地网关。

3. 准备 API Key

在这个场景下，Agent 工具包是远程 MCP 服务，需采用真实 API Key 才能连接同时调用工具。

打开 Agent 工具包控制台的 API Key 页面
落到代码里，新建一把新的 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	`（链接已移除）`
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。