配置 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