03 · 配置、Provider 與目錄結構 · AI 程式設計教程中文版

Hermes 的配置中心是 ~/.hermes/。理解這個目錄，比記住單個命令更重要——大多數 Hermes 問題不是"命令不會用"，而是金鑰、模型、目錄、身份、記憶、session 或執行環境混在一起：把 API key 放進了 config.yaml、把專案級規則塞進了全域性 SOUL.md、把 OAuth 憑據手動複製到了錯誤位置。

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

先給結論：config.yaml 管普通設定，.env 管 secret（金鑰），auth.json 管 OAuth 憑據，SOUL.md 管全域性長期身份，terminal.backend 管命令執行位置。Provider 先配一個跑穩，再加 fallback（備用切換）和 routing（路由）——多 provider 排障複雜度是單 provider 的好幾倍。

配置目錄

核心結構：

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

每個檔案解決的是不同的"該把什麼放進 system prompt"問題——分工如下：

flowchart LR
    subgraph CFG["配置層 · 決定 Hermes 怎麼跑"]
        C1["config.yaml<br/>非金鑰設定<br/>(可進 git)"]
        C2[".env<br/>金鑰<br/>(.gitignore)"]
        C3["auth.json<br/>OAuth 憑據<br/>(自動寫入)"]
    end
    subgraph IDENT["身份層 · 決定 Hermes 是誰"]
        S1["SOUL.md<br/>全域性人格"]
        P1["AGENTS.md / CLAUDE.md<br/>.hermes.md<br/>專案級規則"]
    end
    subgraph PERSIST["持久化層 · 決定 Hermes 記得什麼"]
        M1["memories/<br/>MEMORY.md + USER.md"]
        SK1["skills/<br/>可複用流程"]
        SE1["sessions/<br/>會話歷史"]
    end
    subgraph RUN["執行時 · Hermes 在做什麼"]
        CR1["cron/<br/>定時任務"]
        LG1["logs/<br/>排障證據"]
    end
    CFG -->|"啟動注入"| SP[("system prompt<br/>每次會話開頭")]
    IDENT -->|"啟動注入"| SP
    PERSIST -->|"啟動注入"| SP
    SP -.->|"執行中產生"| RUN
    style C2 fill:#fde2e2,stroke:#c43d3d
    style SP fill:#fde7c2,stroke:#d4761a

紅色 .env 是必須嚴守的邊界——它不進 system prompt，也不進 git，只透過環境變數在 backend 程序裡被讀取。下面 6 張卡是同一份分工的逐項細節：

config.yaml

普通配置：model、terminal backend、toolsets、壓縮策略、memory 開關、display 等——可進 git 的非金鑰設定。

.env

金鑰：API key、bot token、password、webhook secret、backend 憑據——必須在 .gitignore 裡。

auth.json

OAuth 憑據，例如 Nous Portal、OpenAI Codex、Anthropic Claude（Max plan）、GitHub Copilot 等——hermes model 互動登入後自動寫入。

SOUL.md

全域性長期身份和行為原則，進入 system prompt（系統提示）的靠前位置；專案級規則放 AGENTS.md / CLAUDE.md / .hermes.md。

memories / skills

長期事實（MEMORY.md / USER.md）與可複用流程（agent-created skills + 手動 skill）。

sessions / logs

會話和日誌，是排障時最重要的證據——出問題先看 logs，不要直接改配置。

配置和金鑰分工

config.yaml 存普通設定，.env 存 secrets。

如果某個值既像設定又像金鑰，按金鑰處理。典型例子：API key（API 金鑰）、bot token（機器人憑據）、OAuth secret（開放授權金鑰）、webhook secret（事件回撥金鑰）、SSH 連線憑據、sudo password（管理員密碼）。

不要把 .env 貼進 issue、PR、分享會話、公開日誌或教程正文。也不要讓 agent 把 .env 作為普通上下文讀取。

優先用 CLI

常用命令：

hermes config
hermes config edit
hermes config set KEY VALUE
hermes config check
hermes config migrate

hermes config set 會判斷值型別：API key 進入 .env，普通配置進入 config.yaml。

示例（具體模型名按官方 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/.env

手動編輯可以做，但不要繞過 hermes config check 和 hermes doctor——前者校驗語法和必填欄位，後者跑端到端自查。改完 yaml 不驗證就啟動，很容易把一個 typo 留到上線後才發現。

Provider 策略

第一次只配置一個 provider。等基礎閉環穩定後，再考慮多 provider、fallback（備用切換）或 routing（基於條件路由到不同 provider）。

選 provider 時看五個因素：

憑據穩定：API key 長期可用，OAuth 流程能跑通；訂閱型（Claude Max / Nous Portal）比 API key 更省事但成本固定。
模型上下文 ≥ 64K：官方 quickstart 強制要求至少 64K tokens，Hermes 啟動時直接拒絕低於此值的模型載入。
工具呼叫穩定：模型對函式呼叫、長輸出、多輪工具迴圈響應不掉鏈——這點不同模型差異比想象大，建議跑 quickstart 裡的 prompt 實測。
成本可控：注意 rate limit（速率限制）、按 token 計費 vs 訂閱、限流後的退避策略。
網路可達：當前網路能穩定連線該 provider；國內開發者沒梯子優先選中國區直連（Z.AI / Kimi / DeepSeek / Qwen）。

Hermes 支援的 provider 很多，但這不代表應該全部啟用。Provider 越多，排障越複雜——同一個"模型不回"症狀可能來自主鏈路、fallback 鏈路、routing 規則、或某條 credential pool 裡某個 key 失效，定位時間會指數級上升。

Timeout 不等於穩定性

官方配置支援 provider 級和 model 級 timeout、stale timeout。它適合處理長請求或 provider 掛起，但不能修復錯誤模型、錯誤 key、錯誤 base URL 或 context 不足。

調整 timeout 前先確認：

key 沒錯。
model 名沒錯。
base URL 沒錯。
網路能連。
context size 足夠。
backend 沒卡在 terminal 命令。

先修根因，再調 timeout。

SOUL.md 邊界

SOUL.md 適合寫長期穩定的助手身份和工作原則。

適合寫：

助手角色。
長期溝通偏好。
穩定安全邊界。
工具使用原則。

不適合寫：

本次任務。
臨時路徑。
短期計劃。
會頻繁變化的專案細節。

專案細節優先放專案自己的 AGENTS.md、CLAUDE.md、.hermes.md 或 context files，不要塞進全域性 SOUL。

Terminal backend

Terminal backend 決定命令在哪裡執行。第一次跑通可以用 local，但它沒有隔離。

terminal:
  backend: local
  cwd: "."
  timeout: 180

選擇原則：

local：可信個人專案和低風險命令。
docker：未知指令碼、臨時依賴、隔離執行。
ssh：遠端伺服器、VPS、隔離主機。
modal / daytona / vercel_sandbox：雲端 sandbox 或 workspace。
singularity：HPC 或共享機器。

命令在哪執行，決定它能讀寫哪些檔案、看到哪些環境變數、影響哪些系統。這個問題必須在啟用 terminal toolset 前說清楚。

每次變更後的驗收

每次升級、遷移機器、切 provider、改 model、改 backend 後，先跑：

hermes config check    # 配置文件语法 + 必填字段校验
hermes doctor          # Hermes 端到端自查（依赖、PATH、配置、权限）

配置健康意味著下面 6 項都能用一句話回答——不能回答說明這一項還沒真正搞清楚：

key 不缺且沒進入公開檔案——驗證：grep -r "sk-" ~/.hermes/config.yaml 應為空。
provider/model 能回——驗證：hermes 跑一次 quickstart 推薦的 prompt 收到正常回復。
session 能寫入和恢復——驗證：完成對話後 hermes --continue 能接回上文。
logs 可讀——驗證：ls ~/.hermes/logs/ 看到當天日誌，能 tail 看到剛才命令的痕跡。
command backend 明確——驗證：hermes config show 能看到 terminal.backend: <值>，不是預設推斷。
最小工具呼叫可控——驗證：讓 Hermes 跑一條只讀命令，命令實際執行位置（cwd）符合預期。

官方資料

Configuration
Configuring Models
Providers 完整目錄
Profiles（多 profile 切換）
Provider Routing / Fallback Providers / Credential Pools

03 · 配置、Provider 與目錄結構