---
title: "03 · 配置、Provider 與目錄結構"
description: "理解 Hermes 的 ~/.hermes 目錄、config.yaml、.env、auth.json、SOUL.md、provider、timeout 和 terminal backend。"
verifiedAt: "2026-05-09"
---

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

官方資料：[Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)、[Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)、[Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)、[Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models)、[Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles)。

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

## 配置目錄

核心結構：

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

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

```mermaid
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 張卡是同一份分工的逐項細節：

<Cards>
  <Card title="config.yaml" description="普通配置：model、terminal backend、toolsets、壓縮策略、memory 開關、display 等——可進 git 的非金鑰設定。" />
  <Card title=".env" description="金鑰：API key、bot token、password、webhook secret、backend 憑據——必須在 .gitignore 裡。" />
  <Card title="auth.json" description="OAuth 憑據，例如 Nous Portal、OpenAI Codex、Anthropic Claude（Max plan）、GitHub Copilot 等——hermes model 互動登入後自動寫入。" />
  <Card title="SOUL.md" description="全域性長期身份和行為原則，進入 system prompt（系統提示）的靠前位置；專案級規則放 AGENTS.md / CLAUDE.md / .hermes.md。" />
  <Card title="memories / skills" description="長期事實（MEMORY.md / USER.md）與可複用流程（agent-created skills + 手動 skill）。" />
  <Card title="sessions / logs" description="會話和日誌，是排障時最重要的證據——出問題先看 logs，不要直接改配置。" />
</Cards>

## 配置和金鑰分工

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

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

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

## 優先用 CLI

常用命令：

```bash
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](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models) 當前推薦為準，不要在教程裡寫死版本號）：

```bash
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`，但它沒有隔離。

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

選擇原則：

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

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

## 每次變更後的驗收

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

```bash
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](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)
- [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models)
- [Providers 完整目錄](https://hermes-agent.nousresearch.com/docs/integrations/providers)
- [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles)（多 profile 切換）
- [Provider Routing](https://hermes-agent.nousresearch.com/docs/user-guide/features/provider-routing) / [Fallback Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers) / [Credential Pools](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools)

## 下一步

<Cards>
  <Card title="工具系統與終端後端" description="配置清楚後，下一步理解 toolset（調什麼）和 terminal backend（在哪跑）的解耦設計。" href="/zh-Hant/docs/hermes/understanding/04-tools-terminal-backends" />
  <Card title="配置手冊" description="需要操作細節（具體 yaml 欄位、命令）查官方教程中文版的配置頁。" href="/zh-Hant/docs/hermes/official/01-user-guide/configuration" />
</Cards>
