跳到主要內容

配置

所有設置均存儲在 ~/.hermes/ 目錄中，便於訪問。

目錄結構​

~/.hermes/
├── config.yaml     # 配置項（模型、終端、TTS、壓縮等）
├── .env            # API 密鑰與敏感信息
├── auth.json       # OAuth 提供商憑證（Nous Portal 等）
├── SOUL.md         # 主 Agent 身份（系統提示中的第 1 槽位）
├── memories/       # 持久記憶（MEMORY.md、USER.md）
├── skills/         # Agent 創建的技能（由 skill_manage 工具管理）
├── cron/           # 定時任務
├── sessions/       # 網關會話
└── 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 提供商。

終端後端配置​

Hermes 支持六種終端後端。每種後端決定了 Agent 的 shell 命令實際執行的位置 —— 您的本地機器、Docker 容器、通過 SSH 連接的遠程服務器、Modal 雲沙箱、Daytona 工作區，或 Singularity/Apptainer 容器。

terminal:
  backend: local    # 任選：本地 | docker | ssh |莫代爾|代託納 |奇點
  cwd: "."          # 工作目錄（local 用當前目錄，容器默認用 /根目錄）
  timeout: 180      # 每條命令的超時時間（秒）
  env_passthrough: []  # 透傳到沙箱執行環境的環境變量名（terminal + 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直接在您的機器上無開發、個人使用
dockerDocker 容器內完全隔離（命名空間、能力降級）安全沙箱、CI/CD
ssh通過 SSH 連接的遠程服務器網絡邊界遠程開發、高性能硬件
modalModal 雲沙箱完全隔離（雲虛擬機）臨時雲計算、評估
daytonaDaytona 工作區完全隔離（雲容器）受管理的雲開發環境
singularitySingularity/Apptainer 容器內命名空間（--containall）HPC 集群、共享機器

本地後端​

默認後端。命令直接在您的機器上運行，無任何隔離。無需特殊設置。

terminal:
  backend: local
注意

Agent 具有與您的用戶賬戶相同的文件系統訪問權限。請使用 hermes tools 禁用您不希望使用的工具，或切換到 Docker 以實現沙箱隔離。

Docker 後端​

在 Docker 容器中運行命令，並進行安全加固（所有能力被丟棄，無權限提升，PID 限制）。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # 將啟動目錄掛載到 /workspace
  docker_forward_env:              # 透傳進容器的環境變量
    - "GITHUB_TOKEN"
  docker_volumes:                  # 掛載主機目錄
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro 表示只讀

  # 資源限制
  container_cpu: 1                 # CPU 核數（0 = 不限）
  container_memory: 5120           # 內存 / 磁盤大小，單位 MB（0 = 不限）
  container_disk: 51200            # 磁盤大小，單位 MB（需要 overlay2 + XFS+pquota）
  container_persistent: true       # 在會話間持久化 /workspace 和 /root

要求： 已安裝並運行 Docker Desktop 或 Docker Engine。Hermes 會探測 $PATH 以及常見的 macOS 安裝路徑（/usr/local/bin/docker、/opt/homebrew/bin/docker、Docker Desktop 應用包）。

容器生命週期： 每個會話啟動一個長期運行的容器（docker run -d ... sleep 2h）。命令通過 docker exec 以登錄 shell 執行。清理時，容器將被停止並刪除。

安全加固：

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

憑證轉發： docker_forward_env 列出的環境變量首先從您的 shell 環境中解析，然後從 ~/.hermes/.env 中解析。技能也可以聲明 required_environment_variables，這些變量會自動合併。

SSH 後端​

通過 SSH 在遠程服務器上運行命令。使用 ControlMaster 實現連接複用（5 分鐘空閒保活）。默認啟用持久化 shell —— 狀態（當前工作目錄、環境變量）在命令之間保持不變。

terminal:
  backend: ssh
  persistent_shell: true           # 保持一個長期存活的 bash 會話（默認 true）

必需的環境變量：

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

可選：

變量默認值描述
TERMINAL_SSH_PORT22SSH 端口
TERMINAL_SSH_KEY（系統默認）SSH 私鑰路徑
TERMINAL_SSH_PERSISTENTtrue啟用持久化 shell

工作原理： 初始化時以 BatchMode=yes 和 StrictHostKeyChecking=accept-new 連接。持久化 shell 會在遠程主機上保持一個單一的 bash -l 進程運行，通過臨時文件進行通信。需要 stdin_data 或 sudo 的命令會自動回退到一次性模式。

在 Modal 雲沙箱中運行命令。每個任務都會獲得一個可配置 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 — 需要 apptainer 或 singularity 在 $PATH 中。這在 HPC 集群上很常見。

如有疑問，將 terminal.backend 設置回 local，並先確認命令在此模式下能否正常運行。

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/outputs:/outputs"               # Agent 寫入，你來讀取

這適用於：

  • 提供文件給 Agent（數據集、配置文件、參考代碼）
  • 接收文件自 Agent（生成的代碼、報告、導出文件）
  • 共享工作區，你和 Agent 均可訪問相同文件

也可通過環境變量設置：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/.env（如果曾通過 hermes config set 保存過）。

注意

docker_forward_env 中列出的任何內容都會對容器內運行的命令可見。僅轉發你願意暴露給終端會話的憑證。

可選：將啟動目錄掛載到 /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 後端 最為有用，同時也能消除每條命令的連接開銷。持久化 shell 默認為 SSH 啟用，本地後端禁用。

terminal:
  persistent_shell: true   # 默認值——為 SSH 啟用持久化 shell

禁用方法：

hermes config set terminal.persistent_shell false

跨命令保持的內容：

  • 工作目錄（cd /tmp 對下一條命令仍然有效）
  • 導出的環境變量（export FOO=bar）
  • Shell 變量（MY_VAR=hello）

優先級順序：

級別變量默認值
配置terminal.persistent_shelltrue
SSH 覆蓋TERMINAL_SSH_PERSISTENT與配置一致
本地覆蓋TERMINAL_LOCAL_PERSISTENTfalse

按後端設置的環境變量具有最高優先級。若你也希望在本地後端啟用持久化 shell：

export TERMINAL_LOCAL_PERSISTENT=true
備註

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

有關每個後端的詳細信息，請參閱 代碼執行 和 README 中的終端部分。

技能設置​

技能可通過其 SKILL.md 前置元數據聲明自己的配置設置。這些是非敏感值（路徑、偏好、領域設置），存儲在 config.yaml 的 skills.config 命名空間下。

skills:
  config:
    wiki:
      path: ~/wiki          # 供 llm-wiki 技能使用

技能設置的工作方式：

  • hermes config migrate 會掃描所有啟用的技能，查找未配置的設置，並提示你進行配置
  • hermes config show 會顯示所有技能設置，按所屬技能分類列出
  • 當技能加載時，其解析後的配置值會自動注入到技能上下文中

手動設置值：

hermes config set skills.config.wiki.path ~/my-research-wiki

有關在你自己的技能中聲明配置設置的詳細信息，請參閱 創建技能 — 配置設置。

記憶配置​

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # 約 800 tokens
  user_char_limit: 1375     # 約 500 tokens

文件讀取安全​

控制單次 read_file 調用可返回的內容量。超過限制的讀取將被拒絕，並提示 Agent 使用 offset 和 limit 來獲取更小的範圍。這可防止對一個壓縮後的 JS 包或大型數據文件的一次性讀取，導致上下文窗口被淹沒。

file_read_max_chars: 100000  # 默認值——約 25–35K tokens

如果你使用的是具有大上下文窗口的模型，並且頻繁讀取大文件，可以適當提高該值。對於上下文較小的模型，則應降低該值以保持讀取效率：

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

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

Agent 還會自動去重文件讀取 —— 如果同一文件區域被讀取兩次且文件未更改，則返回輕量級佔位符，而非重新發送內容。該機制在上下文壓縮後重置，因此 Agent 可在內容被摘要後重新讀取文件。

Git 工作樹隔離​

為在同一個倉庫上並行運行多個 Agent，啟用隔離的 Git 工作樹：

worktree: true    # 始終創建 worktree（等同於 hermes -w）
# worktree: false # 默認值——僅在傳入 -w 時創建

啟用後，每個 CLI 會話都會在 .worktrees/ 下創建一個全新的工作樹，並擁有自己的分支。Agent 可以編輯文件、提交、推送和創建 PR，互不干擾。退出時會自動清理乾淨的工作樹；髒的工作樹則保留以供手動恢復。

你還可以通過在倉庫根目錄下的 .worktreeinclude 文件列出要複製到工作樹中的被忽略文件：

# .worktreeinclude 示例
.env
.venv/
node_modules/

上下文壓縮​

Hermes 會自動壓縮長時間對話，以保持在模型的上下文窗口限制內。壓縮摘要器是一個獨立的 LLM 調用 —— 你可以將其指向任何提供方或端點。

所有壓縮設置均位於 config.yaml 中（不使用環境變量）。

完整參考​

compression:
  enabled: true                                     # 開啟 / 關閉上下文壓縮
  threshold: 0.50                                   # 達到上下文限制該比例時觸發壓縮
  target_ratio: 0.20                                # 作為最近消息尾部保留的閾值比例
  protect_last_n: 20                                # 至少保留多少條最近消息不壓縮
  summary_model: "google/gemini-3-flash-preview"    # 用於摘要壓縮的模型
  summary_provider: "auto"                          # 提供商：auto、openrouter、nous、codex、main 等
  summary_base_url: null                            # 自定義 OpenAI 兼容端點（優先於 provider）

常見配置​

默認（自動檢測）—— 無需配置：

compression:
  enabled: true
  threshold: 0.50

使用第一個可用的提供方（OpenRouter → Nous → Codex），使用 Gemini Flash。

強制指定特定提供方（基於 OAuth 或 API 密鑰）：

compression:
  summary_provider: nous
  summary_model: gemini-3-flash

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

自定義端點（自託管、Ollama、zai、DeepSeek 等）：

compression:
  summary_model: glm-4.7
  summary_base_url: https://api.z.ai/api/coding/paas/v4

指向一個自定義的 OpenAI 兼容端點。使用 OPENAI_API_KEY 進行認證。

三個配置項的交互方式​

summary_providersummary_base_url結果
auto（默認）未設置自動檢測最佳可用提供方
nous / openrouter / 等未設置強制使用該提供方，使用其認證方式
任意值已設置直接使用自定義端點（提供方被忽略）

summary_model 必須支持至少與主模型相同長度的上下文，因為它需要接收對話的中間完整部分進行壓縮。

上下文引擎​

上下文引擎控制在接近模型標記限制時如何管理對話。內置的 compressor 引擎使用有損摘要（參見 上下文壓縮）。插件引擎可替換它，以採用其他策略。

context:
  engine: "compressor"    # 默認值——內置有損摘要引擎

要使用插件引擎（例如 LCM 實現無損上下文管理）：

context:
  engine: "lcm"          # 必須與插件名稱一致

插件引擎從不自動激活——您必須顯式設置 context.engine 為插件名稱。可通過 hermes plugins → Provider Plugins → Context Engine 瀏覽並選擇可用的引擎。

有關記憶插件的類似單選系統，請參閱 記憶提供者。

迭代預算壓力​

當 Agent 在處理複雜任務並進行大量工具調用時，可能在未察覺的情況下耗盡其迭代預算（默認：90 輪）。預算壓力會在接近限制時自動向模型發出警告：

閾值等級模型所見內容
70%警告[BUDGET: 63/90. 27 次迭代剩餘。開始整合工作。]
90%警告[BUDGET WARNING: 81/90. 僅剩 9 次。立即響應。]

警告會注入到最後一個工具結果的 JSON 中（作為 _budget_warning 字段），而非作為獨立消息——這保留了提示緩存機制，且不會破壞對話結構。

agent:
  max_turns: 90                # 每輪對話允許的最大迭代次數（默認 90）

預算壓力默認啟用。Agent 會自然地將警告視為工具結果的一部分，從而鼓勵其整合工作並在耗盡迭代次數前交付響應。

流式傳輸超時​

LLM 流式連接包含兩層超時機制。對於本地提供者（localhost、局域網 IP）兩者均會自動調整——大多數設置無需配置。

超時默認值本地提供者環境變量
套接字讀取超時120s自動提升至 1800sHERMES_STREAM_READ_TIMEOUT
靜默流檢測180s自動禁用HERMES_STREAM_STALE_TIMEOUT
API 調用（非流式）1800s保持不變HERMES_API_TIMEOUT

套接字讀取超時控制 httpx 等待提供者發送下一塊數據的時間。本地 LLM 在大上下文預填充階段可能需要數分鐘才能生成第一個 token，因此 Hermes 在檢測到本地端點時會將該值提升至 30 分鐘。如果您顯式設置了 HERMES_STREAM_READ_TIMEOUT，則無論端點檢測結果如何，都將始終使用該值。

靜默流檢測會終止接收 SSE 心跳 ping 但無實際內容的連接。此機制對本地提供者完全禁用，因為它們在預填充期間不會發送心跳 ping。

上下文壓力警告​

與迭代預算壓力不同，上下文壓力跟蹤對話距離壓縮閾值的接近程度——即上下文壓縮觸發以總結較早消息的臨界點。這有助於您和 Agent 瞭解對話是否正在變長。

進度等級發生什麼
≥ 60% 至閾值信息CLI 顯示青色進度條；網關發送信息通知
≥ 85% 至閾值警告CLI 顯示粗體黃色條；網關警告壓縮即將發生

在 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    # 均勻輪換各個 key
  anthropic: least_used      # 總是優先選擇使用次數最少的 key

選項：fill_first（默認）、round_robin、least_used、random。完整文檔請參見 Credential Pools。

輔助模型​

Hermes 使用輕量級“輔助”模型執行圖像分析、網頁摘要、瀏覽器截圖分析等輔助任務。默認情況下，這些任務通過自動檢測使用 Gemini Flash——您無需進行任何配置。

通用配置模式​

Hermes 中的每個模型槽位——輔助任務、壓縮、回退——均使用相同的三個控制項：

鍵作用默認值
provider用於認證和路由的提供者"auto"
model請求的模型提供者的默認模型
base_url自定義 OpenAI 兼容端點（覆蓋提供者）未設置

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

可用於輔助任務的提供者：auto、openrouter、nous、codex、copilot、anthropic、main、zai、kimi-coding、minimax，任何註冊在 提供者註冊表 中的提供者，或您 custom_providers 列表中命名的任何自定義提供者（例如 provider: "beans"）。

"main" 僅用於輔助任務

"main" 提供商選項表示“使用我主 Agent 所使用的任何提供者”——它僅在 auxiliary:、compression: 和 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 兼容端點（優先於 provider）
    api_key: ""                # base_url 對應的 API key（未填時回退到 OPENAI_API_KEY）
    timeout: 30                # 單位秒——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                # 單位秒

  # 上下文壓縮超時（獨立於 compression.* 配置）
  compression:
    timeout: 120               # 單位秒——壓縮長對話通常更耗時

  # 會話搜索——總結過去會話的匹配結果
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Skills Hub——技能匹配與搜索
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP 工具調度
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # 記憶刷新——為持久記憶生成對話摘要
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
提示

每個輔助任務都有一個可配置的 timeout（以秒為單位）。默認值：vision 30 秒，web_extract 360 秒，approval 30 秒，compression 120 秒。如果你為輔助任務使用較慢的本地模型，請增加這些值。vision 還有一個獨立的 download_timeout（默認 30 秒），用於 HTTP 圖像下載——對於慢速連接或自託管圖像服務器，請增加此值。

信息

上下文壓縮有其自身的頂層 compression: 塊，包含 summary_provider、summary_model 和 summary_base_url——請參閱上方的 上下文壓縮。回退模型使用 fallback_model: 塊——請參閱 回退模型。這三個配置遵循相同的提供者/模型/基礎 URL 模式。

更改視覺模型​

要使用 GPT-4o 而不是 Gemini Flash 進行圖像分析：

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

或通過環境變量（在 ~/.hermes/.env 中）：

AUXILIARY_VISION_MODEL=openai/gpt-4o

提供商選項​

這些選項適用於 輔助任務配置（auxiliary:、compression:、fallback_model:），而不是你的主 model.provider 設置。

提供商描述要求
"auto"最佳可用選項（默認）。視覺嘗試 OpenRouter → Nous → Codex。—
"openrouter"強制使用 OpenRouter —— 路由到任意模型（Gemini、GPT-4o、Claude 等）。OPENROUTER_API_KEY
"nous"強制使用 Nous Portalhermes auth
"codex"強制使用 Codex OAuth（ChatGPT 賬戶）。支持視覺（gpt-5.3-codex）。hermes model → Codex
"main"使用你當前的自定義/主端點。這可以來自 OPENAI_BASE_URL + OPENAI_API_KEY，或來自 hermes model / config.yaml 保存的自定義端點。支持 OpenAI、本地模型或任何 OpenAI 兼容 API。僅限輔助任務 —— 不適用於 model.provider。自定義端點憑據 + 基礎 URL

常見配置​

使用直接自定義端點（比 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 憑證
    # 模型 默認是 gpt-5.3-codex（支持視覺）

使用本地/自託管模型：

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。

設置環境變量
視覺提供者AUXILIARY_VISION_PROVIDER
視覺模型AUXILIARY_VISION_MODEL
視覺端點AUXILIARY_VISION_BASE_URL
視覺 API 密鑰AUXILIARY_VISION_API_KEY
網頁提取提供者AUXILIARY_WEB_EXTRACT_PROVIDER
網頁提取模型AUXILIARY_WEB_EXTRACT_MODEL
網頁提取端點AUXILIARY_WEB_EXTRACT_BASE_URL
網頁提取 API 密鑰AUXILIARY_WEB_EXTRACT_API_KEY

壓縮和回退模型設置僅支持 config.yaml。

提示

運行 hermes config 以查看當前的輔助模型設置。僅當與默認值不同時，覆蓋項才會顯示。

推理努力​

控制模型在響應前進行“思考”的程度：

agent:
  reasoning_effort: ""   # 留空 = medium（默認）；可選：none、minimal、low、medium、high、xhigh（最高）

未設置時（默認），推理努力默認為“中等”——一個對大多數任務都表現良好的平衡水平。設置一個值將覆蓋默認值——更高的推理努力在複雜任務上可獲得更好結果，但會增加 token 消耗和延遲。

你也可以在運行時通過 /reasoning 命令更改推理努力：

/reasoning           # 顯示當前推理強度與展示狀態
/reasoning high      # 將推理強度設為 high
/reasoning none      # 關閉推理
/reasoning show      # 在每條回覆上方顯示模型思考
/reasoning hide      # 隱藏模型思考

工具使用強制執行​

某些模型（尤其是 GPT 系列）偶爾會將預期操作描述為文本，而不是實際調用工具。工具調用強制機制會注入引導信息，促使模型回到實際調用工具的行為。

agent:
  tool_use_enforcement: "auto"   # 可選："auto" | true | false | ["模型名子串", ...]
值行為
"auto"（默認）對 GPT 模型（gpt-、openai/gpt-）啟用，對其他所有模型禁用。
true對所有模型始終啟用。
false對所有模型始終禁用。
["gpt-", "o1-", "custom-model"]僅對名稱中包含列表中任一子字符串的模型啟用。

啟用後，系統提示中會包含引導信息，提醒模型應實際調用工具，而非僅描述其行為。此機制對用戶透明，且對已能可靠使用工具的模型無影響。

TTS 配置​

tts:
  provider: "edge"              # 可選：edge | elevenlabs | openai | neutts
  edge:
    voice: "en-US-AriaNeural"   # 共 322 個聲音、74 種語言
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # 可選：alloy、echo、fable、onyx、nova、shimmer
    base_url: "https://api.openai.com/v1"  # 用於覆蓋 OpenAI 兼容 TTS 端點
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

此配置同時控制 text_to_speech 工具和語音模式下的語音回覆（CLI 中的 /voice tts 或消息網關）。

顯示設置​

display:
  tool_progress: all      # 可選：off | new | all | verbose
  tool_progress_command: false  # 在消息網關中啟用 /verbose 斜槓命令
  tool_progress_overrides: {}  # 按平臺覆蓋（見下文）
  skin: default           # 內置或自定義 CLI 皮膚（見 user-guide/features/skins）
  personality: "kawaii"  # 舊版外觀字段，部分摘要裡仍會顯示
  compact: false          # 緊湊輸出模式（減少空白）
  resume_display: full    # full（恢復時顯示歷史消息）| minimal（只顯示一行概覽）
  bell_on_complete: false # Agent 完成時播放終端響鈴（適合長任務）
  show_reasoning: false   # 在回覆上方顯示模型推理 / 思考（可用 /reasoning show|hide 切換）
  streaming: false        # 在 token 到達時實時流式輸出到終端
  show_cost: false        # 在 CLI 狀態欄顯示預估美元成本
  tool_preview_length: 0  # 工具調用預覽的最大字符數（0 = 不限，顯示完整路徑 / 命令）
模式你將看到的內容
off靜音 — 僅顯示最終響應
new僅當工具變更時顯示工具指示器
all每次工具調用均顯示簡短預覽（默認）
verbose顯示完整參數、結果和調試日誌

在 CLI 中，使用 /verbose 命令循環切換這些模式。要在消息平臺（Telegram、Discord、Slack 等）中使用 /verbose，請在上述 display 部分設置 tool_progress_command: true。該命令將循環切換模式並保存至配置文件。

各平臺進度顯示覆蓋設置​

不同平臺對詳細程度的需求不同。例如，Signal 不支持編輯消息，因此每次進度更新都會變成一條獨立消息 —— 容易造成噪音。使用 tool_progress_overrides 可為各平臺設置獨立的顯示模式：

display:
  tool_progress: all          # 全局默認值
  tool_progress_overrides:
    signal: 'off'             # 在 Signal 中關閉進度顯示
    telegram: verbose         # 在 Telegram 中顯示詳細進度
    slack: 'off'              # 在共享 Slack 工作區中保持安靜

未設置覆蓋的平臺將回退到全局 tool_progress 值。有效平臺鍵名：telegram、discord、slack、signal、whatsapp、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles。

隱私​

privacy:
  redact_pii: false  # 從 LLM 上下文中剝離 PII（僅網關場景）

當 redact_pii 為 true 時，網關會在支持的平臺上將系統提示中的個人身份信息（PII）進行脫敏處理後再發送給 LLM：

字段處理方式
電話號碼（WhatsApp/Signal 中的用戶 ID）哈希為 user_<12-char-sha256>
用戶 ID哈希為 user_<12-char-sha256>
聊天 ID數字部分哈希，平臺前綴保留（如 telegram:<hash>）
主頻道 ID數字部分哈希
用戶名 / 用戶別名不受影響（由用戶選擇，公開可見）

平臺支持： 脫敏適用於 WhatsApp、Signal 和 Telegram。Discord 和 Slack 被排除，因為其提及系統（<@user_id>）需要在 LLM 上下文中保留真實 ID。

哈希為確定性生成 —— 同一用戶始終映射到同一哈希值，因此模型仍可在群聊中區分不同用戶。路由與交付仍使用原始值在內部處理。

語音轉文本（STT）​

stt:
  provider: "local"            # 可選：local | groq | openai
  local:
    model: "base"              # 可選：tiny、base、small、medium、large-v3
  openai:
    model: "whisper-1"         # 開關：whisper-1 | gpt-4o-mini-轉錄 | gpt-4th-轉錄
  # 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 後自動播放語音回覆
  silence_threshold: 200        # 語音檢測的 RMS 閾值
  silence_duration: 3.0         # 自動停止前允許的靜音秒數

在 CLI 中使用 /voice on 啟用麥克風模式，使用 record_key 開始/停止錄音，使用 /voice tts 切換語音回覆。詳見 語音模式 以獲取端到端設置及各平臺的具體行為說明。

流式傳輸​

在完整響應生成前，逐個令牌地將內容流式傳輸到終端或消息平臺，而非等待全部響應完成。

CLI 流式傳輸​

display:
  streaming: true         # 在終端中實時流式輸出 token
  show_reasoning: true    # 同時流式顯示 reasoning / thinking token（可選）

啟用後，響應將以流式框內逐令牌顯示。工具調用仍會靜默捕獲。若提供方不支持流式傳輸，將自動回退到正常顯示模式。

網關流式傳輸（Telegram、Discord、Slack）​

streaming:
  enabled: true           # 啟用漸進式消息編輯
  transport: edit         # 可選：edit（漸進編輯）或 off
  edit_interval: 0.3      # 兩次消息編輯之間的間隔（秒）
  buffer_threshold: 40    # 累積到多少字符後強制刷新編輯
  cursor: " ▉"            # 流式輸出時顯示的光標

啟用後，機器人在首個令牌到達時發送消息，隨後隨著更多令牌到達逐步編輯該消息。對於不支持消息編輯的平臺（Signal、Email、Home Assistant），將在首次嘗試時自動檢測 —— 該會話中流式傳輸將優雅禁用，避免消息氾濫。

溢出處理： 若流式文本超過平臺的消息長度限制（約 4096 字符），當前消息將被確認並自動開啟新消息。

備註

流式傳輸默認禁用。請在 ~/.hermes/config.yaml 中啟用以體驗流式交互體驗。

群聊會話隔離​

控制共享聊天是按房間保持一個對話，還是按參與者保持獨立對話：

group_sessions_per_user: true  # true = 群組/頻道按用戶隔離；false = 每個聊天共用一個會話
  • true 是默認且推薦的設置。在 Discord 頻道、Telegram 群組、Slack 頻道等共享上下文中，當平臺提供用戶 ID 時，每位發送者都會獲得自己的會話。
  • false 會回退到舊的共享房間行為。這在你明確希望 Hermes 將某個頻道視為單一協作對話時可能有用，但同時也意味著用戶會共享上下文、Token 消耗和中斷狀態。
  • 私信不受影響。Hermes 仍按聊天/私信 ID 鍵控私信，如常操作。
  • 無論設置為何，線程始終與父頻道隔離；當設置為 true 時，線程內的每位參與者也會擁有自己的會話。

有關行為細節和示例，請參閱 會話 和 Discord 指南。

未授權私信行為​

控制 Hermes 在未知用戶發送私信時的行為：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore
  • pair 是默認值。Hermes 拒絕訪問，但在私信中回覆一個一次性配對碼。
  • ignore 會靜默丟棄未授權的私信。
  • 平臺配置項會覆蓋全局默認值，因此你可以在整體保持配對功能開啟的同時，讓某個平臺更安靜。

快速命令​

定義自定義命令，運行 shell 命令而不調用大語言模型 —— 零 Token 消耗，即時執行。特別適用於消息平臺（如 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

使用方法：在 CLI 或任意消息平臺中輸入 /status、/disk、/update 或 /gpu。命令將在主機上本地執行，並直接返回輸出 —— 無需調用 LLM，不消耗任何 Token。

  • 30 秒超時 —— 長運行命令將被終止並返回錯誤消息
  • 優先級 —— 快速命令在技能命令之前檢查，因此你可以覆蓋技能名稱
  • 自動補全 —— 快速命令在分發時解析，不會顯示在內置斜槓命令自動補全表中
  • 類型 —— 僅支持 exec（運行 shell 命令）；其他類型會報錯
  • 全平臺可用 —— CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

人類延遲​

在消息平臺中模擬類人響應節奏：

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

代碼執行​

配置沙箱化的 Python 代碼執行工具：

code_execution:
  timeout: 300                 # 最大執行時長（秒）
  max_tool_calls: 50           # 代碼執行期間允許的最大工具調用次數

網絡搜索後端​

web_search、web_extract 和 web_crawl 工具支持四種後端提供商。可在 config.yaml 中配置後端，或通過 hermes tools 命令設置：

web:
  backend: firecrawl    # 可選：firecrawl | parallel | tavily | exa
後端環境變量搜索提取爬取
Firecrawl（默認）FIRECRAWL_API_KEY✔✔✔
ParallelPARALLEL_API_KEY✔✔—
TavilyTAVILY_API_KEY✔✔✔
ExaEXA_API_KEY✔✔—

後端選擇：如果未設置 web.backend，系統將根據可用的 API 密鑰自動檢測後端。若僅設置了 EXA_API_KEY，則使用 Exa。若僅設置了 TAVILY_API_KEY，則使用 Tavily。若僅設置了 PARALLEL_API_KEY，則使用 Parallel。否則默認使用 Firecrawl。

自託管 Firecrawl：設置 FIRECRAWL_API_URL 指向你自己的實例。當設置了自定義 URL 時，API 密鑰變為可選（在服務器上設置 USE_DB_AUTHENTICATION=false 可禁用認證）。

Parallel 搜索模式：設置 PARALLEL_SEARCH_MODE 以控制搜索行為 —— fast、one-shot 或 agentic（默認：agentic）。

瀏覽器​

配置瀏覽器自動化行為：

browser:
  inactivity_timeout: 120        # 空閒多久後自動關閉會話（秒）
  command_timeout: 30             # 瀏覽器命令超時時間（秒，如截圖、導航等）
  record_sessions: false         # 自動將瀏覽器會話錄製為 WebM 視頻並保存到 ~/.hermes/browser_recordings/
  camofox:
    managed_persistence: false   # 為 true 時，Camofox 會在重啟後保留 cookies / 登錄態

瀏覽器工具集支持多個提供商。有關 Browserbase、Browser Use 和本地 Chrome CDP 設置的詳細信息，請參閱 瀏覽器功能頁面。

時區​

使用 IANA 時區字符串覆蓋服務器本地時區。影響日誌中的時間戳、定時任務調度以及系統提示中的時間注入。

timezone: "America/New_York"   # IANA 時區（默認留空 = 使用服務器本地時區）

支持的值：任意 IANA 時區標識符（例如 America/New_York、Europe/London、Asia/Kolkata、UTC）。留空或省略則使用服務器本地時間。

Discord​

為消息網關配置 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 key 模式
  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 — 自動檢測並屏蔽工具輸出中看起來像 API 密鑰、令牌和密碼的模式，在進入對話上下文和日誌之前進行脫敏處理。
  • tirith_enabled — 當設置為 true 時，終端命令在執行前會通過 Tirith 掃描，以檢測潛在危險操作。
  • tirith_path — Tirith 可執行文件的路徑。如果 Tirith 安裝在非標準位置，請設置此項。
  • tirith_timeout — 等待 Tirith 掃描的最大秒數。若掃描超時，命令仍將繼續執行。
  • tirith_fail_open — 當設置為 true（默認值）時，若 Tirith 不可用或執行失敗，命令仍允許執行。設置為 false 可在 Tirith 無法驗證命令時阻止其執行。

網站黑名單​

阻止 Agent 的網頁和瀏覽器工具訪問特定域名：

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（屏蔽所有子域名）
  • 頂級域名通配符：*.local

共享文件中每行包含一個域名規則（空行和以 # 開頭的註釋會被忽略）。若文件缺失或無法讀取，將記錄警告信息，但不會禁用其他網頁工具。

該策略緩存時間為 30 秒，因此配置更改無需重啟即可快速生效。

智能審批​

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

approvals:
  mode: manual   # 可選：manual | smart | off
模式行為
manual（默認）在執行任何被標記的命令前提示用戶確認。在 CLI 中顯示交互式審批對話框；在消息系統中將審批請求放入待處理隊列。
smart使用輔助 LLM 評估被標記命令是否真正危險。低風險命令將自動批准，並在會話級別持久化。真正高風險命令則升級至用戶確認。
off跳過所有審批檢查。等價於 HERMES_YOLO_MODE=true。請謹慎使用。

智能模式特別適用於減少審批疲勞——它允許 Agent 在安全操作上更自主地運行，同時仍能捕捉真正具有破壞性的命令。

注意

將 approvals.mode: off 設置為關閉狀態將禁用終端命令的所有安全檢查。僅在受信任的沙箱環境中使用。

檢查點​

在破壞性文件操作前自動創建文件系統快照。詳情請參見 檢查點與回滾。

checkpoints:
  enabled: true                  # 啟用自動檢查點（也可用 hermes --checkpoints）
  max_snapshots: 50              # 每個目錄最多保留多少個檢查點

委派​

配置委派工具的子 Agent 行為：

delegation:
  # model: "google/gemini-3-flash-preview"  # 覆蓋 model（留空 = 繼承父 Agent）
  # provider: "openrouter"                  # 覆蓋 provider（留空 = 繼承父 Agent）
  # base_url: "http://localhost:1234/v1"    # 直接指定 OpenAI 兼容端點（優先於 Provider）
  # api_key: "local-key"                    # base_url 對應的 API key（未填時回退到 OPENAI_API_KEY）

子 Agent 提供者:模型覆蓋：默認情況下，子 Agent 繼承父 Agent 的提供者和模型。可通過設置 delegation.provider 和 delegation.model 將子 Agent 路由至不同的提供者:模型組合——例如，對範圍狹窄的子任務使用廉價快速的模型，而主 Agent 則運行成本較高的推理模型。

直接端點覆蓋：若希望使用明確的自定義端點路徑，請設置 delegation.base_url、delegation.api_key 和 delegation.model。這將使子 Agent 直接連接到該 OpenAI 兼容端點，並優先於 delegation.provider。若未設置 delegation.api_key，Hermes 將僅回退使用 OPENAI_API_KEY。

委派提供者使用與 CLI/網關啟動時相同的憑證解析機制。所有已配置的提供者均受支持：openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。設置提供者後，系統會自動解析正確的基礎 URL、API 密鑰和 API 模式——無需手動配置憑證。

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

明確化​

配置明確化提示行為：

clarify:
  timeout: 120                 # 等待用戶補充說明的時長（秒）

上下文文件（SOUL.md, AGENTS.md）​

Hermes 使用兩種不同的上下文作用域：

文件用途作用域
SOUL.md主 Agent 身份 —— 定義 Agent 的身份（系統提示中的第 #1 位置）~/.hermes/SOUL.md 或 $HERMES_HOME/SOUL.md
.hermes.md / HERMES.md項目特定指令（最高優先級）向上遍歷至 Git 倉庫根目錄
AGENTS.md項目特定指令，編碼規範遞歸目錄遍歷
CLAUDE.mdClaude Code 上下文文件（也支持檢測）當前工作目錄
.cursorrulesCursor IDE 規則（也支持檢測）當前工作目錄
.cursor/rules/*.mdcCursor 規則文件（也支持檢測）當前工作目錄
  • SOUL.md 是 Agent 的主要身份標識。它佔據系統提示中的第 #1 位置，完全取代內置的默認身份。通過編輯此文件，可完全自定義 Agent 的身份。
  • 如果缺少 SOUL.md 文件、文件為空或無法加載，Hermes 將回退到內置的默認身份。
  • 項目上下文文件使用優先級系統 —— 僅加載一種類型（首個匹配項勝出）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始終獨立加載。
  • AGENTS.md 具有層級結構：如果子目錄中也包含 AGENTS.md，所有文件將被合併。
  • 如果不存在 SOUL.md，Hermes 會自動創建一個默認的 SOUL.md。
  • 所有加載的上下文文件均限制在 20,000 個字符以內，並採用智能截斷。

另請參閱：

工作目錄​

上下文默認值
CLI（hermes）運行命令時所在的當前目錄
消息網關用戶主目錄 ~（可通過 MESSAGING_CWD 覆蓋）
Docker / Singularity / Modal / SSH容器或遠程機器中的用戶主目錄

覆蓋工作目錄：

# 寫在 ~/.hermes/.env 或 ~/.hermes/config.yaml 中：
MESSAGING_CWD=/home/myuser/projects    # 網關會話
TERMINAL_CWD=/workspace                # 所有終端會話