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

TL;DR：Hermes Agent是Nous Research推出的開源自我改進AI agent。它可以作為CLI執行，也能作為多平台訊息gateway；會在磁碟上儲存持久身分與永久記憶，彙整會隨使用而改進的skills，並可搭配任何OpenAI相容的LLM供應商使用，包括Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Qwen Cloud、Hugging Face、Google、xAI/SuperGrok，或您自行託管的endpoint。¹²¹⁹截至v0.14.0（2026年5月16日），Hermes新增SuperGrok OAuth，具備grok-4.3 1M context；加入可供OAuth供應商使用的OpenAI相容本機proxy（hermes proxy）；正式支援x_search、PyPI安裝、lazy dependency installs、含LINE與SimpleX Chat在內的22個messaging platforms、/handoff、寫入後的LSP語意診斷、統一的video_generate、透過cua-driver為非Anthropic供應商提供computer_use、原生Windows beta，以及12項P0／50項P1收斂。¹⁹多數新使用者最難掌握的是供應商驗證：Hermes支援約20個一級供應商加上自訂endpoints，並有3種不同auth路徑（.env中的API key、透過hermes model使用OAuth，或在config.yaml中設定custom endpoint）。auth模型是最該優先理解的部分，因為後續一切都取決於最終解析到哪個供應商。

Hermes Agent運作方式是完整的agent runtime，不是chat wrapper。它會讀取您的檔案系統、在沙盒後端執行命令、擷取網頁、產生subagents、執行排程cron jobs、透過單一gateway process與Telegram/Discord/Slack/WhatsApp/Signal/Email溝通，並從經驗中建立自己的skills。¹CLI是在run_agent.py中的conversation loop之上打造的terminal UI；gateway則是長時間執行的process，負責將messaging platforms的訊息路由到同一個conversation loop。³

一般使用與專家級Hermes使用的差異，取決於5個系統。掌握這些系統後，Hermes就會成為倍增器：

1. Provider resolution：auth流程如何對應到API呼叫
2. Configuration hierarchy：config.yaml＋.env＋auth.json＋SOUL.md＋AGENTS.md
3. Tool＋toolset system：agent能做什麼，並依平台控管
4. Skills system：agent會建立並持續演進的程序性記憶
5. Gateway＋cron＋profiles：讓Hermes在您實際工作的地方運作，而不只是在您所在的終端機裡

重點摘要

• Provider auth有3條路徑，不是1條。.env中的API key、透過hermes model/hermes auth使用OAuth，或在config.yaml中設定custom endpoint。請選擇符合供應商的路徑，而不是選看起來熟悉的路徑。
• 切換供應商只需要一個命令。hermes model會以互動方式引導您完成每個支援的供應商設定，包括OAuth登入；/model provider:model可在session中途切換，且不會遺失歷史紀錄。²
• 使用者可編輯的設定介面集中在兩個檔案。~/.hermes/config.yaml存放設定，~/.hermes/.env存放secrets。auth.json、SOUL.md、MEMORY.md與skills/由Hermes直接管理；您可以手動編輯SOUL.md，但其餘項目會由agent本身處理。⁴
• Hermes是OpenClaw的後繼者。若正在遷移，hermes claw migrate會自動匯入30多類狀態。⁵
• 服務品質取決於您的auxiliary model。Vision、web summarization、compression與memory flush都會使用獨立的auxiliary LLM。預設會透過自動偵測使用Gemini Flash（OpenRouter→Nous→Codex）；若未設定其中任一項，這些功能會靜默降級，直到您將auxiliary slots指向主要供應商為止。⁴

v0.14變更內容

v0.14.0與其說是單一主打功能，不如說是在擴大Hermes可執行範圍的同時，降低設定阻力。¹⁹主要操作面變更如下：

• 安裝與啟動更輕量。pip install hermes-agent可從PyPI安裝，heavy adapters會在首次使用時lazy-install，啟動路徑也延後足夠多的工作，使cold start約縮短19秒。
• 訂閱可以變成本機API endpoints。hermes proxy會把Claude Pro、ChatGPT Pro、SuperGrok等以OAuth支援的供應商，轉成本機OpenAI相容endpoint，供Codex、Aider、Cline與Continue等工具使用。
• Gateway涵蓋範圍擴大。LINE與SimpleX Chat讓平台數量來到22個；Microsoft Teams已完成端到端串接；Discord history backfill預設啟用；Telegram/Discord的clarify提示現在會使用原生按鈕。
• 寫入時驗證能力提升。編輯後，Hermes可以在下一輪之前顯示每輪的file-mutation摘要與language-server語意診斷，讓它更接近以證據驅動的agent工作方式。
• 桌面與媒體工具範圍擴大。computer_use會透過cua-driver支援非Anthropic供應商；video_generate統一由可插拔後端提供；vision_analyze會將原始pixels傳給真正能看見影像的models。

以下每個章節皆以hermes-agent.nousresearch.com/docs的上游文件，以及github.com/NousResearch/hermes-agent的source tree為依據。每項事實聲明都有footnote指向其來源的特定上游頁面。

選擇您的路徑

Hermes 的運作方式：心智模型

Hermes 的結構圍繞著單一對話迴圈，任何進入點都能呼叫它。這些進入點包括 CLI（cli.py）、訊息 gateway（gateway/run.py）、用於編輯器整合的 ACP adapter、batch runner，以及 API 伺服器。³它們最後都會呼叫 run_agent.py 中的 AIAgent.run_conversation()，其流程如下：

1. 透過 prompt_builder.py，從 SOUL.md、MEMORY.md、USER.md、skills、context 檔案與 tool 指引建立 system prompt³
2. 透過 runtime_provider.py 解析 runtime provider——這一步會選定您的 auth、base URL，以及 API mode³
3. 使用 3 種 API mode 之一呼叫 provider：chat_completions、codex_responses 或 anthropic_messages³
4. 透過 model_tools.py 與中央 tool registry（tools/registry.py）分派任何回傳的 tool calls³
5. 持續迴圈，直到模型產生 final response，接著將 session 持久化到具備 FTS5 的 SQLite³

理解這個迴圈很重要，因為每項功能——personalities、memory、skills、compression、fallback——都附著在其中某個階段。當您讀到某個 config key、想知道它的用途時，答案通常是：「它是上述迴圈第 1、2、3 或 4 階段的一個旋鈕。」

與平台無關的核心。單一 AIAgent class 同時服務 CLI、gateway、ACP、batch 與 API server。平台差異存在於進入點，而不是 agent 本身。³這也是為什麼相同的 slash commands 能同時在 terminal 與 Telegram 中運作——它們都是從 hermes_cli/commands.py 中共用的 COMMAND_REGISTRY 分派。⁶

目錄結構就是系統。Hermes 會把所有內容儲存在 ~/.hermes/ 下（或非預設 profiles 使用的 $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 存在哪裡」，答案就在這些項目之一。

安裝

對多數使用者而言，單行 installer 仍是受引導的安裝路徑。它會處理 Python、uv、Node.js、ripgrep、ffmpeg、repo clone、virtual environment，以及全域 hermes command。⁷v0.14.0 也提供真正的 PyPI package，因此當您已能掌控 Python environment 時，pip install hermes-agent 現在也是可行的直接安裝方式。¹⁹

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

pip install hermes-agent
hermes

可在 Linux、macOS、WSL2 與 Android/Termux 上運作（installer 會自動偵測 Termux，並切換至經測試的 Android bundle）。⁷v0.14.0 透過 PowerShell installer 加入早期 beta 的原生 Windows 支援，但在 Windows 路徑成熟以前，production use 仍建議採用較穩妥的 WSL2。¹⁹

完成後：

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

唯一前置需求是 git。installer 會透過 uv 自動佈建 Python 3.11（不需 sudo）、Node.js v22（用於 browser automation 與 WhatsApp bridge）、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 thread 的 diagnostic command——它會以純文字摘要呈現整個設定，並遮蔽 secrets。⁸

手動安裝

如果需要完整掌控——自訂 Python version、特定 extras、Nix/NixOS integration——upstream installation guide 已逐步記錄手動流程。⁷以下是可搭配 uv pip install -e ".[<extras>]" 使用的主要 optional extras：

Termux install command 不同——它使用帶有 constraints file 的 pip，不是 uv pip：

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

這是因為 Android 上的 .[all] 會透過 voice extra 拉入 faster-whisper，而它依賴的 ctranslate2 wheels 並未針對 Android 發布。⁷

驗證與提供者

Hermes 支援約19個一級提供者，以及自訂端點與3種不同的驗證路徑。以下是完整的驗證介面，依路徑整理，方便您找到符合手上條件的方式。

3種驗證路徑

Hermes 中的每個提供者都符合下列3種驗證模式之一：

路徑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：3種驗證方法

Anthropic 需要獨立說明，因為 Hermes 支援3種進入 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 自己的憑證儲存區，而不是將 token 複製到 ~/.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 裝置碼登入

Token 類型很重要。 Copilot API 不支援傳統 Personal Access Tokens（ghp_*）。支援的類型包括 OAuth tokens（gho_*）、fine-grained PATs（具備 Copilot Requests 權限的 github_pat_*），以及 GitHub App tokens（ghu_*）。如果您的 gh auth token 回傳 ghp_* token，請改用 hermes model 透過 OAuth 驗證。²

中國 AI 提供者（一級支援）

Hermes 內建支援 z.ai/GLM、Kimi/Moonshot、MiniMax（global + China 端點），以及 Alibaba Cloud，並提供專用 provider 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

Base URLs 可透過 GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL 或 DASHSCOPE_BASE_URL 環境變數覆寫。²

Z.AI 會自動偵測端點。 使用 z.ai/GLM 提供者時，Hermes 會探測多個端點（global、China、coding variants），找出接受您 API key 的端點。可用端點會自動快取，多數使用者不需要 GLM_BASE_URL。²

xAI (Grok) 會自動啟用 prompt caching。 當 base URL 包含 x.ai 時，Hermes 會在每個 request 送出 x-grok-conv-id header，將同一個對話 session 路由到同一台伺服器，重用已快取的 system prompts 與 history。² 這是自動行為，無需設定。

hermes auth 指令

hermes auth 是用於 credential pools 與 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

Credential pools 可讓您為同一個提供者輪替多個 API keys 或 OAuth tokens。這對於在不修改程式碼的情況下，將 rate limits 分散到多組 key 很有用。⁶ 舊版 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 的單一真實來源。² 舊版 env vars OPENAI_BASE_URL 與 LLM_MODEL 不再用於 main-model 設定；請使用 hermes model 或直接編輯 config.yaml。²（OPENAI_BASE_URL + OPENAI_API_KEY 仍會作為輔助 provider: "main" 路由路徑的後援而被採用；如果您在該處使用它們，請勿貿然刪除。）⁴

在 session 中途切換自訂端點：

/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，若只載入1個模型就會自動選取；這對執行單一模型的本機伺服器很有用。²

本機 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 預設的 context length 很低（24GB VRAM 以下為 4,096 tokens）。您必須透過 OLLAMA_CONTEXT_LENGTH 或 Modelfile 提高它；OpenAI 相容的 API 不接受由 client 傳入 context length，因此 Hermes 無法替您設定。² 若用於 agent，至少設為 16k–32k。

vLLM — 高效能 GPU serving：

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

Tool calling 需要 --enable-auto-tool-choice 與 --tool-call-parser <name>。支援的 parsers：hermes（Qwen 2.5、Hermes 2/3）、llama3_json、mistral、deepseek_v3、deepseek_v31、xlam、pythonic。沒有這些 flags，tool calls 會以純文字回傳。²

SGLang — 使用 RadixAttention 重用 KV cache 的快速 serving：

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

tool calling 必須使用 --jinja。 沒有它，llama-server 會完全忽略 tools 參數，模型會嘗試在回應文字中寫入 JSON 來呼叫工具，而 Hermes 無法將其解析為真正的 tool calls。²

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

從 LM Studio app 啟動伺服器（Developer tab → 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 會從模型 metadata 讀取 context length，但許多 GGUF 模型回報的預設值是 2048 或 4096。務必在 LM Studio 模型設定中明確設定 context length：點選模型選擇器旁的齒輪圖示，將 “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

接著可在 session 中途用三段式語法切換：

/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/ 目錄，讓第三方 inference providers 可在不修改核心的情況下接入。¹⁸ 如果某個提供者支援 OpenAI、Anthropic 或 Codex 相容的 API 模式，您可以實作一個 ProviderProfile 子類別，宣告 auth path、base URL、model catalog 與 caching headers；Hermes 會透過內建提供者所使用的同一條 runtime_provider.py 路徑解析它。這就是 v0.13.0 provider 擴充背後的架構變更：不必編輯核心程式碼來新增提供者，而是交付一個 plugin。

OpenAI 相容本機 Proxy（v0.14.0+）

hermes proxy 會公開一個 OpenAI 相容的本機端點，背後使用 Hermes 已登入的 OAuth 提供者，例如 Claude Pro、ChatGPT Pro、SuperGrok，或其他相容的已設定提供者。¹⁹ 這表示期待 OpenAI 風格 API 的工具，包括 Codex CLI、Aider、Cline、Continue 或自訂 scripts，都可以重用您的訂閱制 Hermes auth，而不需要另外的 API key。請將此 proxy 視為本機開發者基礎設施：有意識地綁定它，不要廣泛公開，並留意各提供者的特定條款。

Context Length 偵測

依上游文件所述，以下兩個設定經常被混淆：²

• context_length — 總 context window（輸入 + 輸出 token 預算合計，例如 Claude Opus 4.7 的 1,000,000，或 Sonnet 4.6 的 200,000）。Hermes 會用它判斷何時壓縮 history。
• model.max_tokens — 輸出上限（模型在單次回應中可產生的最大 tokens）。與 history 長度無關。

當自動偵測得到錯誤的 window size 時，請設定 context_length：

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

Hermes 使用多來源解析鏈來偵測 context windows：config override → custom provider per-model → persistent cache → endpoint /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev（社群維護、涵蓋 3800+ models 的 registry）→ fallback defaults（128K）。² 這套系統具備 provider awareness，因此同一模型會因服務提供者不同而有不同 context limits（例如 claude-opus-4.6 在 Anthropic direct 上是 1M，但在 GitHub Copilot 上是 128K）。²

Provider Rotation 與 Fallback

Credential pools。 當您有多個同一提供者的 API keys 時，請透過 hermes auth 設定 rotation strategy。這就是將 rate limits 分散到多組 keys 的方式。⁶

Fallback model。 設定備援 provider:model，讓 Hermes 在 primary model 失敗時（rate limits、server errors、auth failures）自動切換過去：²

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

Fallback 會在 session 中途交換 model 與 provider，而不會遺失對話。每個 session 最多觸發一次。² 支援 fallback 的 providers：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 使用輕量級「輔助」模型處理旁支任務：image analysis、web page summarization、browser screenshot analysis、dangerous command approval classification、context compression、session search summarization、skill matching、MCP tool dispatch，以及 memory flush。⁴ 預設會透過自動偵測使用 Gemini Flash（OpenRouter → Nous → Codex）。

您可以設定每個輔助任務使用哪個模型與提供者。 每個 auxiliary slot 都使用相同3個旋鈕：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" provider option 表示「使用我的 main agent 正在使用的任何 provider」，只能用在 auxiliary:、compression: 與 fallback_model: 設定中。它不能用於頂層 model.provider 設定。如果您使用自訂 OpenAI 相容端點作為 main model，請在 model: 區段設定 provider: custom。⁴

這很重要的原因： 如果您只設定了 Anthropic OAuth（沒有 OpenRouter key），vision、web summarization 與 compression 會降級或失敗，因為預設 auxiliary fallback chain 會先嘗試 OpenRouter。請為輔助任務新增 OPENROUTER_API_KEY，或重新設定每個 auxiliary slot 以使用您的 main provider：

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：兩者都設定時，非機密設定以config.yaml為準。⁴規則如下： - 機密（API keys、bot tokens、passwords）→ .env - 其他所有項目（model、terminal backend、compression settings、memory limits、toolsets）→ config.yaml

機密可以透過 shell 風格插值從config.yaml參照：⁴

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 — 僅限機密
5. 內建預設值 — 沒有其他來源設定值時套用

CLI flags一律只在該次呼叫中優先。config.yaml則是長期的真實來源。

在地化（v0.13.0+）

v0.13.0為CLI和 gateway 訊息新增了7種語系：中文（簡體）、日文、德文、西班牙文、法文、烏克蘭文和土耳其文。¹⁸v0.14.0將所有 gateway commands 和 web dashboard 在地化，新增8種語系，總數達16種。¹⁹目前文件僅提供 zh-Hans 在地化版本。Locale會由LC_ALL／LANG環境變數解析，或由config.yaml中的明確locale:鍵指定。英文仍是預設語言，也是任何翻譯尚未涵蓋字串的真實來源。

Profiles — 多個隔離的Hermes執行個體

Profiles讓您擁有多個彼此隔離的Hermes執行個體；每個都有自己的 config、sessions、skills、memory 和 gateway PID。這就是您能並行執行「工作用Hermes」與「個人用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 討論串。⁶

Slash Commands

Slash commands會在作用中的聊天工作階段（CLI或訊息平台）內執行。它們由hermes_cli/commands.py中的共用COMMAND_REGISTRY分派，因此大多數指令在不同介面上的運作方式都相同。⁹

工作階段控制

設定與Model

/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

Tools、Skills與資訊

動態Skill Slash Commands

每個已安裝的skill都會自動公開為slash command：⁹

/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，將短名稱作為較長prompt的別名：⁹

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。當前綴有歧義時，會採用registry順序中的第一個註冊項目。完整指令名稱與已註冊別名一律優先於前綴比對。⁹

訊息平台專用指令

有些指令只適用於訊息平台（Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant）：⁹

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

另有一些指令僅限CLI使用：/skin、/tools、/toolsets、/browser、/config、/cron、/skills、/platforms、/paste、/statusbar、/plugins。⁹

Tools與Toolsets

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。¹⁰

管理Tools

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

也可以在session中途透過/tools disable <name>和/tools enable <name>切換工具；這會重設session，讓新的工具集合生效。⁹

終端機後端

終端機工具可在6種不同環境中執行命令：¹⁰

使用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後端（基於安全性建議使用——agent無法修改自己的程式碼）：¹⁰

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後，已安裝的套件、檔案與設定會跨session保留。¹⁰

所有容器後端都會套用安全強化：唯讀根檔案系統（Docker）、移除所有Linux capabilities，僅保留DAC_OVERRIDE、CHOWN和FOWNER、禁止權限提升、PID限制（256個程序）、完整namespace隔離，以及透過volumes提供持久工作區。¹⁰

背景程序

終端機工具支援背景執行，並提供明確的程序管理：¹⁰

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會提示輸入密碼（在該session中快取）。也可以在~/.hermes/.env中設定SUDO_PASSWORD。¹⁰

Multi-Agent Kanban（v0.13.0+）

v0.13.0將multi-agent協作變成一等原語：一個耐久Kanban看板，可跨agents與重啟追蹤任務、狀態與worker身分。¹⁸這個看板讓一群Hermes workers能真正完成工作，而不是卡在失效的交接上。

Kanban看板自然可與目標端的/goal（鎖定目標的Ralph loop）搭配，也可與既有的delegate_task工具搭配處理spawn語意。結果會形成一種swarm模式：每個agent共享同一個事實來源，清楚知道接下來要做什麼、誰正在執行，以及哪些項目卡住。

Skill 系統

skill 是 agent 可在需要時載入的隨需知識文件。它們採用漸進揭露模式，以盡量降低 token 用量，並相容於 agentskills.io 開放標準。¹¹

所有 skill 都位於 ~/.hermes/skills/——這是主要目錄，也是唯一真實來源。全新安裝時，隨附的 skill 會從 repo 複製過來。透過 Hub 安裝與 agent 建立的 skill 也會放在這裡。¹¹

漸進揭露

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)

agent 只有在實際需要時，才會載入完整的 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

## Verification
How to confirm it worked.

條件式啟用

skill 可以依據可用工具自行顯示或隱藏。這對備援 skill 最有用，也就是只有在付費工具不可用時才應出現的免費或本機替代方案：¹¹

範例：內建的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。當您設定了 FIRECRAWL_API_KEY，web toolset 可用，agent 會使用 web_search——DuckDuckGo skill 會維持隱藏。沒有 API 金鑰時，DuckDuckGo skill 會自動以備援形式出現。¹¹

Agent 管理的 Skill

agent 可以透過 skill_manage 工具建立、更新及刪除自己的 skill。這是 agent 的程序式記憶——當它找出非顯而易見的工作流程時，會將方法儲存成 skill，以便日後重複使用。¹¹

agent 建立 skill 的時機：¹¹ - 成功完成複雜任務後（5 次以上工具呼叫） - 遇到錯誤或走入死路，並找到可行路徑時 - 使用者修正其方法時 - 發現非顯而易見的工作流程時

動作：¹¹

Skill Hub

從線上 registry 瀏覽、搜尋、安裝及管理 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 taps（無須設定即可瀏覽）：openai/skills、anthropics/skills、VoltAgent/awesome-agent-skills、garrytan/gstack。¹¹

安全掃描

所有透過 hub 安裝的 skill 都會經過安全掃描器檢查，涵蓋資料外洩、prompt injection、破壞性命令、供應鏈訊號及其他威脅。¹¹

信任等級：¹¹

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

外部 Skill 目錄

您可以讓 Hermes 指向其他 skill 目錄，並與本機目錄一併掃描：¹¹

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

路徑支援 ~ 展開與 ${VAR} 環境變數替換。外部目錄是唯讀——當 agent 建立或編輯 skill 時，一律寫入 ~/.hermes/skills/。如果兩處都有同名 skill，會以本機優先。¹¹

持久記憶

Hermes具備有界且經過整理的記憶，可跨session持續存在。Agent的記憶由2個檔案組成，兩者都儲存在~/.hermes/memories/：¹²

兩者都會在session開始時，以凍結快照形式注入system prompt。Agent會透過memory工具管理自己的記憶——add、replace或remove。¹²

凍結快照模式：system prompt注入只會在session開始時擷取一次，session期間不會變更。這是刻意設計——可保留LLM的前綴快取以提升效能。session期間所做的變更會立即持久化到磁碟，但直到下一個session才會出現在system prompt中。¹²

要儲存哪些內容

儲存這些內容（agent會主動執行）：¹² - 使用者偏好：「我偏好TypeScript，而不是JavaScript」→user - 環境事實：「這台伺服器執行Debian 12與PostgreSQL 16」→memory - 修正事項：「執行Docker指令時不要使用sudo，使用者在docker群組中」→memory - 慣例：「專案使用tab、120字元行寬、Google風格docstrings」→memory - 已完成工作：「已於2026年1月15日將資料庫從MySQL遷移至PostgreSQL」→memory

略過這些內容：¹² - 瑣碎或顯而易見的資訊 - 容易重新發現的事實 - 原始資料傾印（對記憶而言太大） - session限定的短暫資訊 - 已在context檔案中的資訊

Session Search

除了MEMORY.md與USER.md之外，agent也可以使用session_search工具搜尋過去的對話。所有CLI與messaging sessions都會儲存在SQLite（~/.hermes/state.db）中，並提供FTS5全文搜尋。查詢會透過Gemini Flash摘要，回傳相關的過往對話。¹²

外部記憶提供者

若需要比MEMORY.md與USER.md更深入的持久記憶，Hermes內建8個外部記憶provider外掛：Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover與Supermemory。¹²

外部providers會與內建記憶並行運作（不會取代它），並加入知識圖譜、語意搜尋、自動事實擷取，以及跨session使用者建模等能力：⁶¹²

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)

同一時間只能啟用1個外部provider。內建記憶永遠啟用。⁶

Session自動續接（v0.13.0+）

v0.13.0讓agent執行途中遭中斷時也能恢復。gateway會在重新啟動後自動續接中斷的sessions；/update重新啟動會在升級期間保留session狀態；開發期間重新載入原始檔時，也會維持作用中的session，而不是強制建立新的session。¹⁸實際效果是：長時間執行的gateway工作與cron驅動的jobs，在程序重新啟動時不再重設其context window。

Checkpoints v2（v0.13.0+）

v0.13.0將狀態持久化重寫為單一儲存設計，具備真正的修剪、磁碟防護欄，且不再產生孤立的shadow repos。¹⁸先前的checkpoint系統會在長時間執行的profiles中於磁碟累積狀態；v2 store為本機checkpoint儲存設定硬性上限，並移除造成成長的重複簿記。不需要變更任何使用者可見的config；下一次checkpoint寫入會使用v2路徑。

個性與SOUL.md

SOUL.md是Hermes instance的主要身分。它佔據system prompt中的第1個位置，取代硬編碼的預設身分。¹³

Hermes會自動在~/.hermes/SOUL.md（或自訂profiles的$HERMES_HOME/SOUL.md）建立預設SOUL.md。既有使用者檔案永遠不會被覆寫。Hermes只會從HERMES_HOME載入SOUL.md——不會查看目前工作目錄。這讓personality在不同專案之間保持可預期。¹³

SOUL.md適合放什麼

用於長期穩定的語氣與personality指引：¹³ - 語氣 - 溝通風格 - 直接程度 - 預設互動風格 - 風格上應避免的事項 - Hermes應如何處理不確定性、分歧與模糊性

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

這些應該放在AGENTS.md，而不是SOUL.md。

SOUL.md與AGENTS.md

這是Hermes身分管理中最重要的區別：¹³

SOUL.md——身分、語氣、風格、溝通預設值、personality層級的行為。

AGENTS.md——專案架構、程式碼慣例、工具偏好、repo特定工作流程、指令、ports、路徑、部署備註。

一個實用規則是：如果它應該跟著您到任何地方，就屬於SOUL.md。如果它屬於某個專案，就屬於AGENTS.md。¹³

內建Personalities

Hermes內建多種personalities，可用/personality切換：¹³

config.yaml中的自訂personalities：¹³

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是session層級的覆蓋。¹³建議保留務實的預設SOUL.md，再針對教學對話使用/personality teacher，或在腦力激盪時使用/personality creative。

Nous Tool Gateway（v0.10.0+）

自Hermes Agent v0.10.0（2026年4月16日）起，付費Nous Portal訂閱者可透過既有Portal憑證，取得一組經整理的受管工具存取權——不需要管理額外的API金鑰。²¹Hermes CLI本身仍採MIT授權，並且完全open source。改變之處在於，您的Portal auth現在解鎖的不只是model inference。

gateway包含什麼

運作方式

gateway透過新的use_gateway config欄位，針對每個工具選擇性啟用。如果您在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

Runtime優先順序：當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憑證自動偵測。

定價與存取

定價與tier名稱發布於Nous Portal定價頁（https://portal.nousresearch.com/pricing）。本指南不列舉tiers，因為它們由Portal產品負責，不由Hermes CLI負責，且會獨立於Hermes releases變更。請到https://portal.nousresearch.com/註冊，並查看定價頁取得目前tiers。

棄用通知

• HERMES_ENABLE_NOUS_MANAGED_TOOLS env var已在v0.10.0中移除。受管工具現在透過各工具的use_gateway config欄位啟用，並依您的Portal訂閱狀態進行gate。²¹

定位：這個release不是什麼

Hermes Agent CLI不需要訂閱才能使用。此專案仍採MIT授權，所有核心功能（CLI、skills、memory、messaging gateway、cron、MCP、local dashboard、每個provider的BYOK）都能在不付費給任何人的情況下端到端運作。v0.10.0為已經付費使用Nous Portal的使用者新增一條便利路徑——並未從免費路徑移除任何內容。

Messaging Gateway

Hermes可以作為長時間執行的gateway程序，從單一gateway程序連接到22個訊息平台：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、LINE、SimpleX Chat，以及通用Webhook介面卡。^320171819 v0.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外掛hook。¹⁸ v0.14.0加入LINE與SimpleX Chat，並以Graph auth、webhook listener、pipeline runtime與outbound delivery，完成Microsoft Teams堆疊的端到端支援。¹⁹

設定

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 tokens、bot IDs、channel mappings、allowlists。⁶

訊息如何流動

來自上游架構文件：³

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對話迴圈。這就是為什麼slash commands在兩處都以相同方式運作，也解釋了為什麼在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系統，其中工作是agent tasks，而不是shell commands。每個排程工作都會透過全新的AIAgent執行，使用已設定的prompt、選用的附加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.

agent會透過自身工具設定cron工作。工作會持久化在JSON中，並在重新啟動後保留。³

MCP整合

Hermes支援Model Context Protocol，可同時作為client與server：⁶

作為client：將Hermes連接到外部MCP servers，以擴充其工具介面：

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"

作為server：將Hermes對話公開給其他agents：

hermes mcp serve
hermes mcp serve -v    # Verbose

Context Compression

Hermes會自動壓縮長對話，使其維持在模型的context window內。壓縮summarizer是獨立的LLM call，您可以將它指向任何provider或endpoint。⁴

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

Provider選項：⁴

summary_model必須支援至少與主模型一樣大的context length，因為它會接收對話完整的中段內容來進行壓縮。⁴

預算壓力警告

當agent處理包含大量tool calls的複雜工作時，可能在未察覺的情況下耗盡iteration budget（預設：90 turns）。預算壓力會自動警告模型：⁴

串流逾時

LLM streaming connection有兩層逾時機制，會針對本機providers（localhost、LAN IPs）自動調整：⁴

本機endpoints的socket讀取逾時會提高到30分鐘，因為本機LLMs在大型contexts上進行prefill時，可能需要數分鐘才會產生第一個token。⁴

本機Web Dashboard（v0.9.0+）

這是一個以瀏覽器為基礎的dashboard，可在本機管理您的Hermes Agent。設定選項、監控sessions、瀏覽skills，並在不碰觸config檔案或terminal的情況下管理gateway。¹⁶ 使用hermes dashboard啟動。對偏好GUI的新使用者而言，這是最容易上手的onboarding路徑。

背景程序監控（v0.9.0+）

watch_patterns讓您設定要在背景程序輸出中監控的patterns，並在符合時即時收到通知。¹⁶ 可監控錯誤、等待特定事件（「listening on port」），或觀察build logs，全程不需要polling。結合v0.8.0的notify_on_complete（會在背景工作完成時通知），Hermes現在具備完整的背景程序可觀測性層。¹⁵

可插拔Context Engine（v0.9.0+）

context管理現在透過hermes plugins成為可插拔slot。可換入自訂context engines，控制agent每一輪看到的內容，包括篩選、摘要，或注入特定領域context。¹⁶ 這會將context策略從核心agent loop中解耦，允許依專案或領域自訂context。

備份與還原（v0.9.0+）

hermes backup會建立包含config、sessions、skills與memory的完整封存檔。hermes import則可從備份封存檔還原。¹⁶ 可用於在機器之間遷移、在重大變更前建立snapshot，或與團隊成員分享已知良好的設定。

Termux／Android支援（v0.9.0+）

Hermes可透過Termux在Android上原生執行。經過調整的安裝路徑、針對行動裝置螢幕最佳化的TUI、voice backend支援，以及/image command都可在裝置端運作。¹⁶

安全強化（v0.13.0+）

v0.13.0修復了8個P0安全問題，並將一項預設值改成更有利於使用者的設定。¹⁸ v0.14.0接續修復另外12個P0與50個P1問題，包括sudo暴力破解／sudo-stdin強化、危險命令繞過修正、工具錯誤重新注入模型前的清理、dashboard plugin API驗證、skills-hub SSRF涵蓋範圍，以及安裝期間的供應鏈公告掃描。¹⁹

如果您維護Hermes部署，請將v0.13.0與v0.14.0視為與安全相關的升級，而不只是功能發布。v0.13.0修復了Discord跨guild繞過與兩個TOCTOU視窗；v0.14.0則在sudo處理、工具錯誤重新注入、plugin API、skills-hub SSRF與相依套件公告方面再做一輪強化。

給實務使用者的架構說明

本節適合想了解底層運作的人員，方便除錯、擴充，或推敲效能表現。內容綜合自上游架構文件。³

進入點→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>；移除工具會觸發工作階段重設，讓agent重建工具清單）。

三種API模式

Hermes會將供應商差異抽象成三種API模式，並在執行階段自動選擇：³

runtime_provider.py解析器會將(provider, model)tuple對應到(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（agent身分；若無法使用，則採用內建備援）
2. 具工具感知能力的行為指引
3. 記憶／使用者脈絡（MEMORY.md、USER.md）
4. Skills指引
5. 脈絡檔案（AGENTS.md、.cursorrules）
6. 時間戳記
7. 平台特定格式提示
8. 選用系統提示覆蓋，例如/personality

SOUL.md是基礎，其他所有內容都建立在它之上。¹³

工作階段儲存

以SQLite為基礎的工作階段儲存，搭配FTS5全文搜尋。工作階段具備譜系追蹤（壓縮前後的父／子關係）、各平台隔離，以及具競用處理的原子寫入。³

Plugin System

三個探索來源：~/.hermes/plugins/（使用者）、.hermes/plugins/（專案）與pip進入點。Plugin會透過脈絡API註冊工具、hook與CLI命令。Memory provider是plugins/memory/下的專用plugin類型。³

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伺服器、訊息平台token與允許清單（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent預設值（reasoning effort、compression、human delay、timezone、sandbox）、工作階段重設政策、approval rules、TTS config、瀏覽器設定、工具設定、exec timeout、command allowlist、gateway config，以及來自3個來源的API keys。⁶

封存供人工審查： cron jobs、plugins、hooks/webhooks、memory backend（QMD）、skills registry config、UI/identity、logging、multi-agent setup、channel bindings、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API key解析會依優先順序檢查3個來源：config values→~/.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

變更記錄

參考資料