配置 Hermes Agent

Hermes Agent 的配置目标不是把示例字段填满，而是让它明确三件事：① 用哪个模型；② 密钥放在哪里；③ 命令在哪个环境执行。只要这三件事混乱，后面的 memory、skills、Gateway、cron 和 MCP 都会一起变乱——本页就围绕这三件事展开。

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

先给结论：普通配置进 config.yaml，密钥进 .env，OAuth 凭据进 auth.json；命令在哪执行由 terminal.backend 决定；修改后用 hermes config check（语法 / 必填校验）和 hermes doctor（端到端自查）双验收。

配置目录

Hermes 的配置中心是：

~/.hermes/
├── config.yaml     # model、terminal、TTS、压缩、memory、toolsets 等普通设置
├── .env            # API keys、bot tokens、passwords、webhook secrets
├── auth.json       # Nous Portal、OpenAI Codex、GitHub Copilot 等 OAuth 凭据
├── SOUL.md         # Agent 长期身份，进入 system prompt 的前置身份层
├── memories/       # MEMORY.md、USER.md
├── skills/         # Agent-created skills
├── cron/           # scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # errors.log、gateway.log 等，官方会做 secret redaction

新手先记住一条线：密钥不进 config.yaml，长期规则不进 .env，项目临时说明不进 SOUL.md。

用命令管理配置

优先用 CLI 改配置：

hermes config              # 查看当前配置
hermes config edit         # 打开 config.yaml
hermes config set KEY VAL  # 设置单个值
hermes config check        # 检查更新后缺失项
hermes config migrate      # 交互式补齐缺失项

示例（具体模型名按官方 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 config set 会自动判断：API key 这类 secret 写入 .env，普通设置写入 config.yaml——比手动编辑更不容易把密钥放错位置。手动编辑 config.yaml 时，注意 yaml 缩进敏感，多一个空格少一个空格都会让 hermes 启动报错。

配置优先级

Hermes 解析配置时按这个顺序覆盖：

CLI arguments：只影响当前 invocation。
~/.hermes/config.yaml：长期普通设置。
~/.hermes/.env：环境变量和 secret fallback。
built-in defaults：内置默认值。

如果“明明改了配置但没生效”，优先检查命令行参数是否覆盖了 config.yaml。如果“密钥明明写了但 provider 还是报错”，检查 key 是否在 .env、shell 环境或 OAuth auth.json 里被另一个来源覆盖。

环境变量替换

config.yaml 支持 ${VAR_NAME} 形式引用环境变量：

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

注意三个边界：

必须写 ${VAR}，裸 $VAR 不展开。
同一个值里可以拼多个变量，例如 "${HOST}:${PORT}"。
未设置的变量会保持原样，不会自动变成空字符串。

${VAR} 不是加密。它只是引用。真实 secret 仍然要按密钥方式管理。

Provider timeout

Hermes 支持 provider 级和 model 级 timeout 配置，用来控制长请求、fallback chain 和 stale-call detector。默认值对普通用户通常够用；只有在自建模型、网络很慢、长上下文任务或 provider 经常挂起时才需要改。

调整 timeout 前先确认问题不是：

模型 context 不足。
API key 或 OAuth 过期。
网络代理不稳定。
工具任务卡在 terminal/backend，而不是模型请求。

不要把 timeout 当成万能修复。请求慢和请求不对是两类问题。

Terminal backend

terminal.backend 决定命令实际在哪里执行——按官方 Tools 页 Backends 段当前列表为准，共 7 种：

local

命令直接在本机执行——上手最快，但没有任何隔离。删 ~/ 没人挡。

docker

单个持久 Docker 容器，适合隔离未知代码和临时依赖；注意持久含义——容器内状态会跨 tool call 保留。

ssh

命令在远程服务器执行，适合隔离主机、远程硬件和 VPS——把 Hermes 在哪和命令在哪解耦。

modal / daytona

云端 sandbox 或 workspace（无服务器），闲置免费、按需启动——适合临时算力和远程持久环境。

vercel_sandbox

Vercel cloud microVM（微型虚拟机），支持 snapshot-backed filesystem persistence（快照支持的文件系统持久化）。

singularity

HPC（高性能计算）或共享机器里的 Apptainer / Singularity 容器，常用于科研集群。

配置示例（注意 yaml 缩进）：

terminal:
  backend: docker         # local / docker / ssh / modal / daytona / vercel_sandbox / singularity
  cwd: "."                # 工作目录（cwd = current working directory）
  timeout: 180            # 单条命令超时（秒）
  env_passthrough: []     # 允许穿透到 backend 的环境变量白名单（默认全空 = 不传任何 env）

默认 local 最容易跑通，但风险也最大。只要任务会运行不确定脚本、修改大量文件、处理外部输入或执行自动化，就应该重新评估 backend——一句"local 上手快"很容易让人忘记基础环境其实是裸机执行。

Docker 的关键边界

Hermes 的 Docker backend 不是“每个命令一个新容器”。官方文档说明它会启动一个长生命周期容器，并用 docker exec 执行后续 terminal、file 和 execute_code 调用。也就是说：

安装的包会在当前 Hermes 进程期间保留。
/workspace 里的文件会跨 tool call 存在。
/new、/reset 和 delegation subagents 仍可能共享这个容器。
并行任务写同一路径会互相影响。

因此 Docker 是隔离边界，不是并发隔离万能方案。并行任务需要单独规划工作目录、volume、环境变量和写入路径。

配置验收

改完配置后跑：

hermes config check
hermes doctor

健康配置至少满足：

Provider/model 能完成普通对话。
Secret 在 .env、OAuth 或安全凭据来源里，不在公开文件里。
terminal.backend 与任务风险匹配。
Backend 能执行一个低风险命令。
Sessions、logs、memory 路径能正常写入。
你知道命令是在本机、容器、远端还是云端执行。

常见坑

按出现频率从高到低：

把 API key 写进 config.yaml —— 一旦提交进 git 就极难撤回；用 hermes config set OPENROUTER_API_KEY sk-... 让工具自动写到 .env
复制完整示例却不知道哪些字段真正在用 —— 直接 hermes config edit 在已有最小配置上增量改，比从空白复制示例更安全
用 CLI 参数临时覆盖后以为长期配置失效 —— 检查启动命令是否带了 --model / --backend 等覆盖
以为 local backend 有沙箱隔离 —— 它就是直接在本机跑，跟你手敲一样
Docker 或云 backend 转发了过多环境变量 —— 默认 env_passthrough: [] 不要随意改成 ["*"]，会把整个 shell 环境（包括其他项目的密钥）暴露进容器
Gateway 里使用的 cwd 和 CLI 启动目录不是同一个 —— Gateway 的 cron 默认在 home 目录跑，不是项目目录
日志里输出 .env、token 或完整 provider 响应 —— Hermes 默认会做 secret redaction（密钥脱敏），但自定义 hooks 不会自动脱敏，写 hooks 时要主动避免

官方资料

Configuration
Configuring Models
Profiles（多 profile 切换）
Providers
Tools & Toolsets / Backends（7 个 backend 完整说明）
Security