03 · 配置、Provider 与目录结构 · AI 编程教程中文版

Hermes 的配置中心是 ~/.hermes/。理解这个目录，比记住单个命令更重要——大多数 Hermes 问题不是"命令不会用"，而是密钥、模型、目录、身份、记忆、session 或执行环境混在一起：把 API key 放进了 config.yaml、把项目级规则塞进了全局 SOUL.md、把 OAuth 凭据手动复制到了错误位置。

官方资料：Configuration、Providers、Tools & Toolsets、Configuring Models、Profiles。

先给结论：config.yaml 管普通设置，.env 管 secret（密钥），auth.json 管 OAuth 凭据，SOUL.md 管全局长期身份，terminal.backend 管命令执行位置。Provider 先配一个跑稳，再加 fallback（备用切换）和 routing（路由）——多 provider 排障复杂度是单 provider 的好几倍。

配置目录

核心结构：

~/.hermes/
├── config.yaml
├── .env
├── auth.json
├── SOUL.md
├── memories/
├── skills/
├── cron/
├── sessions/
└── logs/

每个文件解决的是不同的"该把什么放进 system prompt"问题——分工如下：

flowchart LR
    subgraph CFG["配置层 · 决定 Hermes 怎么跑"]
        C1["config.yaml<br/>非密钥设置<br/>(可进 git)"]
        C2[".env<br/>密钥<br/>(.gitignore)"]
        C3["auth.json<br/>OAuth 凭据<br/>(自动写入)"]
    end
    subgraph IDENT["身份层 · 决定 Hermes 是谁"]
        S1["SOUL.md<br/>全局人格"]
        P1["AGENTS.md / CLAUDE.md<br/>.hermes.md<br/>项目级规则"]
    end
    subgraph PERSIST["持久化层 · 决定 Hermes 记得什么"]
        M1["memories/<br/>MEMORY.md + USER.md"]
        SK1["skills/<br/>可复用流程"]
        SE1["sessions/<br/>会话历史"]
    end
    subgraph RUN["运行时 · Hermes 在做什么"]
        CR1["cron/<br/>定时任务"]
        LG1["logs/<br/>排障证据"]
    end
    CFG -->|"启动注入"| SP[("system prompt<br/>每次会话开头")]
    IDENT -->|"启动注入"| SP
    PERSIST -->|"启动注入"| SP
    SP -.->|"运行中产生"| RUN
    style C2 fill:#fde2e2,stroke:#c43d3d
    style SP fill:#fde7c2,stroke:#d4761a

红色 .env 是必须严守的边界——它不进 system prompt，也不进 git，只通过环境变量在 backend 进程里被读取。下面 6 张卡是同一份分工的逐项细节：

config.yaml

普通配置：model、terminal backend、toolsets、压缩策略、memory 开关、display 等——可进 git 的非密钥设置。

.env

密钥：API key、bot token、password、webhook secret、backend 凭据——必须在 .gitignore 里。

auth.json

OAuth 凭据，例如 Nous Portal、OpenAI Codex、Anthropic Claude（Max plan）、GitHub Copilot 等——hermes model 交互登录后自动写入。

SOUL.md

全局长期身份和行为原则，进入 system prompt（系统提示）的靠前位置；项目级规则放 AGENTS.md / CLAUDE.md / .hermes.md。

memories / skills

长期事实（MEMORY.md / USER.md）与可复用流程（agent-created skills + 手动 skill）。

sessions / logs

会话和日志，是排障时最重要的证据——出问题先看 logs，不要直接改配置。

配置和密钥分工

config.yaml 存普通设置，.env 存 secrets。

如果某个值既像设置又像密钥，按密钥处理。典型例子：API key（API 密钥）、bot token（机器人凭据）、OAuth secret（开放授权密钥）、webhook secret（事件回调密钥）、SSH 连接凭据、sudo password（管理员密码）。

不要把 .env 贴进 issue、PR、分享会话、公开日志或教程正文。也不要让 agent 把 .env 作为普通上下文读取。

优先用 CLI

常用命令：

hermes config
hermes config edit
hermes config set KEY VALUE
hermes config check
hermes config migrate

hermes config set 会判断值类型：API key 进入 .env，普通配置进入 config.yaml。

示例（具体模型名按官方 Configuring Models 当前推荐为准，不要在教程里写死版本号）：

hermes config set model openrouter/anthropic/claude-sonnet-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # 也可改写到 ~/.hermes/.env

手动编辑可以做，但不要绕过 hermes config check 和 hermes doctor——前者校验语法和必填字段，后者跑端到端自查。改完 yaml 不验证就启动，很容易把一个 typo 留到上线后才发现。

Provider 策略

第一次只配置一个 provider。等基础闭环稳定后，再考虑多 provider、fallback（备用切换）或 routing（基于条件路由到不同 provider）。

选 provider 时看五个因素：

凭据稳定：API key 长期可用，OAuth 流程能跑通；订阅型（Claude Max / Nous Portal）比 API key 更省事但成本固定。
模型上下文 ≥ 64K：官方 quickstart 强制要求至少 64K tokens，Hermes 启动时直接拒绝低于此值的模型加载。
工具调用稳定：模型对函数调用、长输出、多轮工具循环响应不掉链——这点不同模型差异比想象大，建议跑 quickstart 里的 prompt 实测。
成本可控：注意 rate limit（速率限制）、按 token 计费 vs 订阅、限流后的退避策略。
网络可达：当前网络能稳定连接该 provider；国内开发者没梯子优先选中国区直连（Z.AI / Kimi / DeepSeek / Qwen）。

Hermes 支持的 provider 很多，但这不代表应该全部启用。Provider 越多，排障越复杂——同一个"模型不回"症状可能来自主链路、fallback 链路、routing 规则、或某条 credential pool 里某个 key 失效，定位时间会指数级上升。

Timeout 不等于稳定性

官方配置支持 provider 级和 model 级 timeout、stale timeout。它适合处理长请求或 provider 挂起，但不能修复错误模型、错误 key、错误 base URL 或 context 不足。

调整 timeout 前先确认：

key 没错。
model 名没错。
base URL 没错。
网络能连。
context size 足够。
backend 没卡在 terminal 命令。

先修根因，再调 timeout。

SOUL.md 边界

SOUL.md 适合写长期稳定的助手身份和工作原则。

适合写：

助手角色。
长期沟通偏好。
稳定安全边界。
工具使用原则。

不适合写：

本次任务。
临时路径。
短期计划。
会频繁变化的项目细节。

项目细节优先放项目自己的 AGENTS.md、CLAUDE.md、.hermes.md 或 context files，不要塞进全局 SOUL。

Terminal backend

Terminal backend 决定命令在哪里执行。第一次跑通可以用 local，但它没有隔离。

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

选择原则：

local：可信个人项目和低风险命令。
docker：未知脚本、临时依赖、隔离执行。
ssh：远程服务器、VPS、隔离主机。
modal / daytona / vercel_sandbox：云端 sandbox 或 workspace。
singularity：HPC 或共享机器。

命令在哪执行，决定它能读写哪些文件、看到哪些环境变量、影响哪些系统。这个问题必须在启用 terminal toolset 前说清楚。

每次变更后的验收

每次升级、迁移机器、切 provider、改 model、改 backend 后，先跑：

hermes config check    # 配置文件语法 + 必填字段校验
hermes doctor          # Hermes 端到端自查（依赖、PATH、配置、权限）

配置健康意味着下面 6 项都能用一句话回答——不能回答说明这一项还没真正搞清楚：

key 不缺且没进入公开文件——验证：grep -r "sk-" ~/.hermes/config.yaml 应为空。
provider/model 能回——验证：hermes 跑一次 quickstart 推荐的 prompt 收到正常回复。
session 能写入和恢复——验证：完成对话后 hermes --continue 能接回上文。
logs 可读——验证：ls ~/.hermes/logs/ 看到当天日志，能 tail 看到刚才命令的痕迹。
command backend 明确——验证：hermes config show 能看到 terminal.backend: <值>，不是默认推断。
最小工具调用可控——验证：让 Hermes 跑一条只读命令，命令实际执行位置（cwd）符合预期。

官方资料

Configuration
Configuring Models
Providers 完整目录
Profiles（多 profile 切换）
Provider Routing / Fallback Providers / Credential Pools

03 · 配置、Provider 与目录结构