Hermes Agent 配置怎么做：model、tools、gateway 和 config.yaml 排查指南

Hermes Agent 配置指南：model、tools、gateway 和 config.yaml 怎么接起来

如果 Hermes Agent 已经装好了，后面最容易卡住的部分通常是 ~/.hermes/ 这个目录里的配置。官方把大部分设置都放到了这里：config.yaml 放模型、终端、工具、压缩这些非敏感设置，.env 放 API key、bot token 和密码，SOUL.md 负责 agent 的基础身份，sessions/ 和 logs/ 则留给会话和排错。先把这几个位置分清，后面碰到“模型能聊天，但命令跑不了”或者“CLI 正常，gateway 里行为不一样”这类问题时，排查范围会小很多，也不用反复重装。

配置顺序也不需要一上来铺满。初次配置时，可以先把模型入口定下来，再确认命令到底跑在本地、Docker 还是 SSH，接着补工具和消息入口，最后再去调 subagent、上下文压缩和其它细项。Hermes 官方把 hermes model、hermes tools、hermes gateway setup、hermes config check、hermes config migrate 这些命令拆开，本身就在引导这种顺序。很多时候先用 hermes config 看当前值，再用 hermes config set 改一两项，会比直接打开很长的 YAML 更快。官方文档还单独写了这条命令的分流规则，API key 这类内容会自动写进 .env，其它设置则进入 config.yaml，所以很多小改动可以直接在命令行里完成。

模型这一层，先做到能稳定起会话就够了。Hermes 现在已经把 Nous、OpenAI Codex、Anthropic、GitHub Copilot、OpenRouter 以及 Kimi、MiniMax、GLM、DashScope 这类 provider 都接进了统一的入口，只要至少配好一个 provider，就能开始工作。官方给的口径很清楚：密钥放 .env，模型名、provider、base_url、context_length 这类非敏感设置放 config.yaml。如果你用的是官方支持的 provider，先跑一遍 hermes model 会快一些；如果你接的是自建端点、本地模型或局域网服务，再手动补 base_url 和 context_length 会更合适。尤其是本地模型，context 长度如果不写清楚，前几轮看着正常，工具调用一多，历史内容就容易被挤掉。

model:
  provider: "kimi-coding"
  default: "kimi-for-coding"

terminal:
  backend: local
  cwd: "."
  timeout: 180

# ~/.hermes/.env
KIMI_API_KEY=your-key

模型配好以后，Hermes 还不能立刻改文件或跑命令。命令是否能执行，还取决于 terminal.backend 和工具开关。刚开始配置时，先把 terminal.backend 留在 local 会更直接，因为你先要确认 CLI 里的 terminal、read_file、patch 这些基础能力都能正常调用，再决定要不要切去 Docker 或 SSH。工具这一层也别忽略，Hermes 把能力按 toolset 分组，可以用 hermes tools 逐个平台去开关。CLI 和 gateway 的工具开关是分开管理的，你在 CLI 里能用到的工具，到了 Telegram、Discord 或 Slack 里不一定已经打开，所以如果你准备把 Hermes 接进消息入口，最好单独看一遍对应平台的工具配置。

消息入口还有一个更常见的误差，在工作目录。CLI 的默认目录，就是你运行 hermes 时所在的位置；gateway session 的默认目录却是用户 home，官方文档也明确写了这一点。如果你在终端里进项目目录测试过，一切正常，换到 Telegram 或 Discord 以后却突然找不到仓库，多半是 MESSAGING_CWD 没设。MESSAGING_CWD 主要影响 gateway 会话从哪里开始，TERMINAL_CWD 则影响所有 terminal session 的默认目录。这两个变量分开写清楚以后，CLI 和消息入口就不会各跑各的目录，后面做项目协作也更容易复现问题。

到这一步以后，再去补 SOUL.md、项目里的 AGENTS.md 和 delegation 会更合适。Hermes 会同时读 agent 自己的身份文件和项目上下文文件，这两层承担的内容并不一样。SOUL.md 决定它是什么样的 agent，项目里的规则文件则决定它进到某个仓库以后要遵守哪些约定。官方把项目上下文的优先级写得很细，.hermes.md 或 HERMES.md 优先，其次是 AGENTS.md，再往后才是 CLAUDE.md 和 .cursorrules。如果仓库里本来就有这些文件，Hermes 通常已经能读到，你不需要把同一套规范再抄一遍进 SOUL.md。身份设定和项目规则分开以后，后面你想调的是 agent 的说话方式，还是某个仓库里的编码约定，处理起来都会更清楚。

如果只是想先把 Hermes 配到可以长期使用的状态，一个更实际的目标可以只放在四步上：先用 hermes model 定一个能稳定使用的 provider，再用 hermes tools 把 CLI 和消息入口需要的工具打开，接着让 terminal.backend 先留在 local 确认可执行，最后按你的入口去跑 hermes gateway setup，并补上 MESSAGING_CWD。做到这里以后，再回头调 Docker、SSH、delegation、fallback model 或 context compression，阻力会小很多。Hermes 的配置项确实不少，但它们大多是按层分开的，你把顺序排对，第一轮不用一次填满。

配好以后可以接哪些工具链

如果你只是想体验 Agent 配置，可以先从 Hermes Agent 本身开始；如果目标是写代码和改仓库，可以把它和 Codex、Claude Code、Cursor 放在一起比较。Hermes 更偏“自己配置入口和工具链”，Codex/Claude Code 更偏“开箱进入真实项目”。

后续排查时，建议先看三件事：模型 provider 是否能稳定响应、terminal backend 是否真的在目标目录执行、gateway 入口是否和 CLI 使用同一套工作目录。把这三层对齐以后，再去调 tools、subagent 和上下文压缩，成本会低很多。