Hermes Agent 完整使用教程：CLI、MCP 与 Gateway 配置到 TaoToken

1. 为什么第一次用 Hermes Agent 会卡在“连不上模型”

Hermes Agent 是一个把 CLI、Gateway、MCP、cron 揉在一起的 agent 运行时。它能读写文件、跑终端命令、定时执行任务，还能通过 MCP 把外部系统接成工具。适合谁？适合已经厌倦了“聊天窗口里复制粘贴代码”的开发者，尤其是想让 agent 长期在线、按计划干活的人。

但第一次上手，十有八九会卡在同一个地方：模型通道。你装完 CLI，敲hermes进去，发一句“总结当前目录”，结果要么转圈，要么报401，要么提示local proxy failed。原因不复杂——Hermes 默认要你配一个 provider，而 provider 的 base URL、API Key、模型 ID 三件套，对新手来说就是第一道墙。

我试过的路径是：把 Hermes 的 endpoint 和鉴权统一改到 TaoToken 的 API 通道上，一个 Key 管住 CLI、MCP 触发的模型调用、以及 Gateway 转发。这样你不需要在.env里堆五六个不同厂商的 Key，也不用担心某个 provider 突然限流。

这篇教程按三条主线走：CLI 安装与初始化、MCP 工具接入、Gateway 转发配置。最后用一个 cron 定时任务跑通端到端调用，证明整条链路是活的。每一步都给可复制的命令和配置片段，你照着敲就行。

先明确一个概念：Hermes 的“模型调用”发生在 agent 层，不管你是从 CLI 发起的，还是 Gateway 从消息平台转发进来的，还是 cron 在后台触发的，最终都要走 provider 配置。所以只要把 provider 这一层统一到 TaoToken，后面所有入口都自动生效。这就是为什么值得先花十分钟把通道配好，而不是每个入口单独折腾。

TaoToken 在这里的角色是统一 Key/API 通道：官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。你拿到一个 Key，填进 Hermes 的.env，再把 base URL 指过去，模型 ID 用通道支持的名称，就通了。

2. 前置准备：拿到 TaoToken Key 并理解 Hermes 的配置分层

在动 Hermes 之前，先把 TaoToken 这边的准备工作做完。打开 https://taotoken.net/api-keys ，创建一个 API Key。这个 Key 就是后面.env里的核心凭证。创建时建议起个能认出来的名字，比如hermes-dev，方便以后轮换。

拿到 Key 之后，先别急着改 Hermes。你要理解 Hermes 的配置分两层，这决定了你该把东西写在哪：

第一层是~/.hermes/.env，放的是 API Key、base URL、平台 token 这类环境变量。它管的是“连哪个通道、用什么凭证”。

第二层是~/.hermes/config.yaml，放的是结构化行为配置，比如 MCP server 声明、toolset 默认值、gateway 平台开关。它管的是“agent 怎么干活”。

模型相关的三件套——Base URL、Key、Model ID——全部落在.env里。这是最容易搞混的地方：很多人以为模型要在config.yaml里配，结果改了半天没生效。记住，provider 凭证走.env。

如果你还没装 Hermes，先装。官方脚本最快：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.bashrc hermes version

如果你打算改仓库源码，用开发安装：

git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent uv venv venv --python 3.11 source venv/bin/activate uv pip install -e ".[all,dev]"

装完先跑一次hermes doctor，它会告诉你哪些依赖缺了、配置目录在哪。默认配置目录是~/.hermes/，你需要关注的三个文件是config.yaml、.env、SOUL.md。SOUL.md是 Hermes 的长期风格文件，先不用动。

现在打开.env，把 TaoToken 的三件套写进去。下面这段是核心，路径和变量名要和 Hermes 实际读取的一致：

# ~/.hermes/.env OPENAI_API_KEY=你的_TaoToken_Key OPENAI_BASE_URL=https://taotoken.net/api

这里用OPENAI_*前缀是因为 Hermes 的 OpenAI 兼容 provider 会读这两个变量。TaoToken 的 API 入口是 OpenAI 兼容格式，所以 base URL 填https://taotoken.net/api，注意结尾不要多加/v1，Hermes 会自己拼路径。如果你填成https://taotoken.net/api/v1，很可能出现 404 或者路径重复。

模型 ID 不在.env里写死，而是通过hermes model或者会话内的/model来选。但你要知道通道支持哪些模型名。可以在 https://taotoken.net/doc 查当前可用的模型列表，或者直接在模型对话页 https://taotoken.net/models 里试一下哪个模型名能通。

配完之后验证一下环境变量有没有被读到：

hermes status

如果它显示当前 provider 是 openai 兼容、base URL 指向 taotoken，说明.env生效了。如果还显示默认的 openrouter，检查你是不是把变量名写错了，或者.env文件路径不对。

这一步做完，你手里就有了一个统一的模型通道。接下来 CLI、MCP、Gateway 全都复用这个通道，不需要重复配 Key。

3. 可复制配置：CLI 初始化、MCP 声明与 Gateway 转发

这一节是全文的核心，给三份可直接复制的配置。先做 CLI 初始化，再配 MCP，最后配 Gateway。

3.1 CLI 初始化与模型选择

首次安装后跑一次 setup：

hermes setup

它会引导你选 provider、terminal backend、gateway 平台、toolset。provider 这一步选 OpenAI 兼容，它会去读你.env里的OPENAI_API_KEY和OPENAI_BASE_URL。如果你在 setup 里被要求填 base URL，直接填https://taotoken.net/api。

setup 完成后，进 CLI：

hermes

进去先跑/model，看看当前模型是什么。然后切到通道支持的模型：

/model custom:你的模型ID

比如通道里如果有claude-sonnet这类名称，就填对应的 ID。切完发一句带动作的任务，别发“你好”：

阅读当前目录结构并总结这个仓库的核心组成。

如果 Hermes 开始调用 file 或 terminal 工具，说明 CLI 这条链路通了。你可以用/verbose观察工具输出，用/usage看 token 消耗。

3.2 MCP 服务声明片段

MCP 是把外部系统接成 Hermes 工具的方式。配置文件是~/.hermes/config.yaml，注意键名是mcp_servers，不是mcp.servers。这是很多人踩的坑，写错了 MCP 根本不加载。

下面是一个 stdio 类型的 MCP 声明，接的是文件系统服务：

# ~/.hermes/config.yaml mcp_servers: filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"] tools: include: [read_file, write_file, list_directory] prompts: false resources: false

再给一个 HTTP 类型的 MCP 声明，接内部 API：

mcp_servers: company_api: url: "https://mcp.internal.example.com" headers: Authorization: "Bearer 你的内部token" tools: include: [query_orders, get_user]

改完配置后，在 CLI 里执行：

/reload-mcp

然后/tools list看新工具有没有出现。如果没出现，先检查mcp_servers键名，再检查npx命令在不在 PATH 里。stdio 类型的 MCP 依赖本地命令，命令不存在就会静默失败。

这里有个原则：内置工具够用就别上 MCP，只是流程复杂就用 skill，确实要接外部系统才用 MCP。MCP 开太多会让工具列表膨胀，模型选择工具时更容易出错。

3.3 Gateway 转发配置

Gateway 让 Hermes 通过消息平台长期在线。核心命令：

hermes gateway setup hermes gateway run

平台 token 写在.env里，比如 Telegram：

# ~/.hermes/.env TELEGRAM_BOT_TOKEN=你的bot_token TELEGRAM_ALLOWED_USERS=你的用户ID

授权控制必须做，别开放所有用户。TELEGRAM_ALLOWED_USERS填你的用户 ID，只有你能触发 agent。

Gateway 跑起来后，进入对应聊天，执行/sethome。这一步很关键，cron 和后台任务的结果才知道发去哪里。没有 home channel，定时任务跑完你收不到通知。

Gateway 的模型调用同样走.env里的 TaoToken 通道，不需要额外配。这就是统一通道的好处：CLI 配一次，Gateway 自动继承。

4. 验证请求：用 cron 定时任务跑通端到端调用

配置写完不算通，要有一个真实的端到端动作来验证。最合适的是 cron 定时任务，因为它同时经过 provider 通道、agent 调度、工具调用和 Gateway 通知四条链路。

先创建一个 cron job。Hermes 的 cron 不是系统计划任务，而是在新 session 里跑一个 agent 任务。所以 prompt 必须完全自包含，不能依赖当前会话的上下文。

hermes cron create "*/5 * * * *" "读取 /home/user/projects/status.txt 的内容，如果里面有 ERROR 字样，把内容发送到 home channel；如果没有 ERROR，回复 [SILENT]。" --name "error-watch"

这条 cron 每 5 分钟跑一次。注意 prompt 里显式约定了[SILENT]，这样没有异常时不会刷屏。这是自动化任务的一个好模式：脚本负责抓数据，agent 负责判断和总结。

创建后在 CLI 里查看：

/cron list

手动触发一次，不用等 5 分钟：

/cron run <job_id>

观察输出。如果 agent 成功读取文件、判断内容、并决定是否发送，说明整条链路通了。你可以故意在status.txt里写一行ERROR: disk full，再手动触发，看 home channel 有没有收到消息。

如果这一步成功，你实际上验证了：TaoToken 通道能调通模型、Hermes 的 provider 配置正确、cron 调度正常、Gateway 通知可达。这比单纯在 CLI 里聊两句有说服力得多。

再验证一个后台任务：

/background 总结这个仓库的工具系统并写一份建议。

后台任务会把当前任务异步化，不阻塞你的会话。跑完后用/status看结果。

到这里，CLI、MCP、Gateway、cron 四条线都跑通了。你可以把 cron 的 prompt 换成自己的监控逻辑，比如检查构建状态、汇总日志、定时生成报告。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

配通道的过程中，报错基本集中在几个固定位置。下面按真实报错对照排查。

401 Unauthorized

最常见。原因通常是.env里的OPENAI_API_KEY没被读到，或者 Key 填错了。先跑hermes status确认 provider 和 base URL。然后检查.env文件路径是不是~/.hermes/.env，变量名是不是OPENAI_API_KEY。如果你在 setup 里选了别的 provider，它可能读的是OPENROUTER_API_KEY，那就把 Key 填到对应变量里，或者重新 setup 选 OpenAI 兼容。

local proxy failed

这个报错通常出现在 base URL 指向了本地地址，但本地没有服务在跑。检查OPENAI_BASE_URL是不是被改成了http://localhost:xxxx。如果你要用 TaoToken，应该是https://taotoken.net/api。另外检查有没有残留的代理环境变量，比如HTTP_PROXY，它们会干扰请求。

reading choices 相关报错

这类报错说明请求发出去了，但返回的 JSON 结构不符合预期。常见原因是 base URL 路径拼错，比如填了https://taotoken.net/api/v1导致路径重复，返回的不是标准 chat completions 结构。把 base URL 改回https://taotoken.net/api，让 Hermes 自己拼/v1/chat/completions。

OAuth 相关报错

如果你在 MCP 或 Gateway 里用了需要 OAuth 的服务，报错会提示 token 过期或 scope 不足。MCP 的 HTTP 类型如果带Authorizationheader，检查 token 有没有过期。Gateway 的平台 token 如果失效，重新生成并更新.env，然后hermes gateway stop再hermes gateway start。

MCP 工具不出现

先确认config.yaml里键名是mcp_servers。然后确认 stdio 类型的command在 PATH 里存在。最后执行/reload-mcp。三步都做了还不出现，用/verbose看加载日志。

cron 跑了但没收到通知

检查有没有执行/sethome。没有 home channel，cron 结果无处可发。另外检查 prompt 里有没有[SILENT]约定，如果 agent 判断为静默，它就不会发消息。

排查时不要一上来就删整个~/.hermes。大多数问题都能局部定位：先看hermes doctor，再看hermes status，然后看具体报错属于哪一层。安装层、provider 层、tool 层、MCP 层、Gateway 层，逐层排除。

6. 把通道固定下来：长期使用与 CTA

跑通之后，建议做几件事让长期使用更稳。

第一，用 profile 隔离环境。工作、个人、实验分开，别混在一个实例里：

hermes profile create work --clone hermes profile use work

profile 隔离的是整套 Hermes home，包括配置、技能、会话、memory、gateway 状态。这样你换项目时不会互相污染。

第二，重要规则写进AGENTS.md，别依赖聊天记录。项目约束、测试要求、架构规则，写一次，之后每次会话自动带上。但别写成百科全书，太长会稀释重点、增加成本。

第三，长会话定期看/usage，必要时/compress。Hermes 依赖稳定的系统提示前缀来命中缓存，频繁改模型、改系统提示、改上下文文件会提高成本。

第四，对不可信代码用隔离环境，优先 Docker 这类方案，而不是默认本地 terminal。

如果你还没拿到 Key，去 https://taotoken.net/api-keys 创建一个。接入文档在 https://taotoken.net/doc ，里面有完整的 base URL 和模型 ID 说明。想先试模型通不通，用模型对话页 https://taotoken.net/models 。如果你打算长期跑编码和 Agent 任务，Coding Plan 页面 https://taotoken.net/coding-plan 有更细的通道说明。

把.env里的三件套固定下来——Base URL 填https://taotoken.net/api，Key 填你的 TaoToken Key，Model ID 用通道支持的名称——CLI、MCP、Gateway、cron 全部复用这一套。以后换模型只改 Model ID，换 Key 只改一处，不用每个入口重新配。