配置 Hermes Agent

Hermes 的配置集中在 ~/.hermes/。新手不需要先背所有字段，先理解三件事：普通设置放哪里、密钥放哪里、Agent 的命令到底在哪里执行。

先理解配置目录

官方文档把 ~/.hermes/ 作为配置中心。几个文件和目录最重要：

• config.yaml：模型、terminal backend、TTS、压缩、记忆限制、toolsets 等非密钥设置。
• .env：API key、bot token、password 等 secrets。
• auth.json：OAuth provider 凭据。
• SOUL.md：Agent 的主要身份，会进入 system prompt 的靠前位置。
• memories/：长期记忆。
• skills/：本地 skills。
• sessions/ 和 logs/：会话和日志。

新手原则很简单：密钥不进 config.yaml，规则和偏好不进 .env。

不要急着手改文件

官方推荐用 hermes config 系列命令管理配置。hermes config set 会判断值应该写入哪里：API key 这类 secret 会进 .env，普通配置会进 config.yaml。

第一次配置时，建议只做三件事：

1. 设置模型或 provider。
2. 确认 terminal backend。
3. 运行配置检查。

如果你还没理解某个字段，不要为了“看起来完整”把示例配置全复制进去。空白加默认值通常比错误配置更安全。

配置优先级怎么理解

官方解析顺序从高到低是：

1. CLI arguments。
2. ~/.hermes/config.yaml。
3. ~/.hermes/.env。
4. 内置默认值。

这意味着：你临时在命令里指定的参数，只影响这一次；长期偏好应该写进 config.yaml；密钥必须放在 .env 或安全凭据来源里。

如果你发现“我明明改了配置但没生效”，优先检查是不是 CLI 参数覆盖了它。

环境变量替换

config.yaml 支持 ${VAR_NAME} 形式引用环境变量。它适合把路径、URL 或密钥引用留在配置里，把真实值放在 shell 环境或 .env 里。

注意两个边界：

• 多个变量可以拼在同一个值里。
• 裸 $VAR 不会展开，必须使用 ${VAR}。

新手不要把 ${VAR} 当作加密。它只是引用，真实 secret 仍然要按密钥方式保存。

终端后端怎么选

terminal.backend 决定 Agent 的 shell 命令在哪里执行。

新手可以这样选：

• local：最快上手，命令直接在本机执行，但没有隔离。
• docker：更适合不信任任务和可复现环境。
• ssh：命令在远程服务器执行，适合把 Agent 和主机隔开。
• modal、daytona、vercel_sandbox：云端沙箱，适合远程执行和持久化场景。
• singularity：HPC 或共享机器场景。

如果你只是第一次跑通，先用 local。如果任务会改文件、跑未知代码、接外部输入，再考虑 Docker、SSH 或云沙箱。

新手常见坑

• 把 API key 写进 config.yaml。
• 复制完整示例后忘记哪些字段真的需要。
• 不知道 CLI 参数覆盖了长期配置。
• 以为 local backend 有隔离，实际上它和你的用户账号权限一致。
• Docker backend 转发了过多环境变量。
• 远程或云沙箱启用持久化后，忘记快照里也可能留下凭据和缓存。

---

怎么判断配置健康

一个健康的 Hermes 配置应该满足：

• hermes config check 没有关键缺项。
• secret 在 .env 或对应凭据系统里，不在普通配置文件里。
• terminal backend 能执行最小命令。
• 你知道命令是在本机、容器、远程机器还是云端跑。
• 日志可读，并且 secrets 不被直接打印。
• 出问题时你能回到 local backend 做最小验证。

---

官方资料

• Hermes Agent: Configuration
• Hermes Agent: Tools & Toolsets
• Hermes Agent GitHub

最近更新：2026年5月4日