<!-- Source: https://hermesbible.com/docs/user-guide/configuration -->

章節：使用 Hermes · URL：https://hermesbible.com/docs/user-guide/configuration

所有設定都儲存在 ~/.hermes/ 目錄中，方便存取。

提示 — 取得可運作 config.yaml 的最簡單方式

執行 hermes setup --portal — 一次 OAuth 授權即可取得模型提供者和所有四個 Tool Gateway 工具，無需手動編輯 YAML。Portal 訂閱者還能享受代幣計費提供者 10% 折扣。詳見 Nous Portal。

目錄結構

~/.hermes/
├── config.yaml     # 設定（模型、終端機、TTS、壓縮等）
├── .env            # API 金鑰和密鑰
├── auth.json       # OAuth 提供者憑證（Nous Portal 等）
├── SOUL.md         # 主要代理身份（系統提示中的插槽 #1）
├── memories/       # 持久記憶（MEMORY.md、USER.md）
├── skills/         # 代理建立的技能（透過 skill_manage 工具管理）
├── cron/           # 排程任務
├── sessions/       # Gateway 會話
└── logs/           # 日誌（errors.log、gateway.log — 密鑰自動遮蔽）

管理設定

hermes config              # 檢視目前設定
hermes config edit         # 在編輯器中開啟 config.yaml
hermes config set KEY VAL  # 設定特定值
hermes config check        # 檢查遺漏的選項（更新後使用）
hermes config migrate      # 互動式新增遺漏的選項

# 範例：
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # 儲存至 .env

提示

hermes config set 指令會自動將值路由到正確的檔案 — API 金鑰儲存至 .env，其餘則存入 config.yaml。

設定優先順序

設定的解析順序如下（優先順序由高到低）：

1. CLI 引數 — 例如 hermes chat --model anthropic/claude-sonnet-4（單次呼叫覆寫）
2. ~/.hermes/config.yaml — 所有非密鑰設定的主要設定檔
3. ~/.hermes/.env — 環境變數的備選來源；密鑰必填（API 金鑰、權杖、密碼）
4. 內建預設值 — 當其他來源均未設定時使用的硬編碼安全預設值

資訊 — 經驗法則

密鑰（API 金鑰、機器人權杖、密碼）放在 .env 中。其餘所有內容（模型、終端機後端、壓縮設定、記憶限制、工具組）放在 config.yaml 中。當兩者同時設定時，config.yaml 對非密鑰設定具有優先權。

環境變數替換

你可以在 config.yaml 中使用 ${VAR_NAME} 語法參照環境變數：

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

delegation:
  api_key: ${DELEGATION_KEY}
}

單一值中可包含多個參照：url: "${HOST}:${PORT}"。若參照的變數未設定，則保留原始佔位符（${UNDEFINED_VAR} 會原樣保留）。僅支援 ${VAR} 語法 — 不支援裸 $VAR 語法。

如需設定 AI 提供者（OpenRouter、Anthropic、Copilot、自訂端點、自架 LLM、備選模型等），請參閱 AI 提供者。

提供者逾時設定

你可以設定 providers.<id>.request_timeout_seconds 作為提供者全域的請求逾時，以及 providers.<id>.models.<model>.timeout_seconds 作為特定模型的覆寫。這適用於所有傳輸協定（OpenAI-wire、原生 Anthropic、Anthropic 相容）的主要回合用戶端、備選鏈、憑證輪換後的重建，以及（OpenAI-wire 的）每個請求逾時參數 — 因此設定的值優於舊版 HERMES_API_TIMEOUT 環境變數。

你也可以設定 providers.<id>.stale_timeout_seconds 用於非串流過期呼叫偵測器，以及 providers.<id>.models.<model>.stale_timeout_seconds 作為特定模型的覆寫。這優於舊版 HERMES_API_CALL_STALE_TIMEOUT 環境變數。

保持這些設定為未設定狀態將使用舊版預設值（HERMES_API_TIMEOUT=1800 秒、HERMES_API_CALL_STALE_TIMEOUT=300 秒、原生 Anthropic 900 秒）。目前尚未對接 AWS Bedrock（bedrock_converse 和 AnthropicBedrock SDK 路徑均使用 boto3 及其自身的逾時設定）。詳見 cli-config.yaml.example 中的註解範例。

更新行為

hermes update 的設定位於 config.yaml 的 updates 區塊：

updates:
  pre_update_backup: false       # 每次更新前建立完整的 HERMES_HOME 壓縮檔
  backup_keep: 5                 # 保留的更新前備份壓縮檔數量
  non_interactive_local_changes: stash  # stash | discard

對於 git 安裝，Hermes 會在簽出更新分支或拉取前自動將已追蹤的髒檔案和未追蹤的檔案加入 stash。互動式終端機更新會在還原 stash 前提示使用者。非互動式更新（桌面/聊天應用程式、Gateway 或 --yes）使用 updates.non_interactive_local_changes：stash 在成功拉取後還原本地原始碼編輯，discard 則在成功拉取後丟棄更新建立的 stash。僅在永不保留本地原始碼編輯的託管安裝上使用 discard。

在 stash 步驟之前，Hermes 還會還原 npm install/build 過程留下的已追蹤 package-lock.json 差異。更新前請提交或手動 stash 有意的 lockfile 編輯。

終端機後端設定

Hermes 支援六種終端機後端。每個後端決定代理的 shell 指令實際執行的位置 — 你的本機、Docker 容器、透過 SSH 的遠端伺服器、Modal 雲端沙箱（直接或透過 Nous 管理的 Gateway）、Daytona 工作區，或 Singularity/Apptainer 容器。

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Gateway/cron 工作目錄（CLI 始終使用啟動目錄）
  timeout: 180      # 每個指令的逾時秒數
  home_mode: auto   # auto | real | profile — 子行程 HOME 策略
  env_passthrough: []  # 要轉發至沙箱執行的環境變數名稱（終端機 + execute_code）
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Singularity 後端的容器映像
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Modal 後端的容器映像
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Daytona 後端的容器映像

對於 Modal 和 Daytona 等雲端沙箱，container_persistent: true 表示 Hermes 會嘗試在沙箱重建時保留檔案系統狀態。但不保證相同的即時沙箱、PID 空間或背景程序會繼續運行。

後端總覽

Local 後端

預設值。指令直接在你的機器上執行，無隔離。無需特殊設定。

terminal:
  backend: local

預設情況下，本地工具子行程保留你真實的 OS 用戶 HOME。這讓 git、ssh、gh、az、npm、Claude Code 和 Codex 等外部 CLI 能找到你在正常 shell 中使用的憑證和設定。Hermes 狀態仍透過 HERMES_HOME 以 profile 為範圍管理；HOME 並非 profile 選擇設定、記憶、會話或技能的方式。

Hermes 不會更改你的全域 HOME、你的 shell 啟動檔案或 作業系統帳號的家目錄。此設定僅控制透過 terminal、 背景終端機行程、execute_code 和 ACP 輔助行程等工具 Hermes 啟動的子行程所接收的環境。

terminal.home_mode

預設值的缺點是主機 profile 共享相同的 ~ 下的正常用戶級 CLI 憑證/設定。如果你需要具有 獨立 git 身份、SSH 金鑰、GitHub CLI 登入、npm 設定或雲端 CLI 登入的 profile，請使用 home_mode: profile 並在該 profile 家目錄中刻意初始化這些工具。

如果你想刻意實現嚴格的逐 profile 工具設定隔離，請設定：

terminal:
  home_mode: profile

在此模式下，工具子行程使用 {HERMES_HOME}/home 作為 HOME。Hermes 還會 設定 HERMES_REAL_HOME，使腳本在需要時仍能找到真實的用戶家目錄。 容器後端在 auto 模式下繼續使用 {HERMES_HOME}/home， 因為該目錄位於持久的 Hermes 資料磁碟區上。

需要區分 profile 狀態和真實用戶家目錄的腳本應 優先使用 HERMES_HOME 作為 Hermes 資料路徑，使用 HERMES_REAL_HOME 作為帳號家目錄：

from pathlib import Path
import os

hermes_home = Path(os.environ["HERMES_HOME"])
real_home = Path(os.environ.get("HERMES_REAL_HOME", os.environ["HOME"]))

警告

代理具有與你的用戶帳號相同的檔案系統存取權限。使用 hermes tools 來停用不需要的工具，或切換到 Docker 進行沙箱化。

Docker 後端

在 Docker 容器內執行指令，具有安全強化（移除所有能力、禁止權限提升、PID 限制）。

單一持久容器，跨 Hermes 行程共享。 Hermes 在首次使用時啟動一個長生命容器，並透過 docker exec 將每個終端機、檔案和 execute_code 呼叫路由到同一個容器 — 跨會話、/new、/reset 和 delegate_task 子代理均如此。工作目錄變更、已安裝的套件、/workspace 中的檔案以及背景行程都會從一個工具呼叫延續到下一個，從一個 Hermes 行程延續到下一個。當你關閉 TUI 會話、執行 /quit 或啟動新的 hermes 呼叫時，容器持續運行，下一個 Hermes 行程透過標籤查找重新使用它。確切的拆除規則請見下方容器生命週期。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # 將啟動目錄掛載到 /workspace
  docker_run_as_host_user: false   # 見下方「以主機用戶運行容器」
  docker_forward_env:              # 要轉發到容器的主機環境變數
    - "GITHUB_TOKEN"
  docker_env:                      # 要注入的字面環境變數（KEY=value）
    DEBUG: "1"
    PYTHONUNBUFFERED: "1"
  docker_volumes:                  # 主機目錄掛載
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro 為唯讀
  docker_extra_args:               # 逐字附加到 `docker run` 的額外參數
    - "--gpus=all"
    - "--network=host"

  # 資源限制
  container_cpu: 1                 # CPU 核心數（0 = 無限制）
  container_memory: 5120           # MB（0 = 無限制）
  container_disk: 51200            # MB（需要 XFS+pquota 上的 overlay2）
  container_persistent: true       # 持久化 /workspace 和 /root 綁定掛載目錄

  # 跨行程容器重用（預設值符合「跨會話共享的
  # 長生命容器」合約 — 見容器生命週期）。
  docker_persist_across_processes: true   # 跨 Hermes 重啟重用容器
  docker_orphan_reaper: true              # 啟動時清理被遺棄的 Exited 容器

  # 跨後端生命週期設定（同樣適用於 docker）
  timeout: 180                     # 每個指令的逾時秒數
  lifetime_seconds: 300            # 閒置清理視窗；同時作為 2× 孤兒清理閾值

docker_env 與 docker_forward_env：前者注入你在設定中指定的字面 KEY=value 對（值存在於你的 config.yaml 中或透過 TERMINAL_DOCKER_ENV='{"DEBUG":"1"}' 以 JSON 字典傳入）。後者轉發自你的 shell 或 ~/.hermes/.env 的值，因此實際密鑰永遠不會出現在設定檔中。對權杖使用 docker_forward_env，對容器需要的靜態設定使用 docker_env。

terminal.docker_extra_args（也可透過 TERMINAL_DOCKER_EXTRA_ARGS='["--gpus=all"]' 覆寫）允許你傳入 Hermes 未作為一級鍵值提供的任意 docker run 參數 — --gpus、--network、--add-host、替代的 --security-opt 覆寫等。每個條目必須是字串；列表會附加到組裝好的 docker run 呼叫末尾，因此可以在需要時覆寫 Hermes 的預設值。請謹慎使用 — 與沙箱強化（能力移除、--user、工作區綁定掛載）衝突的參數會悄無聲息地削弱隔離。

需求： 已安裝並運行 Docker Desktop 或 Docker Engine。Hermes 會探索 $PATH 加上常見的 macOS 安裝位置（/usr/local/bin/docker、/opt/homebrew/bin/docker、Docker Desktop 應用程式套件）。Podman 開箱即用：設定 HERMES_DOCKER_BINARY=podman（或完整路徑）可在兩者都安裝時強制使用 Podman。

容器生命週期

每個 Hermes 管理的容器都標記了三個標籤，以便後續行程（和孤兒清理器）能識別它：

• hermes-agent=1 — 標記為 Hermes 管理
• hermes-task-id=<sanitized task_id> — 用於逐任務重用探測
• hermes-profile=<sanitized profile name> — 將重用和清理範圍限定到活躍的 Hermes profile

啟動時，Hermes 執行 docker ps --filter label=hermes-task-id=<id> --filter label=hermes-profile=<profile> 並在找到時附加到現有容器。如果容器是 exited 狀態（例如 Docker daemon 重啟後），它會被 docker start 並重用 — 檔案系統狀態和已安裝的套件會保留，但容器內的背景行程不會。

當 Hermes 行程退出時 — /quit、關閉 TUI 會話、Gateway 關閉，甚至是 SIGKILL — 預設模式下的清理路徑對容器而言是空操作。容器持續運行。下一個 Hermes 行程透過標籤探測在毫秒內附加到它。這是「跨會話共享的長生命容器」合約所要求的行為：這是背景行程（npm watchers、dev servers、長時間運行的 pytest）能跨會話存活的唯一方式。

容器僅在以下情況被拆除（停止並 docker rm -f）：

值得了解的邊緣情況：

• 容器內 PID 1 的 OOM 終止會將容器轉換為 Exited。下次重用時會 docker start 它；檔案系統狀態保留，背景行程不保留。
• 切換 profile會隔離彼此的容器 — 標記為 hermes-profile=work 的容器對以 hermes-profile=research 運行的 Hermes 行程不可見。孤兒清理器也是 profile 範圍的，因此跨 profile 容器不會被意外清理，但它們也不會在你以原始 profile 再次啟動 Hermes 之前被自動清理。

透過 delegate_task(tasks=[...]) 產生的平行子代理共享這一個容器 — 並發的 cd、環境變數變更和對相同路徑的寫入會衝突。如果子代理需要隔離的沙箱，它必須透過 register_task_env_overrides() 註冊逐任務映像覆寫，RL 和評估環境（TerminalBench2、HermesSweEnv 等）會為其逐任務 Docker 映像自動執行此操作。

安全強化：

• --cap-drop ALL 僅重新加入 DAC_OVERRIDE、CHOWN、FOWNER
• --security-opt no-new-privileges
• --pids-limit 256
• 大小受限的 tmpfs：/tmp（512MB）、/var/tmp（256MB）、/run（64MB）

憑證轉發： docker_forward_env 中列出的環境變數首先從你的 shell 環境解析，然後回退到 ~/.hermes/.env。技能也可以宣告 required_environment_variables，會自動合併。

環境變數覆寫

terminal: 下的每個鍵都有對應的環境變數覆寫，格式為 TERMINAL_<KEY_UPPERCASE>。Docker 後端最有用的幾個：

SSH 後端

透過 SSH 在遠端伺服器上執行指令。使用 ControlMaster 進行連線重用（5 分鐘閒置保活）。預設啟用持久 shell — 狀態（cwd、環境變數）跨指令保留。

terminal:
  backend: ssh
  persistent_shell: true           # 保持長生命 bash 會話（預設：true）

必填環境變數：

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

選填：

運作方式： 在初始化時以 BatchMode=yes 和 StrictHostKeyChecking=accept-new 連線。持久 shell 在遠端主機上保持單一 bash -l 行程運行，透過暫時檔案通訊。需要 stdin_data 或 sudo 的指令會自動回退到一次性模式。

Modal 後端

在 Modal 雲端沙箱中執行指令。每個任務獲得一個隔離的 VM，可設定 CPU、記憶體和磁碟。檔案系統可在跨會話間快照/還原。

terminal:
  backend: modal
  container_cpu: 1                 # CPU 核心數
  container_memory: 5120           # MB（5GB）
  container_disk: 51200            # MB（50GB）
  container_persistent: true       # 快照/還原檔案系統

必填： MODAL_TOKEN_ID + MODAL_TOKEN_SECRET 環境變數，或 ~/.modal.toml 設定檔。

持久化： 啟用後，沙箱檔案系統在清理時快照，在下次會話時還原。快照追蹤記錄在 ~/.hermes/modal_snapshots.json 中。這保留的是檔案系統狀態，而非即時行程、PID 空間或背景工作。

憑證檔案： 從 ~/.hermes/ 自動掛載（OAuth 權杖等），並在每個指令前同步。

Daytona 後端

在 Daytona 託管工作區中執行指令。支援停止/恢復以實現持久化。

terminal:
  backend: daytona
  container_cpu: 1                 # CPU 核心數
  container_memory: 5120           # MB → 轉換為 GiB
  container_disk: 10240            # MB → 轉換為 GiB（最大 10 GiB）
  container_persistent: true       # 停止/恢復而非刪除

必填： DAYTONA_API_KEY 環境變數。

持久化： 啟用後，沙箱在清理時停止（不刪除），在下次會話時恢復。沙箱名稱遵循 hermes-{task_id} 格式。

磁碟限制： Daytona 強制 10 GiB 上限。超過此上限的請求會被限制並發出警告。

Singularity/Apptainer 後端

在 Singularity/Apptainer 容器中執行指令。專為 Docker 不可用的 HPC 叢集和共享機器設計。

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # CPU 核心數
  container_memory: 5120           # MB
  container_persistent: true       # 可寫入 overlay 跨會話持久化

需求： $PATH 中有 apptainer 或 singularity 二進位檔。

映像處理： Docker URL（docker://...）會自動轉換為 SIF 檔案並快取。已有的 .sif 檔案直接使用。

暫存目錄： 按以下順序解析：TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent（HPC 慣例）→ ~/.hermes/sandboxes/singularity。

隔離： 使用 --containall --no-home 實現完整的命名空間隔離，不掛載主機家目錄。

常見終端機後端問題

如果終端機指令立即失敗或終端機工具被報告為已停用：

• Local — 無特殊需求。入門時最安全的預設值。
• Docker — 執行 docker version 驗證 Docker 正常運作。如果失敗，修復 Docker 或 hermes config set terminal.backend local。
• SSH — TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER 都必須設定。如果任一遺漏，Hermes 會記錄明確的錯誤。
• Modal — 需要 MODAL_TOKEN_ID 環境變數或 ~/.modal.toml。執行 hermes doctor 進行檢查。
• Daytona — 需要 DAYTONA_API_KEY。Daytona SDK 處理伺服器 URL 設定。
• Singularity — 需要 $PATH 中有 apptainer 或 singularity。在 HPC 叢集中很常見。

如有疑問，將 terminal.backend 設回 local 並先驗證指令在此處能正常運行。

拆除時的遠端到主機檔案同步

對於 SSH、Modal 和 Daytona 後端（代理的工作樹位於與 Hermes 主機不同的機器上），Hermes 會追蹤代理在遠端沙箱中修改的檔案，並在會話拆除 / 沙箱清理時將修改的檔案同步回主機的 ~/.hermes/cache/remote-syncs/<session-id>/。

• 觸發時機：會話關閉、/new、/reset、Gateway 訊息逾時、delegate_task 子代理完成（當子代理使用遠端後端時）。
• 覆蓋代理修改的整個目錄樹，而不僅是其明確開啟的檔案。新增、編輯和刪除都會被捕獲。
• 遠端沙箱在你查找時可能已被拆除；本機的 ~/.hermes/cache/remote-syncs/… 副本是代理修改的權威記錄。
• 大型二進位輸出（模型檢查點、原始資料集）會受大小限制 — 同步會跳過超過 file_sync_max_mb（預設 100）的檔案。如果你預期會有更大的產出回傳，可調高此值。

terminal:
  file_sync_max_mb: 100     # 預設 — 同步最多 100 MB 的檔案
  file_sync_enabled: true   # 預設 — 設為 false 以完全跳過同步

這就是你從會話結束後即銷毀的暫時性雲端沙箱中恢復結果的方式，無需指示代理明確執行 scp 或 modal volume put 來傳回每個產出物。

Docker 磁碟區掛載

使用 Docker 後端時，docker_volumes 允許你與容器共享主機目錄。每個條目使用標準的 Docker -v 語法：host_path:container_path[:options]。

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   # 讀寫（預設）
    - "/home/user/datasets:/data:ro"              # 唯讀
    - "/home/user/.hermes/cache/documents:/output" # Gateway 可見的匯出

這適用於：

• 向代理提供檔案（資料集、設定、參考程式碼）
• 從代理接收檔案（產生的程式碼、報告、匯出）
• 你和代理存取相同檔案的共享工作區

如果你使用訊息 Gateway 且希望代理透過 MEDIA:/... 傳送產生的檔案，建議使用專用的主機可見匯出掛載，例如 /home/user/.hermes/cache/documents:/output。

• 在 Docker 內將檔案寫入 /output/...
• 在 MEDIA: 中發出主機路徑，例如： MEDIA:/home/user/.hermes/cache/documents/report.txt
• 不要發出 /workspace/... 或 /output/...，除非該確切路徑也存在於主機上的 Gateway 行程中

警告

YAML 重複鍵會悄無聲息地覆蓋先前的值。如果你已有 docker_volumes: 區塊，請將新的掛載合併到同一個列表中，而不是在檔案稍後的位置新增另一個 docker_volumes: 鍵。

也可透過環境變數設定：TERMINAL_DOCKER_VOLUMES='["/host:/container"]'（JSON 陣列）。

Docker 憑證轉發

預設情況下，Docker 終端機會話不會繼承任意主機憑證。如果你需要在容器內使用特定權杖，請將其加入 terminal.docker_forward_env。

terminal:
  backend: docker
  docker_forward_env:
    - "GITHUB_TOKEN"
    - "NPM_TOKEN"

Hermes 首先從你目前的 shell 解析每個列出的變數，然後在變數是透過 hermes config set 儲存時回退到 ~/.hermes/.env。

警告

列在 docker_forward_env 中的任何內容都會對容器內執行的指令可見。只轉發你願意暴露給終端機會話的憑證。

以你的主機用戶運行容器

預設情況下 Docker 容器以 root（UID 0）運行。在 /workspace 或其他綁定掛載中建立的檔案在主機上歸 root 所有，因此會話結束後你必須 sudo chown 才能從主機編輯器編輯它們。terminal.docker_run_as_host_user 修復了這個問題：

terminal:
  backend: docker
  docker_run_as_host_user: true   # 預設：false

啟用後，Hermes 會在 docker run 命令後附加 --user $(id -u):$(id -g)，這樣寫入綁定掛載目錄（/workspace、/root、docker_volumes 中的任何路徑）的檔案歸你的主機用戶所有，而非 root。代價是：容器不能再 apt install 或寫入 root 擁有的路徑如 /root/.npm — 如果兩者都需要，請使用家目錄由非 root 用戶擁有的基礎映像（或在映像構建時加入所需工具）。

保持 false（預設值）以獲得向後相容的行為。當你的工作流程主要是「編輯掛載的主機檔案」且厭倦了 sudo chown -R 時開啟它。

選擇性：將啟動目錄掛載到 /workspace

Docker 沙箱預設保持隔離。除非你明確選擇加入，Hermes 不會將你目前的主機工作目錄傳入容器。

在 config.yaml 中啟用：

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

啟用後：

• 如果你從 ~/projects/my-app 啟動 Hermes，該主機會目錄會被綁定掛載到 /workspace
• Docker 後端從 /workspace 開始
• 檔案工具和終端機指令看到的是相同的掛載專案

停用時，/workspace 由沙箱擁有，除非你透過 docker_volumes 明確掛載某些內容。

安全權衡：

• false 保留沙箱邊界
• true 讓沙箱直接存取你啟動 Hermes 的目錄

僅在你刻意希望容器處理即時主機檔案時使用此選項。

持久 Shell

預設情況下，每個終端機指令在自己的子行程中運行 — 工作目錄、環境變數和 shell 變數在指令間重置。當持久 shell 啟用時，一個長生命的 bash 行程會跨 execute() 呼叫保持運行，使狀態在指令間保留。

這對 SSH 後端最有用，因為它還消除了每個指令的連線開銷。SSH 預設啟用持久 shell，本地後端則停用。

terminal:
  persistent_shell: true   # 預設值 — 為 SSH 啟用持久 shell

停用方式：

hermes config set terminal.persistent_shell false

跨指令保留的內容：

• 工作目錄（cd /tmp 在下個指令中仍然有效）
• 匯出的環境變數（export FOO=bar）
• Shell 變數（MY_VAR=hello）

優先順序：

各後端環境變數具有最高優先順序。如果你想在本地後端也啟用持久 shell：

export TERMINAL_LOCAL_PERSISTENT=true

注意

需要 stdin_data 或 sudo 的指令會自動回退到一次性模式，因為持久 shell 的 stdin 已被 IPC 協定佔用。

詳見 程式碼執行 和 README 的終端機章節了解各後端的詳細資訊。

技能設定

技能可以透過其 SKILL.md 前置資料宣告自己的設定選項。這些是儲存在 config.yaml 的 skills.config 命名空間下的非密鑰值（路徑、偏好設定、領域設定）。

skills:
  config:
    myplugin:
      path: ~/myplugin-data   # 範例 — 每個技能定義自己的鍵值

技能設定的運作方式：

• hermes config migrate 掃描所有已啟用的技能，找到未設定的選項，並提供提示
• hermes config show 在「技能設定」下顯示所有技能設定及其所屬技能
• 當技能載入時，其解析後的設定值會自動注入到技能上下文中

手動設定值：

hermes config set skills.config.myplugin.path ~/myplugin-data

有關在你自己的技能中宣告設定選項的詳細資訊，請參閱 建立技能 — 設定選項。

代理建立技能寫入的守衛

當代理使用 skill_manage 建立、編輯、修補或刪除技能時，Hermes 可以選擇性地掃描新/更新的內容以發現危險的關鍵字模式（憑證收集、明顯的提示注入、資料外洩指令）。掃描器預設關閉 — 真實的代理工作流程中合法觸及 ~/.ssh/ 或提及 $OPENAI_API_KEY 的情況太常觸發此啟發式規則。如果你想在代理的技能寫入生效前讓掃描器提示你，請重新開啟：

skills:
  guard_agent_created: true   # 預設：false

開啟後，任何被標記的 skill_manage 寫入會以審批提示的形式顯示掃描器的判斷依據。接受的寫入生效；拒絕的寫入向代理返回解釋性錯誤。

技能寫入的寫入審批

與上方的內容掃描器獨立，skills.write_approval 將每個代理技能寫入（建立 / 編輯 / 修補 / 刪除 / 輔助檔案）置於你的明確審批之後 — 與危險指令相同的准駁機制：

skills:
  write_approval: false   # false = 自由寫入（預設）| true = 每次寫入都需審查

開啟後，技能寫入會被暫存到 ~/.hermes/pending/skills/ 並透過 /skills pending、/skills diff <id>、/skills approve <id>、/skills reject <id> 進行審查 — 可從 CLI 或任何訊息平台操作。執行時透過 /skills approval on|off 切換。記憶也具有相同的守衛（memory.write_approval，見下文）。完整操作說明：守衛代理技能寫入。

記憶設定

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens
  write_approval: false     # true = 任何記憶寫入都需要你的審批

當 memory.write_approval: true 時，記憶寫入需要你的審批才會生效：互動式 CLI 會回合式提示；訊息會話和背景自我改進審查會將寫入暫存以供 /memory pending → /memory approve <id> / /memory reject <id> 審查。執行時透過 /memory approval on|off 切換。詳見 控制記憶寫入。

上下文檔案截斷

控制 Hermes 從每個自動上下文檔案載入的內容量，然後再套用頭尾截斷。這適用於注入到系統提示中的檔案，如 SOUL.md、.hermes.md、AGENTS.md、CLAUDE.md 和 .cursorrules。它不影響 read_file 工具。

context_file_max_chars: 20000  # 預設值

當你刻意保留較大的身份或專案上下文檔案，且使用具有足夠上下文視窗的模型來攜帶它們時，可調高此值：

context_file_max_chars: 25000

檔案讀取安全

控制單一 read_file 呼叫可以返回的最大內容量。超過限制的讀取會被拒絕，並返回錯誤告知代理使用 offset 和 limit 來讀取較小的範圍。這防止單次讀取壓縮的 JS 套件或大型資料檔而淹沒上下文視窗。

file_read_max_chars: 100000  # 預設值 — ~25-35K tokens

如果你使用具有大上下文視窗的模型且經常讀取大型檔案，可調高此值。對小上下文模型則調低以保持讀取效率：

# 大上下文模型（200K+）
file_read_max_chars: 200000

# 小型本機模型（16K 上下文）
file_read_max_chars: 30000

代理還會自動去重檔案讀取 — 如果同一檔案區域被讀取兩次且檔案未變更，則返回輕量級存根而非重新傳送內容。這在上下文壓縮時重置，以便代理在內容被摘要後能重新讀取檔案。

工具輸出截斷限制

三個相關的上限控制工具在 Hermes 截斷之前可以返回的原始輸出量：

tool_output:
  max_bytes: 50000        # 終端機輸出上限（字元數）
  max_lines: 2000         # read_file 分頁上限
  max_line_length: 2000   # read_file 行號檢視中的每行上限

• max_bytes — 當 terminal 指令產生的 stdout/stderr 組合字元數超過此值時，Hermes 保留前 40% 和後 60%，並在兩者之間插入 [OUTPUT TRUNCATED] 通知。預設 50000（在典型分詞器上約 12-15K tokens）。
• max_lines — 單一 read_file 呼叫的 limit 參數上限。超過此值的請求會被限制，以免單次讀取淹沒上下文視窗。預設 2000。
• max_line_length — read_file 發出行號檢視時套用的每行上限。超過此長度的行會被截斷到此字元數，後接 ... [truncated]。預設 2000。

對具有大上下文視窗且能負擔更多原始輸出的模型，可調高這些限制。對小上下文模型則調低以保持工具結果精簡：

# 大上下文模型（200K+）
tool_output:
  max_bytes: 150000
  max_lines: 5000

# 小型本機模型（16K 上下文）
tool_output:
  max_bytes: 20000
  max_lines: 500

全域工具組停用

要一次在 CLI 和所有 Gateway 平台上停用特定工具組，請將它們的名稱列在 agent.disabled_toolsets 下：

agent:
  disabled_toolsets:
    - memory       # 隱藏記憶工具 + MEMORY_GUIDANCE 注入
    - web          # 到處都無 web_search / web_extract

這在之後套用於各平台工具設定（hermes tools 寫入的 platform_toolsets），因此列在此處的工具組始終被移除 — 即使平台的已儲存設定仍列出了它。當你想要一個「在所有地方關閉 X」的單一開關，而非在 hermes tools UI 中編輯 15+ 個平台行時使用此功能。

留空列表或省略該鍵為空操作。

Git Worktree 隔離

啟用隔離的 git worktree 以在同一個倉庫上並行運行多個代理：

worktree: true    # 始終建立 worktree（等同於 hermes -w）
# worktree: false # 預設值 — 僅在傳入 -w 標誌時

啟用後，每個 CLI 會話在 .worktrees/ 下建立一個帶有自己分支的新 worktree。代理可以編輯檔案、提交、推送和建立 PR 而互不干擾。乾淨的 worktree 在退出時移除；有變更的則保留以供手動恢復。

你也可以透過倉庫根目錄的 .worktreeinclude 列出要複製到 worktree 的 gitignore 檔案：

# .worktreeinclude
.env
.venv/
node_modules/

上下文壓縮

Hermes 自動壓縮長對話以保持在模型的上下文視窗內。壓縮摘要器是一個獨立的 LLM 呼叫 — 你可以將其指向任何提供者或端點。

所有壓縮設定都在 config.yaml 中（無環境變數）。

完整參考

compression:
  enabled: true                                     # 開關壓縮
  threshold: 0.50                                   # 在上下文限制的此百分比時壓縮
  target_ratio: 0.20                                # 保留為近期尾部的閾值比例
  protect_last_n: 20                                # 要保持未壓縮的最少近期訊息數
  protect_first_n: 3                                # 跨壓縮固定的非系統頭部訊息數（0 = 不固定任何內容）
  hygiene_hard_message_limit: 400                   # Gateway 安全閥 — 見下文

# 摘要模型/提供者在 auxiliary 下配置：
auxiliary:
  compression:
    model: ""                                       # 空 = 使用主要聊天模型。例如以 "google/gemini-3-flash-preview" 覆寫以獲得更便宜/更快的壓縮。
    provider: "auto"                                # 提供者："auto"、"openrouter"、"nous"、"codex"、"main" 等
    base_url: null                                  # 自訂 OpenAI 相容端點（覆寫提供者）

資訊 — 舊版設定遷移

較舊的設定中帶有 compression.summary_model、compression.summary_provider 和 compression.summary_base_url 的會在首次載入時自動遷移到 auxiliary.compression.*（設定版本 17）。無需手動操作。

hygiene_hard_message_limit 是 Gateway 專用的預壓縮安全閥。擁有數千條訊息的失控會話可能在正常百分比閾值觸發之前就觸及模型上下文限制；當訊息數量超過此上限時，Hermes 會強制壓縮，不論代幣使用量如何。預設 400 — 對於非常長的會話為正常的平台可調高此值，調低則強制更積極的壓縮。在運行中的 Gateway 上編輯此值會在下一條訊息時生效（見下文）。

protect_first_n 控制跨每次壓縮固定的非系統頭部訊息數。預設 3 — 開頭的用戶/助理對話會在每次摘要過程中存活，使原始目標保持可見。在長時間運行的滾動壓縮會話中，若開頭回合已不再相關，設定 protect_first_n: 0 以僅固定系統提示 + 摘要 + 尾部。系統提示本身始終保留，不受此設定影響。

提示 — Gateway 壓縮和上下文長度的熱重載

從最近的版本開始，在運行中的 Gateway 上編輯 model.context_length 或任何 cache.compression.* 鍵會在下一條訊息時生效 — 無需 Gateway 重啟、/reset 或會話輪替。快取的代理簽名包含這些鍵，因此 Gateway 在偵測到變更時會透明地重建代理。API 金鑰和工具/技能設定仍需要通常的重載路徑。

常見設定

預設（自動偵測）— 無需設定：

compression:
  enabled: true
  threshold: 0.50

使用你的主要提供者和主要模型。如果你想要在比主要聊天模型更便宜的模型上進行壓縮，可逐任務覆寫（例如 auxiliary.compression.provider: openrouter + model: google/gemini-2.5-flash）。

強制使用特定提供者（OAuth 或 API 金鑰）：

auxiliary:
  compression:
    provider: nous
    model: gemini-3-flash

適用於任何提供者：nous、openrouter、codex、anthropic、main 等。

自訂端點（自架、Ollama、zai、DeepSeek 等）：

auxiliary:
  compression:
    model: glm-4.7
    base_url: https://api.z.ai/api/coding/paas/v4

指向自訂的 OpenAI 相容端點。使用 OPENAI_API_KEY 進行認證。

三個旋鈕的互動方式

警告 — 摘要模型上下文長度要求

摘要模型必須具有至少與你的主要代理模型一樣大的上下文視窗。壓縮器將對話的完整中間部分傳送給摘要模型 — 如果該模型的上下文視窗小於主要模型，摘要呼叫將因上下文長度錯誤而失敗。當這種情況發生時，中間回合會在沒有摘要的情況下被丟棄，默默地丟失對話上下文。如果你覆寫了模型，請驗證其上下文長度符合或超過你的主要模型。

上下文引擎

上下文引擎控制當接近模型代幣限制時如何管理對話。內建的 compressor 引擎使用有損摘要（見 上下文壓縮）。外掛引擎可以用替代策略替換它。

context:
  engine: "compressor"    # 預設值 — 內建有損摘要

要使用外掛引擎（例如 LCM 用於無損上下文管理）：

context:
  engine: "lcm"          # 必須與外掛的名稱匹配

外掛引擎永遠不會自動啟用 — 你必須明確設定 context.engine 為外掛名稱。可用的引擎可透過 hermes plugins → Provider Plugins → Context Engine 瀏覽和選擇。

詳見 記憶提供者 了解記憶外掛的類似單選系統。

迭代預算壓力

當代理正在處理具有許多工具呼叫的複雜任務時，它可能會在未意識到的情況下耗盡迭代預算（預設：90 個回合）。預算壓力會在接近限制時自動警告模型：

警告被注入到最後一個工具結果的 JSON 中（作為 _budget_warning 欄位），而非作為單獨的訊息 — 這保留了提示快取且不打斷對話結構。

agent:
  max_turns: 90                # 每個對話回合的最大迭代數（預設：90）
  api_max_retries: 3           # 切換到備選提供者之前的重試次數（預設：3）

預算壓力預設啟用。代理自然地將警告視為工具結果的一部分，鼓勵它整合工作並在迭代耗盡前交付回應。

當迭代預算完全耗盡時，CLI 會向使用者顯示通知：⚠ Iteration budget reached (90/90) — response may be incomplete。如果預算在主動工作中耗盡，代理會在停止前產生已完成工作的摘要。

agent.api_max_retries 控制 Hermes 在暫時性錯誤（速率限制、連線中斷、5xx）上重試提供者 API 呼叫的次數之後才啟用備選提供者切換。預設為 3 — 總共四次嘗試。如果你配置了備選提供者 並想要更快地故障轉移，將此值降至 0，使主要提供者上的第一個暫時性錯誤立即轉交給備選提供者，而非對不穩定的端點進行重試。

API 逾時

Hermes 具有獨立的串流逾時層，以及非串流呼叫的過期偵測器。過期偵測器僅在你保持其隱式預設值時才自動調整本地提供者。

Socket 讀取逾時控制 httpx 從提供者等待下一個資料區塊的時間。本地 LLM 在大型上下文上進行預填充時可能需要數分鐘才產生第一個代幣，因此 Hermes 在偵測到本地端點時會將其提高到 30 分鐘。如果你明確設定 HERMES_STREAM_READ_TIMEOUT，不論端點偵測如何都始終使用該值。

過期串流偵測終止收到 SSE 保持連線 ping 但無實際內容的連線。這對本地提供者完全停用，因為它們在預填充期間不發送保持連線 ping。

過期非串流偵測終止太久未產生回應的非串流呼叫。預設情況下 Hermes 在本地端點上停用此功能以避免長時間預填充期間的誤報。如果你明確設定 providers.<id>.stale_timeout_seconds、providers.<id>.models.<model>.stale_timeout_seconds 或 HERMES_API_CALL_STALE_TIMEOUT，該明確值即使在本地端點上也會被遵守。

上下文壓力警告

與迭代預算壓力分開，上下文壓力追蹤對話距離壓縮閾值有多近 — 即上下文壓縮觸發以摘要較舊訊息的臨界點。這幫助你和代理了解對話何時變得過長。

在 CLI 中，上下文壓力以工具輸出中的進度列形式顯示：

  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

在訊息平台上，發送純文字通知：

◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

如果停用了自動壓縮，警告會改為告知上下文可能被截斷。

上下文壓力是自動的 — 無需設定。它純粹作為面向使用者的通知觸發，不會修改訊息流或向模型的上下文注入任何內容。

憑證池策略

當你有多個相同提供者的 API 金鑰或 OAuth 權杖時，設定輪替策略：

credential_pool_strategies:
  openrouter: round_robin    # 均勻輪替金鑰
  anthropic: least_used      # 始終選擇最少使用的金鑰

選項：fill_first（預設）、round_robin、least_used、random。詳見 憑證池 了解完整文件。

提示快取

Hermes 在活躍提供者支援時自動開啟跨會話提示快取 — 無需使用者設定。

對於在原生 Anthropic、OpenRouter 和 Nous Portal 上的 Claude，Hermes 在系統提示和技能區塊上附加 cache_control 斷點，TTL 為 1 小時（ttl: "1h"）。在同一個小時內的首次傳送支付完整輸入費率；同一個小時內跨任何會話的後續傳送以折扣的快取讀取費率從快取中拉取。這意味著系統提示、載入的技能內容和任何長上下文包含的早期部分在第一個小時內跨 hermes 會話和跨分叉子代理重用。

Qwen Cloud（Alibaba DashScope）上游將快取 TTL 上限設為 5 分鐘，因此 Hermes 在該處使用 5 分鐘的斷點 TTL。其他透過第三方的 Claude 路徑（AWS Bedrock、Azure Foundry）回退到提供者自身的快取預設值。xAI Grok 使用單獨的會話綁定 conversation-id 機制 — 見 xAI 提示快取。

沒有可用於關閉此功能的設定 — 快取始終啟用，即使在單回合對話中也能省錢，因為僅系統提示就是輸入代幣數量的相當大比例。

輔助模型

Hermes 使用「輔助」模型處理輔助任務，如圖片分析、網頁摘要、瀏覽器截圖分析、會話標題生成和上下文壓縮。預設情況下（auxiliary.*.provider: "auto"），Hermes 將每個輔助任務路由到你的主要聊天模型 — 即你在 hermes model 中選擇的相同提供者/模型。你無需設定任何內容即可開始，但要注意在昂貴的推理模型（Opus、MiniMax M2.7 等）上，輔助任務會增加顯著成本。如果你想要不論主要模型為何都使用便宜快速的輔助任務，請明確設定 auxiliary.<task>.provider 和 auxiliary.<task>.model（例如 OpenRouter 上的 Gemini Flash 用於視覺和網頁提取）。

注意 — 為什麼「auto」使用你的主要模型

較早的版本將聚合使用者（OpenRouter、Nous Portal）分流到便宜的提供者端預設值。這令人驚訝 — 支付聚合訂閱的使用者會看到不同的模型處理其輔助流量。auto 現在對所有人都使用主要模型，config.yaml 中的逐任務覆寫仍然有效（見下方完整輔助設定參考）。

互動式設定輔助模型

與其手動編輯 YAML，不如執行 hermes model 並從選單中選擇**「Configure auxiliary models」**。你會獲得一個互動式的逐任務選擇器：

$ hermes model
→ Configure auxiliary models

[ ] vision               目前：auto / main model
[ ] web_extract          目前：auto / main model
[ ] title_generation     目前：openrouter / google/gemini-3-flash-preview
[ ] tts_audio_tags       目前：auto / main model
[ ] compression          目前：auto / main model
[ ] approval             目前：auto / main model
[ ] triage_specifier     目前：auto / main model
[ ] kanban_decomposer    目前：auto / main model
[ ] profile_describer    目前：auto / main model

選擇一個任務、選擇一個提供者（OAuth 流程會開啟瀏覽器；API 金鑰提供者會提示）、選擇一個模型。變更會持久化到 config.yaml 中的 auxiliary.<task>.*。與主要模型選擇器相同的機制 — 無需學習額外語法。

影片教學

影片： 在 YouTube 上觀看

通用設定模式

Hermes 中的每個模型插槽 — 輔助任務、壓縮、備選 — 都使用相同的三個旋鈕：

當設定 base_url 時，Hermes 忽略提供者並直接呼叫該端點（使用 api_key 或 OPENAI_API_KEY 進行認證）。當僅設定 provider 時，Hermes 使用該提供者的內建認證和基礎 URL。

輔助任務的可用提供者：auto、main，加上提供者登錄檔中的任何提供者 — openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、gemini、google-gemini-cli、qwen-oauth、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、minimax-oauth、deepseek、nvidia、xai、xai-oauth、ollama-cloud、alibaba、bedrock、huggingface、arcee、xiaomi、kilocode、opencode-zen、opencode-go、azure-foundry — 或你 custom_providers 列表中的任何命名自訂提供者（例如 provider: "beans"）。

提示 — MiniMax OAuth

minimax-oauth 透過瀏覽器 OAuth 登入（無需 API 金鑰）。執行 hermes model 並選擇 MiniMax (OAuth) 進行認證。輔助任務自動使用 MiniMax-M2.7-highspeed。詳見 MiniMax OAuth 指南。

提示 — xAI Grok OAuth

xai-oauth 透過瀏覽器 OAuth 登入，適用於 SuperGrok 和 X Premium+ 訂閱者（無需 API 金鑰）。執行 hermes model 並選擇 xAI Grok OAuth (SuperGrok / Premium+) 進行認證。同一個 OAuth 權杖會在每個直接到 xAI 的介面（聊天、輔助任務、TTS、圖片生成、影片生成、轉錄）中重用。詳見 xAI Grok OAuth 指南，如果 Hermes 在遠端主機上，請參閱 透過 SSH / 遠端主機進行 OAuth。

警告 — "main" 僅用於輔助任務

"main" 提供者選項意味著「使用我的主要代理使用的任何提供者」— 它僅在 auxiliary:、compression: 和主要備選條目（fallback_providers: 或舊版 fallback_model:）中有效。它不是你的頂層 model.provider 設定的有效值。如果你使用自訂的 OpenAI 相容端點，請在你的 model: 區段中設定 provider: custom。詳見 AI 提供者 了解所有主要模型提供者選項。

完整輔助設定參考

auxiliary:
  # 圖片分析（vision_analyze 工具 + 瀏覽器截圖）
  vision:
    provider: "auto"           # "auto"、"openrouter"、"nous"、"codex"、"main" 等
    model: ""                  # 例如 "openai/gpt-4o"、"google/gemini-2.5-flash"
    base_url: ""               # 自訂 OpenAI 相容端點（覆寫提供者）
    api_key: ""                # base_url 的 API 金鑰（回退到 OPENAI_API_KEY）
    timeout: 120               # 秒 — LLM API 呼叫逾時；視覺負載需要慷慨的逾時
    download_timeout: 30       # 秒 — 圖片 HTTP 下載；對慢速連線可增加

  # 網頁摘要 + 瀏覽器頁面文字提取
  web_extract:
    provider: "auto"
    model: ""                  # 例如 "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # 秒（6 分鐘）— 逐次嘗試 LLM 摘要

  # 危險指令審批分類器
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30                # 秒

  # Gemini 3.1 TTS 隱藏音訊標籤插入
  tts_audio_tags:
    provider: "auto"
    model: ""                  # 空 = 主要聊天模型
    base_url: ""
    api_key: ""
    timeout: 30

  # 上下文壓縮逾時（與 compression.* 設定分開）
  compression:
    timeout: 120               # 秒 — 壓縮摘要長對話，需要更多時間

  # 技能中心 — 技能匹配和搜尋
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP 工具分派
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Kanban 分診規格化器 — `hermes kanban specify <id>`（或
  # 儀表板的 ✨ Specify 按鈕在分診欄卡片上）使用此
  # 插槽將一行描述擴展為具體規格並將
  # 任務提升為 `todo`。便宜快速的模型在這裡效果很好；規格擴展
  # 簡短且不需要深度推理。
  triage_specifier:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 120

提示

每個輔助任務都有一個可設定的 timeout（以秒為單位）。預設值：vision 120 秒、web_extract 360 秒、approval 30 秒、compression 120 秒。如果你使用緩慢的本地模型進行輔助任務，可增加這些值。視覺還有單獨的 download_timeout（預設 30 秒）用於 HTTP 圖片下載 — 對慢速連線或自架圖片伺服器可增加此值。

資訊

上下文壓縮有獨立的 compression: 區塊用於閾值設定和 auxiliary.compression: 區塊用於模型/提供者設定 — 見上方上下文壓縮。主要備選鏈使用頂層的 fallback_providers: 列表 — 見備選提供者。三者都遵循相同的 provider/model/base_url 模式。

OpenRouter 路由與 Pareto Code 用於輔助任務

當輔助任務解析到 OpenRouter（明確設定或透過 provider: "main" 且你的主要代理在 OpenRouter 上），主要代理的 provider_routing 和 openrouter.min_coding_score 設定不會傳播 — 設計如此，每個輔助任務是獨立的。要為特定輔助任務設定 OpenRouter 提供者偏好或使用 Pareto Code 路由器，請透過 extra_body 逐任務設定：

auxiliary:
  compression:
    provider: openrouter
    model: openrouter/pareto-code         # 此任務使用 Pareto Code 路由器
    extra_body:
      provider:                            # OpenRouter 提供者路由偏好
        order: [anthropic, google]         # 按此順序嘗試這些提供者
        sort: throughput                   # 或 "price" | "latency"
        # only: [anthropic]                # 限制到特定提供者
        # ignore: [deepinfra]              # 排除特定提供者
      plugins:                             # OpenRouter Pareto Code 路由器設定
        - id: pareto-router
          min_coding_score: 0.5            # 0.0–1.0；越高 = 越強的程式碼能力

其結構與 OpenRouter 在 chat completions 請求主體中接受的格式一致。Hermes 逐字轉發整個 extra_body，因此 openrouter.ai/docs 上記錄的任何其他 OpenRouter 請求主體欄位都以相同方式運作。

更換視覺模型

要使用 GPT-4o 而非 Gemini Flash 進行圖片分析：

auxiliary:
  vision:
    model: "openai/gpt-4o"

或透過環境變數（在 ~/.hermes/.env 中）：

AUXILIARY_VISION_MODEL=openai/gpt-4o

提供者選項

這些選項適用於輔助任務設定（auxiliary:、compression:）和主要備選條目（fallback_providers: 或舊版 fallback_model:），不適用於你的主要 model.provider 設定。

來自主要提供者目錄的直接 API 金鑰提供者也可在此使用，當你想讓輔助任務繞過你的預設路由器時。gmi 在設定 GMI_API_KEY 後有效：

auxiliary:
  compression:
    provider: "gmi"
    model: "anthropic/claude-opus-4.6"

對於 GMI 輔助路由，使用 GMI 的 /v1/models 端點返回的確切模型 ID。

常見設定

使用直接自訂端點（比 provider: "main" 更明確，適用於本地/自架 API）：

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url 的優先順序高於 provider，因此這是將輔助任務路由到特定端點的最明確方式。對於直接端點覆寫，Hermes 使用設定的 api_key 或回退到 OPENAI_API_KEY；它不會為該自訂端點重用 OPENROUTER_API_KEY。

使用 OpenAI API 金鑰進行視覺：

# 在 ~/.hermes/.env 中：
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_API_KEY=sk-...

auxiliary:
  vision:
    provider: "main"
    model: "gpt-4o"       # 或 "gpt-4o-mini" 以降低成本

使用 OpenRouter 進行視覺（路由到任何模型）：

auxiliary:
  vision:
    provider: "openrouter"
    model: "openai/gpt-4o"      # 或 "google/gemini-2.5-flash" 等

使用 Codex OAuth（ChatGPT Pro/Plus 帳號 — 無需 API 金鑰）：

auxiliary:
  vision:
    provider: "codex"     # 使用你的 ChatGPT OAuth 權杖
    # model 預設為 gpt-5.3-codex（支援視覺）

使用 MiniMax OAuth（瀏覽器登入，無需 API 金鑰）：

model:
  default: MiniMax-M2.7
  provider: minimax-oauth
  base_url: https://api.minimax.io/anthropic

執行 hermes model 並選擇 MiniMax (OAuth) 來自動登入和設定。中國區域的基礎 URL 為 https://api.minimaxi.com/anthropic。詳見 MiniMax OAuth 指南 了解完整操作流程。

使用本地/自架模型：

auxiliary:
  vision:
    provider: "main"      # 使用你的活躍自訂端點
    model: "my-local-model"

provider: "main" 使用 Hermes 正常聊天使用的任何提供者 — 不論是命名的自訂提供者（例如 beans）、openrouter 等內建提供者，還是舊版的 OPENAI_BASE_URL 端點。

提示

如果你使用 Codex OAuth 作為主要模型提供者，視覺會自動運作 — 無需額外設定。Codex 包含在視覺的自動偵測鏈中。

警告

視覺需要多模態模型。 如果你設定 provider: "main"，請確保你的端點支援多模態/視覺 — 否則圖片分析將會失敗。

環境變數（舊版）

輔助模型也可透過環境變數設定。然而，config.yaml 是首選方法 — 它更容易管理且支援所有選項，包括 base_url 和 api_key。

壓縮和備選模型設定僅限 config.yaml。

提示

執行 hermes config 查看你目前的輔助模型設定。僅在與預設值不同時才顯示覆寫。

推理努力程度

控制模型在回應前進行多少「思考」：

agent:
  reasoning_effort: ""   # 空 = medium（預設）。選項：none、minimal、low、medium、high、xhigh（最大）

未設定時（預設），推理 effort 預設為 "medium" — 一個對大多數任務都適用的平衡等級。設定值會覆寫它 — 更高的推理 effort 在複雜任務上提供更好的結果，但代價是更多代幣和延遲。

注意 — 自適應思考模型（Claude 4.6+、Fable/Mythos 級別）透過 OpenRouter

這些模型使用自適應思考，不接受通常的 reasoning.effort 欄位 — OpenRouter 會忽略它。Hermes 透明地將你的 reasoning_effort 路由到 OpenRouter 的 verbosity 參數（對應到 Anthropic 的 output_config.effort），因此相同的 low/medium/high/xhigh 旋鈕繼續運作 — 無需額外設定。none（或未設定）讓 模型保持其自適應預設值。（max 在線路傳輸中被接受，但不是 可選的 reasoning_effort 值；xhigh 是可設定的上限。） 原生 Anthropic 提供者已直接控制 effort 且不受影響。

你也可以在執行時使用 /reasoning 指令更改推理 effort：

/reasoning           # 顯示目前 effort 等級和顯示狀態
/reasoning high      # 將推理 effort 設為 high
/reasoning none      # 停用推理
/reasoning show      # 在每個回應上方顯示模型思考
/reasoning hide      # 隱藏模型思考

工具使用強制

有些模型偶爾會以文字描述預期動作而非進行工具呼叫（「我會執行測試...」而非實際呼叫終端機）。工具使用強制會注入系統提示指導，引導模型回到實際呼叫工具。

agent:
  tool_use_enforcement: "auto"   # "auto" | true | false | ["model-substring", ...]

注入的內容

啟用後，可能向系統提示添加三層指導：

1. 通用工具使用強制（所有匹配的模型）— 指示模型立即進行工具呼叫而非描述意圖、持續工作直到任務完成、永遠不要以未來行動的承諾結束回合。

2. OpenAI 執行紀律（僅 GPT 和 Codex 模型）— 針對 GPT 特定失敗模式的額外指導：在部分結果上放棄工作、跳過先決條件查詢、產生幻覺而非使用工具、在未驗證的情況下宣告「完成」。

3. Google 操作指導（僅 Gemini 和 Gemma 模型）— 簡潔性、絕對路徑、並行工具呼叫和編輯前驗證模式。

這些對使用者是透明的，僅影響系統提示。已經可靠使用工具的模型（如 Claude）不需要此指導，這就是為什麼 "auto" 排除了它們。

何時開啟

如果你使用的模型不在預設自動清單中，且注意到它經常描述它會做什麼而非實際執行，請設定 tool_use_enforcement: true 或將模型子字串加入列表：

agent:
  tool_use_enforcement: ["gpt", "codex", "gemini", "grok", "my-custom-model"]

TTS 設定

tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts"
  speed: 1.0                    # 全域速度乘數（所有提供者的回退值）
  edge:
    voice: "en-US-AriaNeural"   # 322 種語音，74 種語言
    speed: 1.0                  # 速度乘數（轉換為速率百分比，例如 1.5 → +50%）
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # alloy、echo、fable、onyx、nova、shimmer
    speed: 1.0                  # 速度乘數（由 API 限制在 0.25–4.0 範圍內）
    base_url: "https://api.openai.com/v1"  # 用於 OpenAI 相容 TTS 端點的覆寫
  minimax:
    speed: 1.0                  # 語音速度乘數
    # base_url: ""              # 選填：用於 OpenAI 相容 TTS 端點的覆寫
  mistral:
    model: "voxtral-mini-tts-2603"
    voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8"  # Paul - 中性（預設）
  gemini:
    model: "gemini-2.5-flash-preview-tts"   # 或 gemini-3.1-flash-tts-preview
    voice: "Kore"               # 30 種預建語音：Zephyr、Puck、Kore、Enceladus 等
    audio_tags: false           # 隱藏 Gemini 3.1 TTS 音訊標籤插入
    persona_prompt_file: ""      # 選填的 Markdown/純文字檔案，包含 Gemini 語音方向
  xai:
    voice_id: "eve"             # xAI TTS 語音
    language: "en"              # ISO 639-1
    sample_rate: 24000
    bit_rate: 128000            # MP3 位元率
    # base_url: "https://api.x.ai/v1"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

這同時控制 text_to_speech 工具和語音模式中的語音回覆（CLI 中的 /voice tts 或訊息 Gateway）。

速度回退層級： 提供者特定速度（例如 tts.edge.speed）→ 全域 tts.speed → 1.0 預設值。設定全域 tts.speed 可在所有提供者上套用統一速度，或逐提供者覆寫以進行精細控制。

顯示設定

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # 在訊息 Gateway 中啟用 /verbose 斜線指令
  platforms: {}           # 各平台顯示覆寫（見下文）
  tool_progress_overrides: {}  # 已棄用 — 請改用 display.platforms
  interim_assistant_messages: true  # Gateway：將自然的中途助理更新作為單獨訊息發送
  skin: default           # 內建或自訂 CLI 外觀（見 user-guide/features/skins）
  personality: "kawaii"  # 舊版裝飾性欄位，仍在某些摘要中顯示
  compact: false          # 精簡輸出模式（較少空白）
  resume_display: full    # full（恢復時顯示先前訊息）| minimal（僅一行）
  bell_on_complete: false # 代理完成時播放終端機鈴聲（適用於長任務）
  show_reasoning: false   # 在每個回應上方顯示模型推理/思考（透過 /reasoning show|hide 切換）
  streaming: false        # 代幣到達時即時串流到終端機（即時輸出）
  show_cost: false        # 在 CLI 狀態列中顯示預估 $ 成本
  timestamps: false       # 為 true 時，在 CLI / TUI 對話紀錄中為用戶和助理標籤添加 [HH:MM] 時間戳
  tool_preview_length: 0  # 工具呼叫預覽的最大字元數（0 = 無限制，顯示完整路徑/指令）
  runtime_footer:         # Gateway：在最終回覆後附加運行時上下文頁尾
    enabled: false
    fields: ["model", "context_pct", "cwd"]
  file_mutation_verifier: true    # 當 write_file/patch 呼叫在本回合失敗時附加建議性頁尾
  credits_notices: true   # Nous credits 狀態列通知（使用量區段、授權已用、已耗盡）。false = 靜音；/usage 仍可使用
  language: en            # 靜態訊息的 UI 語言（審批提示、部分 Gateway 回覆）。en | zh | zh-hant | ja | de | es | fr | tr | uk | af | ko | it | ga | pt | ru | hu

檔案變更驗證器

當 display.file_mutation_verifier 為 true（預設）時，Hermes 會在 write_file 或 patch 呼叫在回合期間失敗且從未被對同一路徑的成功寫入取代時，在助理的最終回覆後附加一行建議性文字。這捕捉了「並行修補批次，一半靜默失敗，模型總結成功」這類過度宣稱的情況，無需你在每次編輯後手動執行 git status。

範例頁尾：

⚠️ File-mutation verifier: 3 file(s) were NOT modified this turn despite any wording above that may suggest otherwise. Run `git status` or `read_file` to confirm.
  • concepts/automatic-organization.md — [patch] Could not find match for old_string
  • concepts/lora.md — [patch] Could not find match for old_string
  • concepts/rag-pipeline.md — [patch] Could not find match for old_string

設定 file_mutation_verifier: false（或 HERMES_FILE_MUTATION_VERIFIER=0）可關閉頁尾。驗證器僅在回合結束時仍有未解決的真實失敗時觸發 — 在同一回合中重試失敗修補並成功的模型不會對該檔案觸發它。

靜態訊息的 UI 語言

display.language 設定翻譯一小組靜態的面向使用者訊息 — CLI 審批提示、少量 Gateway 斜線指令回覆（例如 restart-drain 通知、「approval expired」、「goal cleared」）。它不會翻譯代理回覆、日誌行、工具輸出、錯誤追溯或斜線指令描述 — 這些保持英文。如果你想讓代理本身以另一種語言回覆，只需在你的提示或系統訊息中告訴它。

支援的值：en（預設）、zh（簡體中文）、zh-hant（繁體中文）、ja（日文）、de（德文）、es（西班牙文）、fr（法文）、tr（土耳其文）、uk（烏克蘭文）、af（南非荷蘭文）、ko（韓文）、it（義大利文）、ga（愛爾蘭文）、pt（葡萄牙文）、ru（俄文）、hu（匈牙利文）。未知值回退到英文。

你也可以透過 HERMES_LANGUAGE 環境變數逐會話設定，這會覆寫設定值。

display:
  language: zh   # CLI 審批提示以中文顯示

在 CLI 中，使用 /verbose 循環切換這些模式。要在訊息平台（Telegram、Discord、Slack 等）中使用 /verbose，請在上方的 display 區段中設定 tool_progress_command: true。該指令將會循環模式並儲存到設定。

工具進度需要一個能安全顯示進度更新的 Gateway 適配器。不支援訊息編輯的平台（包括 Signal）會抑制工具進度氣泡，即使 /verbose 儲存了非 off 模式。

運行時中繼資料頁尾（僅 Gateway）

當 display.runtime_footer.enabled: true 時，Hermes 在每個 Gateway 回合的最終訊息後附加一個小型運行時上下文頁尾。目前頁尾可顯示模型、上下文視窗百分比和目前工作目錄。預設關閉；如果你的團隊希望每個回覆都包含此來源資訊，可按 Gateway 選擇加入。

display:
  runtime_footer:
    enabled: true
    fields: ["model", "context_pct", "cwd"]   # 支援的欄位：model、context_pct、cwd

/footer 斜線指令在任何會話中執行時切換此功能。

附加到 Telegram/Discord/Slack 回覆的範例頁尾：

— claude-opus-4.7 · 12 tool calls · 2m 14s · $0.042

僅回合的最終訊息獲得頁尾；中途更新保持乾淨。

各平台進度覆寫

不同平台有不同的詳細程度需求。使用 display.platforms 設定各平台模式：

display:
  tool_progress: all          # 全域預設
  platforms:
    signal:
      tool_progress: 'off'    # Signal 目前無法顯示工具進度氣泡
    telegram:
      tool_progress: verbose  # Telegram 上的詳細進度
    slack:
      tool_progress: 'off'    # 在共用 Slack 工作區中保持安靜

沒有覆寫的平台回退到全域 tool_progress 值。有效的平台鍵：telegram、discord、slack、signal、whatsapp、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles、qqbot。舊版 display.tool_progress_overrides 鍵仍為向後相容而載入，但已棄用並在首次載入時遷移到 display.platforms。

Signal 被列為有效的平台鍵，因為該設定可以按平台儲存，但目前的 Signal 適配器無法編輯已發送的訊息且不渲染工具進度氣泡。保持 Signal tool_progress 設為 off；如果你需要即時觀看每個工具呼叫，請使用 CLI 或支援編輯的訊息平台。

interim_assistant_messages 僅限 Gateway。啟用時，Hermes 將完成的中途助理更新作為單獨的聊天訊息發送。這獨立於 tool_progress 且不需要 Gateway 串流。

隱私

privacy:
  redact_pii: false  # 從 LLM 上下文移除 PII（僅 Gateway）

當 redact_pii 為 true 時，Gateway 會在支援的平台上將系統提示中的個人識別資訊遮蔽後再傳送給 LLM：

平台支援： 遮蔽適用於 WhatsApp、Signal 和 Telegram。Discord 和 Slack 被排除，因為它們的提及系統（<@user_id>）需要 LLM 上下文中保留真實 ID。

雜湊是確定性的 — 相同的用戶始終映射到相同的雜湊，因此模型仍能在群組聊天中區分用戶。路由和傳遞在內部使用原始值。

語音轉文字（STT）

stt:
  provider: "local"            # "local" | "groq" | "openai" | "mistral"
  local:
    model: "base"              # tiny、base、small、medium、large-v3
  openai:
    model: "whisper-1"         # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
  # model: "whisper-1"         # 舊版回退鍵仍被尊重

提供者行為：

• local 使用在你機器上運行的 faster-whisper。使用 pip install faster-whisper 單獨安裝。
• groq 使用 Groq 的 Whisper 相容端點並讀取 GROQ_API_KEY。
• openai 使用 OpenAI 語音 API 並讀取 VOICE_TOOLS_OPENAI_KEY。

如果請求的提供者不可用，Hermes 按以下順序自動回退：local → groq → openai。

Groq 和 OpenAI 模型覆寫由環境驅動：

STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OPENAI_MODEL=whisper-1
GROQ_BASE_URL=https://api.groq.com/openai/v1
STT_OPENAI_BASE_URL=https://api.openai.com/v1

語音模式（CLI）

voice:
  record_key: "ctrl+b"         # CLI 內的按鍵對話按鍵
  max_recording_seconds: 120    # 長錄音的硬停止
  auto_tts: false               # 當 /voice on 時自動啟用語音回覆
  beep_enabled: true            # 在 CLI 語音模式中播放錄音開始/結束提示音
  silence_threshold: 200        # 語音偵測的 RMS 閾值
  silence_duration: 3.0         # 自動停止前的靜音秒數

在 CLI 中使用 /voice on 啟用麥克風模式，使用 record_key 開始/停止錄音，使用 /voice tts 切換語音回覆。詳見 語音模式 了解端到端設定和平台特定行為。

串流

在代幣到達時即時串流到終端機或訊息平台，而非等待完整回應。

CLI 串流

display:
  streaming: true         # 代幣即時串流到終端機
  show_reasoning: true    # 同時串流推理/思考代幣（選填）

啟用後，回應在串流框中逐代幣顯示。工具呼叫仍被靜默捕獲。如果提供者不支援串流，會自動回退到正常顯示。

Gateway 串流（Telegram、Discord、Slack）

streaming:
  enabled: true           # 啟用漸進式訊息編輯
  transport: edit         # "edit"（漸進式訊息編輯）或 "off"
  edit_interval: 0.3      # 訊息編輯間隔秒數
  buffer_threshold: 40    # 強制編輯刷新前的字元數
  cursor: " ▉"            # 串流期間顯示的游標
  fresh_final_after_seconds: 0    # 當預覽此秒數時選擇加入全新最終訊息（Telegram）

啟用後，機器人在第一個代幣時發送訊息，然後在更多代幣到達時漸進式編輯它。不支援訊息編輯的平台（Signal、Email、Home Assistant）會在第一次嘗試時自動偵測 — 該會話優雅地停用串流，不會產生訊息洪水。

如需不使用漸進式代幣編輯的單獨自然中途助理更新，請設定 display.interim_assistant_messages: true。

溢位處理： 如果串流文字超過平台的訊息長度限制（~4096 字元），目前訊息會被最終化並自動開始新的訊息。

全新最終訊息（Telegram）： Telegram 的 editMessageText 保留原始訊息時間戳，因此長時間運行的串流回覆即使完成後也會保留第一個代幣的時間戳。設定 fresh_final_after_seconds > 0 以選擇將舊預覽作為全新的最終訊息發送，並盡力刪除預覽。預設為 0，始終就地最終化串流回覆，避免在同時顯示兩種操作的客戶端上出現短暫的重複訊息/刪除序列。

注意 — 各平台串流預設值

主要的 streaming.enabled 開關預設為 false — 在你翻轉之前沒有任何串流。一旦啟用，串流按平台決定：Telegram 附帶 display.platforms.telegram.streaming: true（串流），Discord 附帶 display.platforms.discord.streaming: false（不串流）。因此啟用串流後，Telegram 開箱即用串流，Discord 保持整體訊息回覆直到你更改其開關。你可以從儀表板的 Channels 開關或直接在 ~/.hermes/config.yaml 中調整這些各平台開關。

群組聊天會話隔離

限制 CLI、TUI/儀表板和訊息 Gateway 之間可以同時開啟的聊天會話數量：

max_concurrent_sessions: null  # null/0 = 無限制；正整數 = 活躍會話上限

達到上限時，Hermes 為新會話返回直接的限制訊息。現有活躍會話保持正常行為。

正規的鍵是頂層 max_concurrent_sessions。Hermes 也接受 gateway.max_concurrent_sessions 作為回退，但頂層鍵在兩者都設定時獲勝。

上限使用本機運行時租賃檔案強制執行，是尽力而為的：如果登錄檔無法讀取或鎖定，Hermes 會 fail-open 以免使用者受困。它適用於單一主機/Profile 運行時，不適用於跨多台機器共享的 $HERMES_HOME。

控制共享聊天是每個房間保留一個對話還是每個參與者一個對話：

group_sessions_per_user: true  # true = 群組/頻道中的逐用戶隔離，false = 每個聊天一個共享會話

• true 是預設且建議的設定。在 Discord 頻道、Telegram 群組、Slack 頻道和類似的共享上下文中，當平台提供用戶 ID 時，每個發送者獲得自己的會話。
• false 回退到舊的共享房間行為。如果你明確希望 Hermes 將頻道視為一個協作對話，這很有用，但它也意味著使用者共享上下文、代幣成本和中斷狀態。
• 私訊不受影響。Hermes 仍然照常以聊天/私訊 ID 為私訊設定鍵。
• 討論串無論如何都與其父頻道隔離；設定為 true 時，每個參與者在討論串中也獲得自己的會話。

詳見 會話 和 Discord 指南 了解行為細節和範例。

未授權私訊行為

控制當未知使用者發送私訊時 Hermes 的行為：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

• pair 是預設值。Hermes 拒絕存取，但在私訊中回覆一次性配對碼。
• ignore 靜默丟棄未授權的私訊。
• 平台區段覆寫全域預設值，因此你可以廣泛保持配對啟用，同時讓一個平台更安靜。

快速指令

定義不調用 LLM 即可執行 shell 指令的自訂指令，或將一個斜線指令別名到另一個。exec 快速指令是零代幣的，適用於訊息平台（Telegram、Discord 等）中的快速伺服器檢查或實用腳本。

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  disk:
    type: exec
    command: df -h /
  update:
    type: exec
    command: cd ~/.hermes/hermes-agent && git pull && pip install -e .
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader
  restart:
    type: alias
    target: /gateway restart

用法：在 CLI 或任何訊息平台中輸入 /status、/disk、/update、/gpu 或 /restart。exec 指令在主機上本地運行並直接返回輸出 — 無 LLM 呼叫、無代幣消耗。alias 指令重寫為設定的斜線指令目標。

• 30 秒逾時 — 長時間運行的指令會被終止並返回錯誤訊息
• 優先順序 — 快速指令在技能指令之前檢查，因此你可以覆寫技能名稱
• 自動補全 — 快速指令在分派時解析，不會出現在內建斜線指令自動補全表中
• 類型 — 支援的類型是 exec 和 alias；其他類型會顯示錯誤
• 到處可用 — CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

純字串的提示捷徑不是有效的快速指令。對於可重用的提示工作流程，建立技能或別名到現有的斜線指令。

人工延遲

在訊息平台中模擬人類般的回應節奏：

human_delay:
  mode: "off"                  # off | natural | custom
  min_ms: 800                  # 最小延遲（custom 模式）
  max_ms: 2500                 # 最大延遲（custom 模式）

程式碼執行

設定 execute_code 工具：

code_execution:
  mode: project                # project（預設）| strict
  timeout: 300                 # 最大執行時間（秒）
  max_tool_calls: 50           # 程式碼執行中的最大工具呼叫數

mode 控制腳本的工作目錄和 Python 解釋器：

• project（預設）— 腳本在會話的工作目錄中運行，使用活躍的 virtualenv/conda 環境的 Python。專案依賴（pandas、torch、專案套件）和相對路徑（.env、./data.csv）自然解析，與 terminal() 所見的一致。
• strict — 腳本在暫存目錄中運行，使用 sys.executable（Hermes 自身的 Python）。最大可重現性，但專案依賴和相對路徑不會解析。

環境清理（移除 *_API_KEY、*_TOKEN、*_SECRET、*_PASSWORD、*_CREDENTIAL、*_PASSWD、*_AUTH）和工具白名單在兩種模式下相同套用 — 切換模式不會改變安全態勢。

網頁搜尋後端

web_search 和 web_extract 工具支援五個後端提供者。在 config.yaml 或透過 hermes tools 設定後端：

web:
  backend: firecrawl    # firecrawl | searxng | parallel | tavily | exa

  # 或使用各能力鍵混合提供者（例如免費搜尋 + 付費提取）：
  search_backend: "searxng"
  extract_backend: "firecrawl"

後端選擇： 如果未設定 web.backend，後端會從可用的 API 金鑰自動偵測。如果僅設定 SEARXNG_URL，使用 SearXNG。如果僅設定 EXA_API_KEY，使用 Exa。如果僅設定 TAVILY_API_KEY，使用 Tavily。如果僅設定 PARALLEL_API_KEY，使用 Parallel。否則 Firecrawl 是預設值。

SearXNG 是一個免費、自架、尊重隱私的元搜尋引擎，查詢 70 多個搜尋引擎。無需 API 金鑰 — 只需將 SEARXNG_URL 設為你的實例（例如 http://localhost:8080）。SearXNG 僅限搜尋；web_extract 需要單獨的提取提供者（設定 web.extract_backend）。詳見 網頁搜尋設定指南 了解 Docker 設定說明。

自架 Firecrawl： 設定 FIRECRAWL_API_URL 指向你自己的實例。設定自訂 URL 時，API 金鑰變為選填（在伺服器上設定 USE_DB_AUTHENTICATION=*** 以停用認證）。

Parallel 搜尋模式： 設定 PARALLEL_SEARCH_MODE 控制搜尋行為 — fast、one-shot 或 agentic（預設：agentic）。

Exa： 在 ~/.hermes/.env 中設定 EXA_API_KEY。支援 category 篩選（company、research paper、news、people、personal site、pdf）和網域/日期篩選。

瀏覽器

設定瀏覽器自動化行為：

browser:
  inactivity_timeout: 120        # 自動關閉閒置會話前的秒數
  command_timeout: 30             # 瀏覽器指令的逾時秒數（截圖、導航等）
  record_sessions: false         # 自動將瀏覽器會話錄製為 WebM 影片到 ~/.hermes/browser_recordings/
  # 選填的 CDP 覆寫 — 設定後，Hermes 直接附加到你自己的
  # Chromium 系瀏覽器（透過 /browser connect），而非啟動無頭瀏覽器。
  cdp_url: ""
  # 對話監督器 — 控制當 CDP 後端附加時
  # 原生 JS 對話框（alert / confirm / prompt）
  # 的處理方式（Browserbase、透過 /browser connect 的本地 Chromium 系
  # 瀏覽器）。在 Camofox 和預設本地 agent-browser 模式下忽略。
  dialog_policy: must_respond    # must_respond | auto_dismiss | auto_accept
  dialog_timeout_s: 300          # must_respond 下的安全自動關閉（秒）
  camofox:
    managed_persistent: false   # 為 true 時，Camofox 會話跨重啟持久化 cookie/登入
    user_id: ""                  # 選填的外部管理 Camofox userId
    session_key: ""              # 選填的會話密鑰，Hermes 建立索引標籤時發送
    adopt_existing_tab: false    # 在建立新索引標籤之前重用此身份的現有索引標籤

對話策略：

• must_respond（預設）— 捕獲對話框，顯示在 browser_snapshot.pending_dialogs 中，等待代理呼叫 browser_dialog(action=...)。在 dialog_timeout_s 秒無回應後，對話框會被自動關閉以防止頁面的 JS 執行緒永遠卡住。
• auto_dismiss — 捕獲，立即關閉。代理事後仍在 browser_snapshot.recent_dialogs 中看到帶有 closed_by="auto_policy" 的對話框記錄。
• auto_accept — 捕獲，立即接受。適用於具有激進 beforeunload 提示的頁面。

詳見 瀏覽器功能頁面 了解完整的對話框工作流程。

瀏覽器工具組支援多個提供者。詳見 瀏覽器功能頁面 了解 Browserbase、Browser Use 和本地 Chromium 系 CDP 設定的詳細資訊。

時區

使用 IANA 時區字串覆寫伺服器本地時區。影響日誌中的時間戳、cron 排程和系統提示時間注入。

timezone: "America/New_York"   # IANA 時區（預設："" = 伺服器本地時間）

支援的值：任何 IANA 時區識別碼（例如 America/New_York、Europe/London、Asia/Kolkata、UTC）。留空或省略以使用伺服器本地時間。

Discord

設定訊息 Gateway 的 Discord 特定行為：

discord:
  require_mention: true          # 需要 @提及 才在伺服器頻道中回應
  free_response_channels: ""     # 以逗號分隔的頻道 ID 列表，機器人無需 @提及 即可回應
  auto_thread: true              # 在頻道中 @提及 時自動建立討論串

• require_mention — 設為 true（預設）時，機器人僅在伺服器頻道中被 @BotName 提及時回應。私訊始終無需提及即可運作。
• free_response_channels — 以逗號分隔的頻道 ID 列表，機器人對每則訊息回應而無需提及。
• auto_thread — 設為 true（預設）時，頻道中的提及自動為對話建立討論串，保持頻道乾淨（類似 Slack 討論串）。

安全

執行前安全掃描和密鑰遮蔽：

security:
  redact_secrets: true           # 遮蔽工具輸出和日誌中的 API 金鑰模式（預設開啟）
  tirith_enabled: true           # 為終端機指令啟用 Tirith 安全掃描
  tirith_path: "tirith"          # tirith 二進位檔路徑（預設：`$PATH` 中的 "tirith"）
  tirith_timeout: 5              # 等待 tirith 掃描的逾時秒數
  tirith_fail_open: true         # 若 tirith 不可用則允許指令執行
  website_blocklist:             # 見下方網域黑名單章節
    enabled: false
    domains: []
    shared_files: []

• redact_secrets — 設為 true 時，在工具輸出進入對話上下文和日誌之前，自動偵測並遮蔽看起來像 API 金鑰、權杖和密碼的模式。預設開啟。 僅在你需要原始的類似憑證字串進行除錯或遮蔽器開發時明確設為 false。
• tirith_enabled — 設為 true 時，終端機指令在執行前由 Tirith 掃描以偵測潛在危險操作。
• tirith_path — tirith 二進位檔路徑。如果 tirith 安裝在非標準位置，請設定此值。
• tirith_timeout — 等待 tirith 掃描的最大秒數。如果掃描逾時，指令會繼續執行。
• tirith_fail_open — 設為 true（預設）時，如果 tirith 不可用或失敗，指令被允許執行。設為 false 以在 tirith 無法驗證時阻止指令。

網域黑名單

阻止代理的網頁和瀏覽器工具存取特定網域：

security:
  website_blocklist:
    enabled: false               # 啟用 URL 封鎖（預設：false）
    domains:                     # 被封鎖的網域模式列表
      - "*.internal.company.com"
      - "admin.example.com"
      - "*.local"
    shared_files:                # 從外部檔案載入額外規則
      - "/etc/hermes/blocked-sites.txt"

啟用後，任何匹配被封鎖網域模式的 URL 在網頁或瀏覽器工具執行之前就會被拒絕。這適用於 web_search、web_extract、browser_navigate 和任何存取 URL 的工具。

網域規則支援：

• 確切網域：admin.example.com
• 萬用字元子網域：*.internal.company.com（封鎖所有子網域）
• TLD 萬用字元：*.local

共用檔案每行包含一個網域規則（空白行和 # 註解被忽略）。缺失或無法讀取的檔案會記錄警告但不會停用其他網頁工具。

策略快取 30 秒，因此設定變更無需重啟即可快速生效。

智慧審批

控制 Hermes 如何處理潛在危險的指令：

approvals:
  mode: manual   # manual | smart | off

智慧模式對於減少審批疲勞特別有用 — 它讓代理在安全操作上更自主地工作，同時仍然捕捉真正具有破壞性的指令。

警告

設定 approvals.mode: off 會停用終端機指令的所有安全檢查。僅在受信任的沙箱化環境中使用。

檢查點

在破壞性檔案操作之前的自動檔案系統快照。詳見 檢查點與回滾 了解細節。

checkpoints:
  enabled: false                 # 啟用自動檢查點（也可：hermes chat --checkpoints）。預設：false（需選擇加入）。
  max_snapshots: 20              # 每個目錄保留的最大檢查點數（預設：20）

委派

設定委派工具的子代理行為：

delegation:
  # model: "google/gemini-3-flash-preview"  # 覆寫模型（空 = 繼承父代）
  # provider: "openrouter"                  # 覆寫提供者（空 = 繼承父代）
  # base_url: "http://localhost:1234/v1"    # 直接的 OpenAI 相容端點（優先於提供者）
  # api_key: "local-key"                    # base_url 的 API 金鑰（回退到 OPENAI_API_KEY）
  # api_mode: ""                            # base_url 的線路協定："chat_completions"、"codex_responses" 或 "anthropic_messages"。空 = 從 URL 自動偵測（例如 /anthropic 後綴 → anthropic_messages）。對啟發式無法偵測的非標準端點，請明確設定。
  max_concurrent_children: 3                # 每批次的並行子代理數（下限 1，無上限）。也可透過 DELEGATION_MAX_CONCURRENT_CHILDREN 環境變數設定。
  max_spawn_depth: 1                        # 委派樹深度上限（1-3，受限制）。1 = 平坦（預設）：父代產生的葉節點不能委派。2 = 編排器子代可以產生葉節點孫代。3 = 三層。
  orchestrator_enabled: true                # 全域中止開關。設為 false 時，role="orchestrator" 被忽略，每個子代被強制為葉節點，不論 max_spawn_depth 為何。

子代理提供者:模型覆寫： 預設情況下，子代繼承父代代理的提供者和模型。設定 delegation.provider 和 delegation.model 以將子代理路由到不同的提供者:模型對 — 例如，對範圍窄的子任務使用便宜/快速的模型，而你的主要代理運行昂貴的推理模型。

直接端點覆寫： 如果你想要明顯的自訂端點路徑，設定 delegation.base_url、delegation.api_key 和 delegation.model。這會將子代理直接送到該 OpenAI 相容端點並優先於 delegation.provider。如果省略 delegation.api_key，Hermes 僅回退到 OPENAI_API_KEY。

線路協定（api_mode）： Hermes 從 delegation.base_url 自動偵測線路協定（例如路徑以 /anthropic 結尾 → anthropic_messages；Codex / 原生 Anthropic / Kimi-coding 主機名稱保持其現有偵測）。對於啟發式無法分類的端點 — 例如 Azure AI Foundry、MiniMax、Zhipu GLM 或前端為 Anthropic 形狀後端的 LiteLLM 代理 — 請將 delegation.api_mode 明確設為 chat_completions、codex_responses 或 anthropic_messages 之一。留空（預設）以保持自動偵測。

委派提供者使用與 CLI/Gateway 啟動相同的憑證解析。所有已設定的提供者都受支援：openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。設定提供者時，系統會自動解析正確的基礎 URL、API 金鑰和 API 模式 — 無需手動設定憑證。

優先順序： 設定中的 delegation.base_url → 設定中的 delegation.provider → 父代提供者（繼承）。設定中的 delegation.model → 父代模型（繼承）。僅設定 model 而不設定 provider 只更改模型名稱而保留父代的憑證（適用於在同一提供者內切換模型，例如 OpenRouter）。

寬度與深度： max_concurrent_children 限制每批次並行運行的子代理數（預設 3，下限 1，無上限）。也可透過 DELEGATION_MAX_CONCURRENT_CHILDREN 環境變數設定。當模型提交的 tasks 陣列超過上限時，delegate_task 返回工具錯誤解釋限制，而非靜默截斷。max_spawn_depth 控制委派樹深度（限制在 1-3 範圍內）。在預設 1 時，委派是平坦的：子代不能產生孫代，傳遞 role="orchestrator" 會靜默降級為 leaf。提高到 2 讓編排器子代可以產生葉節點孫代；3 用於三層樹。代理透過每次呼叫的 role="orchestrator" 選擇加入編排；orchestrator_enabled: false 強制每個子代回到葉節點，不論其他設定。成本按乘法增長 — 在 max_spawn_depth: 3 和 max_concurrent_children: 3 時，樹可達 3×3×3 = 27 個並行葉代理。詳見 子代理委派 → 深度限制與巢狀編排 了解使用模式。

澄清

設定澄清提示行為：

clarify:
  timeout: 120                 # 等待使用者澄清回應的秒數

上下文檔案（SOUL.md、AGENTS.md）

Hermes 使用兩種不同的上下文範圍：

• SOUL.md 是代理的主要身份。它佔據系統提示中的插槽 #1，完全替換內建的預設身份。編輯它以完全自訂代理是誰。
• 如果 SOUL.md 缺失、空白或無法載入，Hermes 會回退到內建的預設身份。
• 專案上下文檔案使用優先順序系統 — 僅載入一種類型（首次匹配獲勝）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始終獨立載入。
• AGENTS.md 是階層式的：如果子目錄也有 AGENTS.md，會合併所有。
• 如果尚不存在，Hermes 會自動產生預設的 SOUL.md。
• 所有載入的上下文檔案限制在 context_file_max_chars 字元（預設 20,000），具有智慧截斷。

另請參閱：

• 個性與 SOUL.md
• 上下文檔案

工作目錄

覆寫工作目錄：

# 在 ~/.hermes/config.yaml 中：
terminal:
  cwd: /home/myuser/projects

MESSAGING_CWD 和 ~/.hermes/.env 中的直接 TERMINAL_CWD 條目是舊版相容性回退。新的設定應使用 terminal.cwd。

---

---

設定模型