Hermes Agent：實務參考指南（2026）

TL;DR： Hermes Agent是Nous Research推出的開源自我改進AI代理。它以CLI形式執行，同時也是多平台訊息閘道，將持久身份與記憶儲存於磁碟上，匯集能隨使用而進化的技能，並可搭配任何OpenAI相容的LLM供應商運作——Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Alibaba、Hugging Face、Google,或您自行架設的端點皆可。¹² 大多數新使用者最難跨越的關卡是供應商驗證:Hermes支援約19個一級供應商以及自訂端點,並提供三種不同的驗證路徑(在.env中設定API金鑰、透過hermes model進行OAuth驗證,或在config.yaml中設定自訂端點)。驗證模型是首要學習的重點——其他一切都取決於解析出的是哪個供應商。

Hermes Agent是一個完整的代理執行時環境,不只是聊天包裝層。它能讀取您的檔案系統、在沙盒後端執行命令、抓取網頁、派生子代理、執行排程cron任務、從單一閘道程序與Telegram/Discord/Slack/WhatsApp/Signal/Email對話,並從經驗中創造自己的技能。¹ CLI是建構在run_agent.py對話迴圈之上的終端介面;閘道則是一個長時間執行的程序,將訊息從訊息平台路由到同一個對話迴圈。³

休閒使用者與Hermes專家的差距,就在這五個系統。 掌握這些,Hermes就能成為您的力量倍增器:

1. 供應商解析:驗證流程如何對應到API呼叫
2. 設定階層:config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. 工具+toolset系統:代理能做什麼、依平台分別控管
4. skill系統:代理自行建立並演化的程序性記憶
5. gateway + cron + profile:讓Hermes在您日常生活的地方執行,不只在您面前

關鍵要點

• 供應商驗證有三條路徑,不是一條。 在.env中設定API金鑰、透過hermes model/hermes auth進行OAuth驗證,或在config.yaml中設定自訂端點。請選擇符合您供應商的路徑,而非自己熟悉的那一條。
• 切換供應商只需要一個命令。 hermes model會以互動方式引導您完成每個受支援供應商的設定,包括OAuth登入,而/model provider:model可在不遺失歷史紀錄的情況下,於對話中途切換。²
• 使用者可編輯的設定面只有兩個檔案。 ~/.hermes/config.yaml存放設定,~/.hermes/.env存放機密。auth.json、SOUL.md、MEMORY.md和skills/由Hermes直接管理——您可以手動編輯SOUL.md,但其餘都由代理本身維護。⁴
• Hermes是OpenClaw的後繼者。 若要遷移,hermes claw migrate會自動匯入超過30類的狀態。⁵
• 服務品質取決於您的輔助模型。 視覺、網頁摘要、壓縮和記憶刷新都使用另一個輔助LLM。預設是透過自動偵測使用Gemini Flash(OpenRouter → Nous → Codex)——若這幾個都未設定,這些功能會悄悄降級,直到您將輔助槽位指向主要供應商為止。⁴

以下每個章節都以hermes-agent.nousresearch.com/docs的上游文件以及github.com/NousResearch/hermes-agent的原始碼樹為依據。每項事實主張都附有腳註,指向其出處的特定上游頁面。

選擇您的路徑

Hermes 運作方式：心智模型

Hermes 的架構圍繞著一個單一對話迴圈，任何進入點都能調用。這些進入點包括 CLI（cli.py）、訊息 gateway（gateway/run.py）、用於編輯器整合的 ACP 適配器、批次執行器，以及一個 API 伺服器。³ 它們最終都會呼叫 run_agent.py 中的 AIAgent.run_conversation()，其運作如下：

1. 透過 prompt_builder.py 從 SOUL.md、MEMORY.md、USER.md、skills、上下文檔案與工具指引建構系統提示詞³
2. 經由 runtime_provider.py 解析執行時提供者——這一步決定您的驗證方式、基礎 URL 與 API 模式³
3. 使用三種 API 模式之一呼叫提供者：chat_completions、codex_responses 或 anthropic_messages³
4. 將回傳的工具呼叫透過 model_tools.py 與中央工具註冊表（tools/registry.py）進行分派³
5. 持續迴圈直到模型產生最終回應，接著將工作階段持久化至支援 FTS5 的 SQLite³

理解這個迴圈至關重要，因為每項功能——personality、記憶、skills、壓縮、備援——都掛接在其中某個階段。當您閱讀某個設定鍵而想知道它的用途時，答案通常是「它是上述迴圈第 1、2、3 或 4 階段的調節旋鈕」。

跨平台通用核心。 單一 AIAgent 類別同時服務 CLI、gateway、ACP、批次與 API 伺服器。平台差異存在於進入點，而非代理程式本身。³ 這就是為什麼相同的斜線指令在終端機和 Telegram 中都能運作——它們從 hermes_cli/commands.py 中共用的 COMMAND_REGISTRY 進行分派。⁶

目錄結構即是系統。 Hermes 將所有資料儲存於 ~/.hermes/（若使用非預設 profile 則為 $HERMES_HOME）：⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

上述每個檔案都有明確的職責，彼此互不重疊。如果您在找「Hermes 把 X 存在哪裡」，答案就在這些檔案之中。

安裝

單行安裝指令適用於 95% 的使用者。它會處理 Python、uv、Node.js、ripgrep、ffmpeg、儲存庫複製、虛擬環境，以及全域 hermes 指令。⁷

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

支援 Linux、macOS、WSL2 與 Android/Termux（安裝程式會自動偵測 Termux 並切換至經過測試的 Android 套件包）。⁷ 原生 Windows 不受支援——請安裝 WSL2 後在其中執行上述指令。⁷

安裝完成後：

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

唯一的前置需求是 git。安裝程式會透過 uv 自動配置 Python 3.11（無需 sudo）、Node.js v22（用於瀏覽器自動化與 WhatsApp 橋接）、ripgrep 與 ffmpeg。⁷

驗證安裝

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor 會明確告訴您缺少什麼以及如何修復。⁷ hermes dump 則是在 GitHub issue 或 Discord 討論串中尋求協助時應貼上的診斷指令——它會產生一份純文字的完整設定摘要，其中機密資訊已自動遮蔽。⁸

手動安裝

若您需要完全掌控——自訂 Python 版本、特定擴充套件、Nix/NixOS 整合——上游安裝指南中有逐步說明的手動流程。⁷ 以下是可透過 uv pip install -e ".[<extras>]" 組合使用的關鍵選用擴充套件：

Termux 安裝指令有所不同——使用 pip 搭配約束檔案，而非 uv pip：

python -m pip install -e ".[termux]" -c constraints-termux.txt

這是因為在 Android 上使用 .[all] 會透過 voice 擴充套件拉入 faster-whisper，而其依賴的 ctranslate2 輪子並未發布 Android 版本。⁷

驗證與供應商

Hermes 支援約 19 個一級供應商及自訂端點，並提供三種不同的驗證路徑。以下是完整的驗證面，依路徑分類，方便您找到符合手邊資源的方式。

三種驗證路徑

Hermes 中的每個供應商都符合以下三種驗證模式之一：

路徑 1 — .env 中的 API key。 將金鑰放入 ~/.hermes/.env，Hermes 會在啟動時讀取。適用於 OpenRouter、AI Gateway、z.ai/GLM、Kimi/Moonshot、MiniMax（含 MiniMax China）、Alibaba Cloud/DashScope、Kilo Code、OpenCode Zen、OpenCode Go、DeepSeek、Hugging Face、Google/Gemini，以及多數第三方供應商。²

路徑 2 — 透過 hermes model 或 hermes auth 進行 OAuth。 啟動裝置碼流程，開啟瀏覽器，將憑證儲存於 ~/.hermes/auth.json（並可從 Claude Code 或 Codex CLI 等工具匯入既有憑證）。適用於 Nous Portal、OpenAI Codex（ChatGPT 帳號）、GitHub Copilot 與 Anthropic（Claude Pro/Max）。²

路徑 3 — config.yaml 中的自訂端點。 適用於任何 OpenAI 相容的 API — Ollama、vLLM、SGLang、llama.cpp、LM Studio、LiteLLM proxy、Together AI、Groq、Azure OpenAI 或您自架的伺服器。透過 hermes model → Custom endpoint 設定一次後，會持久化至 config.yaml。²

完整供應商矩陣

以下是一級供應商的完整清單，附上各自的精確設定流程。²

Anthropic：三種驗證方式

Anthropic 獨立成節，因為 Hermes 支援三種不同的方式進入 Claude，選對方式很重要。摘自上游文件：²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

當您透過 hermes model 選擇 Anthropic OAuth 時，Hermes 會優先使用 Claude Code 自身的憑證儲存，而非將權杖複製到 ~/.hermes/.env。這能讓可重新整理的 Claude 憑證持續保有重新整理能力。² 如果您已在同一台機器上使用 Claude Code，這是最乾淨的路徑。

要在 config.yaml 中永久綁定 Anthropic：

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude 與 --provider claude-code 也可作為 --provider anthropic 的簡寫。²

GitHub Copilot：兩種模式

Copilot 支援兩種模式：直接 Copilot API（建議使用）與 Copilot ACP（將本機 Copilot CLI 作為子程序啟動）。²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

依上游文件，驗證的檢查順序如下：² 1. COPILOT_GITHUB_TOKEN 環境變數 2. GH_TOKEN 環境變數 3. GITHUB_TOKEN 環境變數 4. gh auth token CLI 後備 5. 透過 hermes model 進行 OAuth 裝置碼登入

權杖類型很重要。 Copilot API 不支援傳統的個人存取權杖（ghp_*）。支援的類型包括 OAuth 權杖（gho_*）、細粒度 PAT（github_pat_*，需具備 Copilot Requests 權限），以及 GitHub App 權杖（ghu_*）。如果 gh auth token 回傳 ghp_* 權杖，請改用 hermes model 透過 OAuth 驗證。²

中國 AI 供應商（一級支援）

Hermes 內建支援 z.ai/GLM、Kimi/Moonshot、MiniMax（全球與中國端點），以及 Alibaba Cloud，並提供專屬的供應商 ID。²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

可透過 GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL 或 DASHSCOPE_BASE_URL 環境變數覆寫基底 URL。²

Z.AI 自動偵測端點。 使用 z.ai/GLM 供應商時，Hermes 會探測多個端點（全球、中國、coding 變體），找到接受您 API 金鑰的端點。可運作的端點會自動快取 — 多數使用者無需設定 GLM_BASE_URL。²

xAI (Grok) 自動啟用提示快取。 當基底 URL 含有 x.ai 時，Hermes 會在每次請求中傳送 x-grok-conv-id 標頭，將請求路由到對話階段中的同一伺服器，重複使用快取的系統提示與歷史。² 自動運作；無需設定。

hermes auth 指令

hermes auth 是用於管理憑證池與 OAuth 憑證的指令。⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

憑證池是您針對同一供應商輪換多個 API 金鑰或 OAuth 權杖的方式 — 在不修改程式碼的情況下，將速率限制分散到多個金鑰上。⁶ 舊版的 hermes login / hermes logout 指令已移除；請改用 hermes auth。⁶

自訂與自架端點

Hermes 可與任何 OpenAI 相容的 API 端點搭配運作。只要伺服器實作 /v1/chat/completions，您就能將 Hermes 指向它。²

互動式設定（建議）：

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

手動設定 config.yaml：

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

兩種方式都會持久化至 config.yaml，這是 main-model、provider 與 base URL 的單一可信來源。² 舊版環境變數 OPENAI_BASE_URL 與 LLM_MODEL 不再用於 main-model 設定 — 請使用 hermes model 或直接編輯 config.yaml。²（OPENAI_BASE_URL 與 OPENAI_API_KEY 仍作為輔助 provider: "main" 路由路徑的後備使用，因此若您在那裡有用到，請勿盲目刪除。）⁴

會話中切換自訂端點：

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom（不指定模型名稱）會查詢您端點的 /v1/models API，若僅載入單一模型則自動選取 — 對執行單一模型的本機伺服器很實用。²

本機 LLM 伺服器（設定範本）

上游文件提供 Ollama、vLLM、SGLang、llama.cpp 與 LM Studio 的完整設定指南。以下是您實際會執行的關鍵指令，每一個都旨在產出 Hermes 可指向的可運作端點。²

Ollama — 最簡單的本機路徑，零設定：

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Ollama 關鍵陷阱： Ollama 的預設上下文長度極低（24GB VRAM 以下為 4,096 tokens）。您必須透過 OLLAMA_CONTEXT_LENGTH 或 Modelfile 提高它 — OpenAI 相容的 API 不接受來自客戶端的上下文長度，因此 Hermes 無法替您設定。² 用於 agent 用途時，至少設為 16k–32k。

vLLM — 高效能 GPU 服務：

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

工具呼叫需要 --enable-auto-tool-choice 與 --tool-call-parser <name>。支援的解析器：hermes（Qwen 2.5、Hermes 2/3）、llama3_json、mistral、deepseek_v3、deepseek_v31、xlam、pythonic。少了這些旗標，工具呼叫會以純文字形式傳回。²

SGLang — 透過 RadixAttention 達成 KV 快取重用的快速服務：

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

SGLang 陷阱： 預設 max_tokens 為 128。若回應被截斷，請在伺服器上設定 --default-max-tokens，或在 config.yaml 中設定 model.max_tokens。²

llama.cpp / llama-server — CPU 與 Apple Silicon Metal：

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja 是工具呼叫的必要參數。 少了它，llama-server 會完全忽略 tools 參數，而模型會嘗試在回應文字中以撰寫 JSON 的方式呼叫工具 — Hermes 無法將其解析為實際的工具呼叫。²

LM Studio — 含 GUI 的桌面應用程式：

從 LM Studio 應用程式啟動伺服器（Developer 標籤 → Start Server），或透過 CLI：lms server start（在 port 1234 啟動）與 lms load qwen2.5-coder --context-length 32768。² 然後將 hermes model 指向 http://localhost:1234/v1。

LM Studio 關鍵陷阱： LM Studio 從模型中繼資料讀取上下文長度，但許多 GGUF 模型回報的預設值為 2048 或 4096。請務必在 LM Studio 模型設定中明確設定上下文長度 — 點擊模型選擇器旁的齒輪圖示，將「Context Length」設為至少 16384（建議 32768），然後重新載入模型。²

具名自訂供應商

如果您需要處理多個自訂端點（例如本機開發伺服器與遠端 GPU 伺服器），可在 config.yaml 中將其定義為具名自訂供應商：²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

接著在會話中以三層語法切換：

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

您也可以從互動式 hermes model 選單中選取具名自訂供應商。²

可插拔供應商架構（v0.13.0+）

v0.13.0 推出了 ProviderProfile ABC 加上 plugins/model-providers/ 目錄，讓第三方推論供應商無需修改核心即可加入。¹⁸ 若供應商支援 OpenAI、Anthropic 或 Codex 相容的 API 模式，您可以實作 ProviderProfile 子類別來宣告驗證路徑、基底 URL、模型目錄與快取標頭；Hermes 會透過內建供應商使用的相同 runtime_provider.py 路徑解析它。這是 v0.13.0 供應商擴充背後的架構轉變：與其修改核心程式碼來新增供應商，您只需出貨一個外掛。

上下文長度偵測

依上游文件，有兩個設定常被混淆：²

• context_length — 整體上下文視窗（輸入 + 輸出 token 預算的總和，例如 Claude Opus 4.7 為 1,000,000，Sonnet 4.6 為 200,000）。Hermes 用此判斷何時壓縮歷史。
• model.max_tokens — 輸出上限（模型在單次回應中可生成的最大 token 數）。與歷史長度無關。

當自動偵測得出的視窗大小錯誤時，請設定 context_length：

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes 使用多來源解析鏈來偵測上下文視窗：設定覆寫 → 自訂供應商每模型設定 → 持久快取 → 端點 /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev（社群維護的 3800+ 模型註冊表）→ 後備預設值（128K）。² 系統具備供應商感知能力，因此同一模型依服務者不同，可能有不同的上下文限制（例如，claude-opus-4.6 在 Anthropic 直連時為 1M，但在 GitHub Copilot 上為 128K）。²

供應商輪換與後備

憑證池。 當您針對同一供應商擁有多組 API 金鑰時，可透過 hermes auth 設定輪換策略。這就是您將速率限制分散至多組金鑰的方式。⁶

後備模型。 設定備援的 provider:model，讓 Hermes 在主要模型失敗時（速率限制、伺服器錯誤、驗證失敗）自動切換：²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

後備機制會在會話中切換 model 與 provider 而不遺失對話。每個會話最多觸發一次。² 後備支援的供應商：openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、alibaba、custom。²

輔助模型

Hermes 為周邊任務使用輕量級「輔助」模型：圖像分析、網頁摘要、瀏覽器螢幕截圖分析、危險指令核可分類、上下文壓縮、會話搜尋摘要、技能比對、MCP 工具派送，以及記憶體 flush。⁴ 預設透過自動偵測（OpenRouter → Nous → Codex）使用 Gemini Flash。

您可以為每個輔助任務設定要使用哪個模型與供應商。 每個輔助插槽都使用相同的三個旋鈕：provider、model、base_url。⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

"main" 供應商選項表示「使用我的主 agent 所使用的供應商」 — 僅在 auxiliary:、compression: 與 fallback_model: 設定中有效。它在頂層 model.provider 設定中無效。如果您將自訂的 OpenAI 相容端點作為主模型，請在 model: 區段中設定 provider: custom。⁴

為什麼這很重要： 若您只設定了 Anthropic OAuth（沒有 OpenRouter 金鑰），則您的 vision、網頁摘要與壓縮會降級或失敗，因為預設的輔助後備鏈會先嘗試 OpenRouter。請為輔助任務新增 OPENROUTER_API_KEY，或重新設定每個輔助插槽以使用您的主供應商：

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

這是新進 Hermes 使用者最常遇到的「為什麼某些功能默默失效」陷阱。

設定系統

Hermes 採用分層的設定系統。理解優先順序至關重要，因為較高層會覆寫較低層的設定，而其中一層是您在 config.yaml 中看不到的全域 provider 註冊表。

設定檔配置

根據官方文件，以下是構成 Hermes 設定的檔案：⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml 與 .env ——當兩者皆設定時，非 secret 設定以 config.yaml 為準。⁴ 規則如下： - Secrets（API keys、bot tokens、密碼）→ .env - 其他所有設定（model、terminal backend、壓縮設定、memory 限制、toolsets）→ config.yaml

Secrets 可在 config.yaml 中透過 shell 風格的字串插值引用：⁴

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

管理設定

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

範例：⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check 與 hermes config migrate 是每次執行 hermes update 之後應該執行的指令——它們會找出您的設定檔尚未包含的新設定選項。⁶

設定優先順序

Hermes 會從多個來源載入設定。當多個來源設定相同的值時，優先順序較高者勝出：⁴

1. CLI arguments —— hermes chat --model anthropic/claude-sonnet-4（單次執行的覆寫）
2. 環境變數 —— 在程序啟動時套用
3. config.yaml —— 主要設定檔
4. .env —— 僅限 secrets
5. 內建預設值 —— 當沒有其他來源設定值時套用

CLI flags 對於單次執行永遠優先。config.yaml 則是長期的真實來源。

在地化（v0.13.0+）

v0.13.0 為 CLI 與 gateway 訊息新增7 種語言：簡體中文、日文、德文、西班牙文、法文、烏克蘭文與土耳其文。¹⁸ 目前文件僅在地化為 zh-Hans。Locale 會從 LC_ALL / LANG 環境變數或 config.yaml 中明確的 locale: 鍵解析。英文仍然是預設語言，也是任何尚未翻譯字串的真實來源。

Profiles —— 多個隔離的 Hermes 實例

Profiles 讓您擁有多個隔離的 Hermes 實例，每個都有自己的設定、sessions、skills、memory 與 gateway PID。這就是您能夠同時並行執行「work Hermes」與「personal Hermes」而互不干擾彼此狀態的方法。⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

每個 profile 都有自己的 HERMES_HOME（預設為 ~/.hermes-<name>/），因此多個 profiles 可以同時執行 gateway 而互不干擾。⁶³

CLI 指令

本節為頂層 CLI 指令的實務參考手冊。如需以原始碼為準的權威參考，請參閱上游的 CLI Commands Reference。⁶

全域選項

hermes [global-options] <command> [subcommand/options]

頂層指令

hermes chat——主要進入點

不帶任何參數直接執行 hermes 即進入互動式對話。hermes chat 是帶選項的明確形式：⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

主要選項：

hermes setup——完整設定精靈

執行完整設定精靈，或直接跳至特定區段：⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs——結構化日誌查詢

hermes logs 比直接對日誌檔案執行 tail -f 更為強大，因為它支援同時依層級、工作階段 ID 及時間範圍進行篩選。⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

日誌檔案存放於 ~/.hermes/logs/：⁶ - agent.log——所有代理活動（API 呼叫、工具調度、工作階段生命週期，INFO 以上） - errors.log——僅包含警告與錯誤（agent.log 的篩選子集） - gateway.log——訊息閘道器活動（平台連線、調度、webhooks）

日誌輪替由 Python 的 RotatingFileHandler 自動處理——留意 agent.log.1、agent.log.2 等檔案。⁶

hermes doctor——診斷工具

hermes doctor [--fix] 是出現問題時應優先執行的指令。它會檢查設定有效性、相依套件是否存在、API 金鑰可用性、服務狀態，並可透過 --fix 嘗試自動修復。⁶

若需與他人分享診斷資訊，請使用 hermes dump——它會產生一份精簡的純文字摘要，其中 API 金鑰已遮蔽處理，可直接貼入 GitHub issue 或 Discord 討論串。⁶

斜線指令

斜線指令在使用中的聊天工作階段（CLI 或訊息平台）中執行。它們由 hermes_cli/commands.py 中共用的 COMMAND_REGISTRY 進行派發，這就是為什麼大多數指令在不同介面上的運作方式完全相同。⁹

工作階段控制

設定與模型

/model 指令是工作階段中切換 provider 的主力：⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

工具、Skills 與資訊

動態 skill 斜線指令

每個已安裝的 skill 都會自動以斜線指令的形式提供：⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

也可以在 config.yaml 中定義快速指令，將短名稱對映到較長的提示詞：⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

然後在 CLI 中輸入 /review、/deploy 或 /morning 即可。

前綴比對

指令支援前綴比對：輸入 /h 會解析為 /help，/mod 會解析為 /model。當前綴具有歧義時，註冊順序中第一個註冊者勝出。完整指令名稱與已註冊的別名永遠優先於前綴比對。⁹

訊息平台專屬指令

部分指令僅在訊息平台上運作（Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant）：⁹

• /status——顯示工作階段資訊
• /sethome（別名 /set-home）——將目前的聊天標記為平台 home
• /approve [session|always]——核准擱置中的危險指令
• /deny——拒絕擱置中的危險指令
• /update——將 Hermes Agent 更新到最新版本
• /commands [page]——瀏覽所有指令與 skill（分頁顯示）

而下列指令僅限 CLI：/skin、/tools、/toolsets、/browser、/config、/cron、/skills、/platforms、/paste、/statusbar、/plugins。⁹

工具與工具集

Hermes 內建廣泛的工具註冊表,涵蓋網路搜尋、瀏覽器自動化、終端執行、檔案編輯、記憶體、委派、RL 訓練、訊息傳遞、Home Assistant 整合等諸多功能。¹⁰ 工具被組織成邏輯化的工具集(toolsets),可依平台啟用或停用。

高階分類

常見的 toolset 名稱包括 web、terminal、file、browser、vision、image_gen、moa、skills、tts、todo、memory、session_search、cronjob、code_execution、delegation、clarify、homeassistant 與 rl。¹⁰

管理工具

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

工具也可在工作階段進行中透過 /tools disable <name> 與 /tools enable <name> 切換,執行後會重設工作階段以套用新的工具組合。⁹

終端後端

terminal 工具可在六種不同環境中執行指令:¹⁰

可透過 hermes config set terminal.backend <name> 切換後端,或在 config.yaml 中設定:

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

SSH 後端(基於安全性建議使用 — 代理無法修改自身程式碼):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Docker 後端:

terminal:
  backend: docker
  docker_image: python:3.11-slim

容器資源(適用於 docker、singularity、modal、daytona):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

啟用 container_persistent: true 後,已安裝的套件、檔案與設定可跨工作階段保留。¹⁰

所有容器後端皆以強化的安全配置執行:唯讀 root 檔案系統(Docker)、捨棄除 DAC_OVERRIDE、CHOWN 與 FOWNER 以外的所有 Linux capabilities、不允許權限提升、PID 限制(256 個程序)、完整的命名空間隔離,並透過 volumes 提供持久化工作區。¹⁰

背景程序

terminal 工具支援背景執行,並提供明確的程序管理:¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

PTY 模式(pty=true)可啟用 Codex 與 Claude Code 等互動式 CLI 工具。¹⁰

Sudo

若指令需要 sudo,Hermes 會提示您輸入密碼(於工作階段中快取)。或在 ~/.hermes/.env 中設定 SUDO_PASSWORD。¹⁰

多代理 Kanban(v0.13.0+)

v0.13.0 將多代理協作提升為一級原語:持久化 Kanban 看板,可跨代理、跨重啟追蹤任務、狀態與工作者身分。¹⁸ 這個看板讓 Hermes 工作者群實際完成工作,而不會卡在死掉的交接上。

Kanban 看板與 /goal(鎖定目標的 Ralph loop)在目標端自然搭配,並與既有的 delegate_task 工具在生成語意上配合無間。最終形成的群協作模式是:每個代理共用一份單一事實來源,清楚指出下一步該做什麼、由誰執行,以及哪裡卡住了。

Skills 系統

Skills 是代理可在需要時載入的隨選知識文件。它們遵循漸進式揭露(progressive disclosure)模式以盡量減少 token 用量,並相容於 agentskills.io 開放標準。¹¹

所有 skills 皆位於 ~/.hermes/skills/ — 此為主要目錄與單一事實來源。全新安裝時,內建 skills 會從 repo 複製過來。透過 hub 安裝及由代理建立的 skills 也都置於此處。¹¹

漸進式揭露

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

代理僅在實際需要時才載入完整的 skill 內容。¹¹

SKILL.md 格式

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## 驗證
如何確認其運作正常。

條件式啟用

Skill 可以根據可用的工具來顯示或隱藏自己。這對於備援 skill 最為實用——僅在進階工具無法使用時才出現的免費或本機替代方案：¹¹

範例:內建的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。當您設定 FIRECRAWL_API_KEY 時,web toolset 即可使用,代理程式便會使用 web_search——DuckDuckGo skill 保持隱藏。若沒有 API 金鑰,DuckDuckGo skill 會自動以備援形式出現。¹¹

代理程式管理的 Skill

代理程式可透過 skill_manage 工具建立、更新及刪除自己的 skill。這是代理程式的程序性記憶——當它找出非顯而易見的工作流程時,會將該方法儲存為 skill 以供未來重複使用。¹¹

代理程式何時建立 skill:¹¹ - 成功完成複雜任務後(5 次以上工具呼叫) - 遇到錯誤或死路後找到可行路徑時 - 使用者修正其方法時 - 發現非顯而易見的工作流程時

動作:¹¹

Skill Hub

從線上登錄處瀏覽、搜尋、安裝及管理 skill:⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

整合的 hub 來源:¹¹

預設 GitHub tap(無需設定即可瀏覽):openai/skills、anthropics/skills、VoltAgent/awesome-agent-skills、garrytan/gstack。¹¹

安全掃描

所有從 hub 安裝的 skill 都會經過安全掃描器,檢查資料外洩、提示注入、破壞性指令、供應鏈訊號及其他威脅。¹¹

信任等級:¹¹

--force 可覆寫 community skill 的非危險政策封鎖。它不會覆寫 dangerous 的掃描判定。¹¹

外部 Skill 目錄

您可以讓 Hermes 指向其他 skill 目錄,與本機目錄一同掃描:¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

路徑支援 ~ 展開及 ${VAR} 環境變數替換。外部目錄為唯讀——當代理程式建立或編輯 skill 時,一律寫入 ~/.hermes/skills/。若兩處都有相同 skill 名稱,以本機優先。¹¹

持久性記憶

Hermes 擁有跨工作階段保留的有界、精選記憶。代理程式的記憶由兩個檔案組成,兩者皆儲存於 ~/.hermes/memories/:¹²

兩者都會在工作階段開始時以凍結快照形式注入系統提示中。代理程式透過 memory 工具管理自己的記憶——add、replace 或 remove。¹²

凍結快照模式:系統提示注入在工作階段開始時擷取一次,且不會在工作階段中途變更。這是刻意的設計——可保留 LLM 的前綴快取以維持效能。工作階段中所做的變更會立即持久化到磁碟,但要到下一個工作階段才會出現在系統提示中。¹²

該儲存什麼

儲存這些(代理程式會主動進行):¹² - 使用者偏好:「我偏好 TypeScript 勝過 JavaScript」→ user - 環境事實:「此伺服器執行 Debian 12 並搭配 PostgreSQL 16」→ memory - 修正:「不要對 Docker 指令使用 sudo,使用者已在 docker 群組中」→ memory - 慣例:「專案使用 tab、120 字元行寬、Google 風格 docstring」→ memory - 已完成的工作:「於 2026 年 1 月 15 日將資料庫從 MySQL 遷移至 PostgreSQL」→ memory

跳過這些:¹² - 瑣碎/顯而易見的資訊 - 容易重新發現的事實 - 原始資料傾印(對記憶而言過大) - 工作階段特有的短暫資訊 - 已存在於上下文檔案中的資訊

工作階段搜尋

除了 MEMORY.md 和 USER.md 之外,代理程式還可透過 session_search 工具搜尋過往對話。所有 CLI 與訊息工作階段都儲存在 SQLite(~/.hermes/state.db)中,並具備 FTS5 全文搜尋功能。查詢會傳回相關的過往對話,並以 Gemini Flash 進行摘要。¹²

外部記憶提供者

對於超越 MEMORY.md 和 USER.md 的更深度持久性記憶,Hermes 隨附八個外部記憶提供者外掛:Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 及 Supermemory。¹²

外部提供者會與內建記憶並行運作(絕不取代),並新增知識圖譜、語意搜尋、自動事實擷取及跨工作階段使用者建模等功能:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

同一時間僅能啟用一個外部提供者。內建記憶永遠處於啟用狀態。⁶

工作階段自動恢復(v0.13.0+)

v0.13.0 讓代理程式中斷後得以延續。gateway 在重啟後會自動恢復中斷的工作階段;/update 重啟可在升級過程中保留工作階段狀態;開發過程中的原始檔重新載入會讓進行中的工作階段保持存活,而非強制建立新的工作階段。¹⁸ 實際效果:長時間執行的 gateway 工作及 cron 驅動的任務,在程序重啟時不再重設其上下文視窗。

Checkpoints v2(v0.13.0+)

狀態持久化在 v0.13.0 中以單一儲存設計重寫,具備真正的修剪、磁碟防護及無孤立陰影儲存庫。¹⁸ 先前的 checkpoint 系統會在長時間執行的 profile 中於磁碟上累積狀態;v2 儲存對本機 checkpoint 儲存空間設定了硬性上限,並移除了導致該成長的重複記錄。無需變更使用者端的設定;下一次 checkpoint 寫入即會使用 v2 路徑。

個性與SOUL.md

SOUL.md是Hermes實例的主要身份。它佔據系統提示中的第1個位置,取代硬編碼的預設身份。¹³

Hermes會在~/.hermes/SOUL.md(或自訂設定檔的$HERMES_HOME/SOUL.md)自動建立預設的SOUL.md。現有的使用者檔案永遠不會被覆寫。Hermes只會從HERMES_HOME載入SOUL.md——不會在當前工作目錄中尋找。這使得個性在不同專案之間保持一致可預測。¹³

SOUL.md應該包含什麼

用於持久的語氣與個性指引:¹³ - 語氣 - 溝通風格 - 直接程度 - 預設互動方式 - 風格上應避免的事項 - Hermes應如何處理不確定性、分歧與模糊狀況

較不適合用於:¹³ - 一次性的專案指示 - 檔案路徑 - 儲存庫慣例 - 暫時性的工作流程細節

這些內容應寫在AGENTS.md中,而非SOUL.md。

SOUL.md與AGENTS.md的差異

這是Hermes身份管理中最重要的區別:¹³

SOUL.md——身份、語氣、風格、溝通預設、個性層級的行為。

AGENTS.md——專案架構、編碼慣例、工具偏好、儲存庫專屬工作流程、命令、連接埠、路徑、部署備註。

一個實用的判斷準則:如果它應該跟著您走到哪都適用,就屬於SOUL.md;如果它屬於某個專案,就屬於AGENTS.md。¹³

內建個性

Hermes內建多種個性,可以透過/personality切換:¹³

自訂個性寫在config.yaml中:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

接著用/personality codereviewer切換。

SOUL.md與/personality的差異

SOUL.md是基準語氣,/personality則是會話層級的覆蓋層。¹³建議保留務實的預設SOUL.md,然後在輔導對話中使用/personality teacher,在腦力激盪時使用/personality creative。

Nous Tool Gateway(v0.10.0+)

從Hermes Agent v0.10.0(2026-04-16)開始,付費的Nous Portal訂閱者可透過現有的Portal憑證,獲得對精選工具集的託管存取權限——無需額外管理API金鑰。²⁰Hermes CLI本身仍維持MIT授權並完全開源。改變的是您的Portal驗證現在不只解鎖模型推論。

Gateway包含哪些工具

運作原理

Gateway是逐工具選擇加入的,透過新的use_gateway設定欄位控制。如果您在hermes auth中有Portal憑證且為某個工具啟用了gateway,該工具的呼叫就會透過Portal路由。否則會使用您直接設定的API金鑰(若有的話)。

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

執行時優先順序:當gateway可用且工具設定use_gateway: true時,即使您同時設定了直接的API金鑰,Hermes仍會優先使用gateway。這對計費很重要——gateway呼叫會從您的Portal訂閱扣款,而非從您直接的API金鑰餘額扣款。

啟用gateway

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

沒有獨立的hermes subscribe或hermes login --portal命令。訂閱狀態會自動從您hermes auth中現有的Portal OAuth憑證偵測。

定價與存取權

定價與方案名稱發布在Nous Portal定價頁面(https://portal.nousresearch.com/pricing)。本指南不列舉方案層級,因為這是Portal產品的責任,而非Hermes CLI的責任,且方案會獨立於Hermes版本變動。請至https://portal.nousresearch.com/註冊,並查看定價頁面取得當前方案資訊。

棄用通知

• HERMES_ENABLE_NOUS_MANAGED_TOOLS環境變數在v0.10.0中已移除。託管工具現在透過逐工具的use_gateway設定欄位啟用,並由您的Portal訂閱狀態控制。²⁰

定位:這個版本不是什麼

Hermes Agent CLI並未被訂閱機制鎖住。專案仍維持MIT授權,所有核心功能(CLI、skills、記憶、訊息gateway、cron、MCP、本地儀表板、針對每個提供者的BYOK)都能完整運作,無需付費給任何人。v0.10.0為已付費訂閱Nous Portal的使用者新增了便捷路徑——它並未從免費路徑中移除任何功能。

訊息Gateway

Hermes可以作為長時間執行的gateway程序運行,在單一gateway程序中連接20個訊息平台:Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin(WeChat)、BlueBubbles(iMessage)、QQBot、Microsoft Teams、Tencent Yuanbao、Google Chat,以及通用的Webhook適配器。^3191718v0.9.0透過BlueBubbles新增iMessage支援(自動webhook註冊、設定精靈、當機韌性),並透過iLink Bot API新增原生WeChat支援,搭配企業應用的WeCom回呼模式。¹⁶v0.11.0新增QQBot。¹⁹v0.12.0新增Microsoft Teams與Tencent Yuanbao。¹⁷v0.13.0新增Google Chat,成為第20個平台,沿用相同的可插拔適配器架構;IRC與Microsoft Teams也已遷移至新的適配器模式,搭配通用的env_enablement_fn / cron_deliver_env_var外掛掛鉤。¹⁸

設定

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

互動式設定會引導您連接每個平台:API權杖、機器人ID、頻道對應、許可清單。⁶

訊息流程

來自上游架構文件:³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

每個訊息平台都透過與CLI相同的AIAgent對話迴圈運行。這就是為什麼斜線命令在兩處運作方式完全相同,也是為什麼在Telegram中排程的cron任務能將輸出傳遞到Discord——平台差異僅存在於邊緣。³

使用者授權與配對

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

配對碼可防止陌生人隨意與您的gateway對話。使用者從訊息平台發送配對碼,您透過hermes pairing approve核准,從此他們就獲得授權。⁶

排程任務(Cron)

Hermes擁有一流的cron系統,任務本身是代理任務,而非shell命令。每個排程任務都會透過全新的AIAgent執行,搭配設定好的提示、選擇性附加的skills,並將結果傳遞至任何平台:³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

或者,在訊息聊天中以對話方式建立:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

代理會透過其工具設定cron任務。任務會持久化儲存於JSON中,並能在重啟後繼續執行。³

MCP 整合

Hermes 同時支援作為 Model Context Protocol 的客戶端與伺服器:⁶

作為客戶端 — 將 Hermes 連接至外部 MCP 伺服器以擴充其工具介面:

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

或於 config.yaml 中手動設定:¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

作為伺服器 — 將 Hermes 對話開放給其他代理使用:

hermes mcp serve
hermes mcp serve -v    # Verbose

上下文壓縮

Hermes 會自動壓縮較長的對話,使其維持在模型上下文視窗的範圍內。壓縮摘要器是獨立的 LLM 呼叫 — 您可將其指向任一供應商或端點。⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

供應商選項:⁴

summary_model 所支援的上下文長度至少須與主模型相當,因為它會接收對話中段的完整內容進行壓縮。⁴

預算壓力警告

當代理執行包含眾多工具呼叫的複雜任務時,可能在不知不覺中耗盡其迭代預算(預設:90 輪)。預算壓力機制會自動向模型發出警告:⁴

串流逾時

LLM 串流連線有兩層逾時設定,並會針對本地供應商(localhost、LAN IP)自動調整:⁴

Socket 讀取逾時對本地端點提高至 30 分鐘,因為本地 LLM 在大型上下文上產生第一個 token 之前,可能需要花費數分鐘進行 prefill。⁴

本地網頁儀表板 (v0.9.0+)

一個瀏覽器介面的儀表板,可在本地端管理您的 Hermes Agent。無須觸碰設定檔或終端機,即可設定組態、監控工作階段、瀏覽 skills,以及管理 gateway。¹⁶ 透過 hermes dashboard 啟動。對於偏好 GUI 的新使用者而言,這是最便捷的入門途徑。

背景程序監控 (v0.9.0+)

watch_patterns 讓您可設定模式以監控背景程序的輸出,並在符合條件時即時收到通知。¹⁶ 不論是監控錯誤、等待特定事件(如「listening on port」),或觀察建置記錄 — 全程無須輪詢。再結合 v0.8.0 的 notify_on_complete(於背景任務完成時發出通知),Hermes 現已具備完整的背景程序可觀測性層。¹⁵

可插拔上下文引擎 (v0.9.0+)

上下文管理現已透過 hermes plugins 成為可插拔的擴充點。您可換用自訂的 context engine,以掌控代理在每一輪所看到的內容 — 包括過濾、摘要,或注入特定領域的上下文。¹⁶ 這項機制將上下文策略與核心代理迴圈解耦,讓上下文得以依專案或領域進行客製化。

備份與還原 (v0.9.0+)

hermes backup 會建立涵蓋設定、工作階段、skills 與記憶體的完整封存檔。hermes import 則可從備份封存檔還原。¹⁶ 此功能可用於跨機器遷移、在重大變更前建立快照,或與隊友分享已驗證可用的設定。

Termux / Android 支援 (v0.9.0+)

Hermes 透過 Termux 在 Android 上原生執行。已調整安裝路徑、針對行動螢幕最佳化 TUI、支援語音後端,且 /image 指令亦可在裝置端運作。¹⁶

安全強化 (v0.13.0+)

v0.13.0 修復了 8 項 P0 安全議題,並對使用者有利地調整了一項預設值。¹⁸

若您維運的是 Hermes 部署,請將 v0.13.0 視為與安全相關的升級,而非單純的功能更新。Discord 跨公會繞過與兩項 TOCTOU 窗口在先前版本中皆可被利用。

給實踐者的架構說明

本節適合想了解底層運作機制的讀者,以便進行除錯、擴充或推理效能。內容整合自上游架構文件。³

進入點 → AIAgent

Hermes 中的每個進入點最終都會呼叫 AIAgent.run_conversation():

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

此圖改編自上游架構文件。³

橫幅中的「47 tools / 20 toolsets」與「28 tools」對比。「47 tools」是上游程式碼倉庫中的工具註冊總數——也就是 Hermes 隨附原始碼的所有工具,涵蓋每一個 toolset。您實際執行的 CLI 在啟動橫幅中會顯示較小的數字(本指南所驗證的安裝環境回報的是 28 tools / 89 skills)。這並非錯誤。許多 toolset 屬於選擇啟用,必須在 config.yaml 的 toolsets: 區段中明確啟用——例如訊息平台轉接器、瀏覽器自動化、較重的爬蟲工具等。註冊總數代表「可用的項目」;橫幅數字則代表「目前 profile 中已啟用的項目」。可使用 hermes tools --list 檢查目前啟用的 toolset,並透過 ~/.hermes/config.yaml 中的 toolsets: 區塊啟用或停用個別 toolset(或在執行中的工作階段內使用 /tools list / /tools enable <name> / /tools disable <name> ——移除某個工具會觸發工作階段重置,讓代理重新建構工具清單)。

三種 API 模式

Hermes 將提供者之間的差異抽象為三種 API 模式,並於執行時自動選擇:³

runtime_provider.py 解析器會將 (provider, model) 元組對應為 (api_mode, api_key, base_url),支援 18 個以上的提供者,並處理 OAuth 流程、憑證池與別名解析。³

CLI 工作階段中的資料流

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

引自上游架構頁面。³

提示組裝順序

提示堆疊包含:¹³

1. SOUL.md(代理身份——若無法取得,則使用內建備援)
2. 工具感知行為指引
3. 記憶/使用者脈絡(MEMORY.md、USER.md)
4. Skills 指引
5. 脈絡檔案(AGENTS.md、.cursorrules)
6. 時間戳記
7. 平台特定的格式化提示
8. 選擇性系統提示覆寫,例如 /personality

SOUL.md 是基石——其他一切都建構於其上。¹³

工作階段儲存

以 SQLite 為基礎的工作階段儲存,搭配 FTS5 全文搜尋。工作階段具備血統追蹤(壓縮過程中的父子關係)、依平台隔離,以及具有競爭處理機制的原子寫入。³

外掛系統

三種發現來源:~/.hermes/plugins/(使用者)、.hermes/plugins/(專案),以及 pip entry points。外掛透過脈絡 API 註冊工具、掛鉤(hooks)與 CLI 命令。記憶提供者屬於特化的外掛類型,位於 plugins/memory/。³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

設計原則

引自上游架構頁面:³

從 OpenClaw 遷移

Hermes Agent 是 OpenClaw 的後繼者。若您正從現有的 OpenClaw 安裝環境進行遷移:⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate 預設會從 ~/.openclaw 讀取(同時自動偵測舊版的 ~/.clawdbot 與 ~/.moldbot 目錄),並寫入 ~/.hermes。⁶

直接匯入(30 個以上類別):SOUL.md、MEMORY.md、USER.md、AGENTS.md、來自 4 個來源目錄的 skills、預設模型、自訂提供者、MCP 伺服器、訊息平台權杖與許可清單(Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost)、代理預設值(推理強度、壓縮、人類延遲、時區、沙箱)、工作階段重置政策、核准規則、TTS 設定、瀏覽器設定、工具設定、exec 逾時、命令許可清單、gateway 設定,以及來自 3 個來源的 API 金鑰。⁶

封存以供手動檢閱:cron 作業、外掛、hooks/webhooks、記憶後端(QMD)、skills 註冊表設定、UI/身份、日誌、多代理設定、頻道繫結、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API 金鑰解析會依優先順序檢查三個來源:設定值 → ~/.openclaw/.env → auth-profiles.json。⁶

疑難排解

「API key not set」

執行 hermes model 以互動方式設定供應商,或執行 hermes config set OPENROUTER_API_KEY your_key。hermes doctor 指令會明確告訴您缺少哪些金鑰。⁷

啟動時出現「Context limit: 2048 tokens」(本地模型)

Hermes 會自動從伺服器的 /v1/models 端點偵測上下文長度,但許多本地伺服器回報的預設值偏低。請在 config.yaml 中明確設定:²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

工具呼叫顯示為文字而非實際執行

您的伺服器未啟用工具呼叫,或該模型透過伺服器實作不支援工具呼叫。²

回應在句子中途被截斷

兩種可能原因:²

1. 輸出上限過低(max_tokens)——SGLang 預設每次回應 128 個 token。請在伺服器設定 --default-max-tokens,或在 config.yaml 中設定 model.max_tokens。
2. 上下文耗盡——模型已填滿其上下文視窗。請增加 model.context_length 或在 Hermes 中啟用上下文壓縮。

從 WSL2 連線至 Windows 主機上的模型伺服器時出現「Connection refused」

WSL2 使用具有自有子網路的虛擬網路介面卡——WSL2 內的 localhost 指的是 Linux 虛擬機,而非 Windows 主機。有兩種解決方式:²

鏡像網路(Windows 11 22H2+):編輯 %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

接著執行 wsl --shutdown 並重新啟動。localhost 即可雙向運作。

主機 IP 備援(較舊版 Windows):從 WSL2 內取得 Windows 主機 IP,改用該 IP 取代 localhost:

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

您也需要讓模型伺服器繫結至 0.0.0.0,而非 127.0.0.1——Ollama 請設定 OLLAMA_HOST=0.0.0.0,llama-server/SGLang 請加上 --host 0.0.0.0,LM Studio 則請啟用「Serve on Network」。²

各項資源在哪裡?

hermes status 與 hermes dump 是您的好幫手。hermes logs list 會列出所有日誌檔案及其大小。hermes config path 會印出設定檔位置。hermes config env-path 則會印出 .env 檔案位置。⁶

常見問題

Hermes Agent 與 Claude Code 有什麼差別?

Claude Code 是 Anthropic 的官方 CLI,僅限使用 Anthropic 模型。Hermes Agent 是 Nous Research 開發的開源代理框架,可搭配任何 OpenAI 相容供應商運作——Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google,或您自行架設的端點皆可。¹² Hermes 還內建 Telegram/Discord/Slack/WhatsApp/Signal 訊息閘道,這是 Claude Code 所沒有的。

我可以用 Anthropic API 金鑰搭配 Hermes 嗎?

可以。有三種方式:²

1. 在 ~/.hermes/.env 中設定 ANTHROPIC_API_KEY,然後執行 hermes chat --provider anthropic --model claude-sonnet-4-6
2. 執行 hermes model 並選擇 Anthropic——可用時 Hermes 會使用 Claude Code 的憑證儲存區
3. 設定手動 ANTHROPIC_TOKEN(setup-token 或 OAuth token)作為備援

如果您已在同一台機器上使用 Claude Code,建議採用選項 2——這樣可保留可重新整理的 Claude 憑證之重新整理能力。

如何在不遺失對話的情況下切換供應商?

在工作階段中使用 /model provider:model。對話歷史、記憶與技能皆會延續:⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

我設定了 Anthropic,但視覺/網頁/壓縮功能無法運作

您遇到的是輔助模型備援問題。視覺、網頁摘要、壓縮等附屬任務使用獨立的輔助 LLM——預設透過自動偵測使用 Gemini Flash(OpenRouter → Nous → Codex)。若以上皆未設定且您僅設定了 Anthropic,這些功能會無聲降級。⁴

修復方式:可選擇加入 OPENROUTER_API_KEY 供輔助任務使用,或重新設定輔助插槽改用主供應商。請注意,上下文壓縮位於獨立的頂層 compression: 區塊,使用 summary_provider,而非 auxiliary.compression.provider——auxiliary.compression 插槽僅暴露 timeout。完整修復如下:

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

SOUL.md 與 AGENTS.md 有什麼差別?

SOUL.md 是您代理的身分——語氣、風格、溝通預設。它位於 ~/.hermes/SOUL.md 並隨您走遍各處。AGENTS.md 則是專案專屬——架構、慣例、指令、路徑——位於您的專案目錄中。¹³ 若該設定應隨您走遍各處,使用 SOUL.md;若屬於某專案,使用 AGENTS.md。

如何同時執行多個 Hermes 實例?

使用 profile。每個 profile 都有自己的 HERMES_HOME、設定、記憶、工作階段與閘道 PID:⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Hermes 支援本地 LLM 嗎?

支援,透過自訂端點路徑。Hermes 可搭配任何 OpenAI 相容伺服器運作:Ollama、vLLM、SGLang、llama.cpp/llama-server、LM Studio、LocalAI、Jan,或您自行架設的伺服器皆可。² 各伺服器的設定方式請參閱 Custom & Self-Hosted Endpoints。

為什麼我的啟動橫幅顯示的工具數量比指南所述的少?

指南引用上游架構註冊表的 47 個工具 / 20 個 toolset——這是 Hermes 在所有 toolset 中所提供原始碼的工具總數。您執行中的安裝會在橫幅中顯示較小的數字(本指南所用的參考安裝回報 28 個工具),因為 Hermes 啟動時只會啟用預設的 toolset 集合。許多 toolset 屬於選用性質:訊息閘道介接器、瀏覽器自動化、較重型的爬蟲堆疊,以及多個專門整合,都必須在 ~/.hermes/config.yaml 的 toolsets: 下明確列出後才會載入。註冊表總數 =「啟用後可使用的工具」。橫幅總數 =「您目前 profile 實際載入的工具」。請使用 hermes tools --list 查看哪些 toolset 處於啟用狀態,以及哪些可用但已停用。可在執行階段以 /tools enable <name> 與 /tools disable <name> 切換個別 toolset(停用會觸發工作階段重置,讓代理以新的形態重建工具清單)。

主供應商失敗時 Hermes 如何處理模型備援?

請在 config.yaml 中設定 fallback_model 區塊:²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

當主供應商失敗(速率限制、伺服器錯誤、驗證失敗)時,Hermes 會在工作階段中途切換至備援,且不會遺失對話歷史。每個工作階段最多觸發一次。

代理可以隨時間自我改進技能嗎?

可以——這正是 Hermes Agent 的「自我改進」之處。代理可透過 skill_manage 工具建立、更新與刪除 skill。當它摸索出非顯而易見的工作流程時,會將該方法儲存為 skill 以供日後重用。¹¹ 代理會在以下情況建立 skill:完成複雜任務後(5 次以上工具呼叫)、遇到錯誤並找到可行路徑時、您糾正其方法時,或它發現非顯而易見的工作流程時。

是否有 IDE 整合?

有——Hermes 可作為 ACP(Agent Client Protocol)伺服器運行,支援 VS Code、Zed 與 JetBrains:⁶

pip install -e '.[acp]'
hermes acp

變更日誌

參考資料