Hermes Agent 設定教學：config.yaml、.env 與終端 backend

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
Configuration	設定	Hermes 的設定詳解。
層級	scope	全域 / 任務級設定。
優先順序	priority	多層設定生效順序。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你理清 Hermes 設定的層級和關鍵項，改到對的地方。

你是 Hermes 設定顧問。

【角色】
Hermes 設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 想改的設定：___
- 適用範圍：___
- 現有設定：___
- 是否團隊共享：___
- 經驗水平：___

【工作流程】
1. 梳理設定層級
2. 把設定放到合適層
3. 說明優先順序
4. 標出常見衝突
5. 給驗證

【輸出規範】
▌一、設定層級
▌二、設定歸層
▌三、優先順序
▌四、衝突 + 驗證

【硬約束】
- 設定放對層級
- 敏感設定安全存放
- 改後驗證生效
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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 Agent 設定目錄裡分別放什麼

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。

Hermes Agent 設定應該用哪些命令管理

優先用 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 Agent 設定優先順序怎麼排查

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