03 · 配置、Provider 与目录结构

Hermes 的配置中心是 ~/.hermes/。理解这个目录，比记住单个命令更重要。

核心结构：

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

config.yaml 和 .env 的分工

config.yaml 存普通配置：

• 默认模型。
• 终端后端。
• toolset。
• 压缩策略。
• memory 开关和容量。
• TTS / browser / delegation 等非密钥设置。

.env 存 secrets：

• API key。
• bot token。
• password。
• OAuth 相关 secret。

不要把密钥写进 config.yaml。也不要把 .env 贴进 issue、PR、分享会话或公开日志。

优先用 CLI 写配置

常用命令：

hermes config
hermes config edit
hermes config set KEY VAL
hermes config check
hermes config migrate

示例：

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...

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

Provider 配置策略

第一次使用只配置一个 provider。等基础闭环稳定后，再考虑多 provider、fallback 或 routing。

选 provider 时看四个因素：

• 凭据是否稳定。
• 模型上下文是否足够。
• 工具调用是否稳定。
• 成本和限流是否可接受。

Hermes 支持很多 provider，但这不代表应该全部启用。provider 越多，排障越复杂。

SOUL.md 是什么

SOUL.md 是 Hermes 的主身份文件，会进入 system prompt 的靠前位置。它适合写长期稳定的助手人格和工作原则，不适合写一次性任务。

适合写：

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

不适合写：

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

配置检查

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

hermes config check
hermes doctor

配置检查能更早发现 key 缺失、目录错误、依赖缺失和迁移问题。不要等 gateway 或 cron 失败后再查基础配置。