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如何運作：Mental Model

Hermes圍繞單一對話迴圈建構，任何進入點都能呼叫。進入點包括CLI（cli.py）、messaging 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 files和工具指引建立system prompt³
2. 透過runtime_provider.py解析runtime provider——這一步會選定您的auth、base URL和API模式³
3. 使用3種API模式之一呼叫provider：chat_completions、codex_responses或anthropic_messages³
4. 透過model_tools.py和中央tool registry（tools/registry.py）派發任何回傳的tool calls³
5. 持續迴圈，直到模型產生最終回應，接著將session持久化到帶有FTS5的SQLite³

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

平台無關核心。單一AIAgent類別服務CLI、gateway、ACP、batch和API伺服器。平台差異存在於進入點，而非agent本身。³這就是為什麼相同的slash commands能在終端機和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存在哪裡」，答案就在其中之一。

v0.18.0的新功能（The Judgment Release）

Hermes Agent v0.18.0（tag v2026.7.1，2026年7月1日）以judgment命名：agent會驗證自己的工作，而不是宣稱成功；同時提供您實際可檢視的ensemble reasoning。此版本也關閉了整個P0/P1 backlog——約692個最高優先級項目在12天內解決。²²

• Mixture-of-Agents成為一級模型。MoA現在可像任何其他模型一樣，在所有介面中選用；ensemble reasoning也變得可見：每個reference model的完整輸出都會以獨立標記區塊呈現，並即時串流答案——您可以觀看ensemble思考，而不是得到不透明的合併答案。²²
• /goal的completion contracts。agent會先執行專案檢查，驗證自己的工作，再回報goal完成，而不是直接宣稱成功——把judgment用在自己身上。²²
• /learn——把任何描述轉成skill。只要描述workflow，就能將其轉成可重複使用的skill；產生的skills會自動符合repo的CONTRIBUTING.md慣例。²²
• /journey時間軸。以視覺方式呈現memory和skills隨時間變化的歷史，支援編輯，桌面版另有memory graph。²²
• Background subagent fan-out。可委派多個並行執行的任務，且不會阻塞對話——v0.17.0的單一background subagent擴展為一整個fleet。²²
• Desktop Projects。提供一級coding Projects，採用project/repo/lane的組織模型。²²
• Scale-to-zero gateway。Gateways可在閒置時休眠，並協調drains以達成無縫部署——對任何把Hermes當作常駐服務運行的人都很有意義。²²
• Google Vertex AI支援。透過GCP service accounts存取Gemini，並自動重新整理OAuth2 token，加入provider catalog。²²
• /prompt editor command。開啟$EDITOR來撰寫多行prompts，不必再和輸入列苦戰。²²

如果您正從v0.17.x升級，這裡沒有任何會破壞CLI的變更。升級的主要理由是completion contracts（會自我驗證的goals）、具備可檢視ensembles的一級MoA，以及用於skill capture的/learn。

v0.17.0的新功能（The Reach Release）

Hermes Agent v0.17.0（tag v2026.6.19，2026年6月19日）以agent如今能觸及的範圍命名——新的messaging channels、新的model providers，以及更深入的desktop和dashboard控制。它是在v0.16.x之上的增量更新；CLI介面維持不變。²¹

• 新的messaging channels。iMessage現在透過Photon Spectrum即可運作，不需要Mac relay（device-code OAuth、hermes photon login）；WhatsApp Business Cloud API是官方Meta adapter，取代bridge-process需求；SimpleX新增groups、native attachments、text batching和auto-accept；Raft則作為內建platform plugin加入，採用privacy-by-contract wake-channel設計。²¹
• 新的models和providers。catalog新增z-ai/glm-5.2（1M context）、anthropic/claude-fable-5、laguna-m.1、nemotron-3-ultra和grok-composer-2.5-fast（透過xAI OAuth使用Cursor的model，200k context）。xAI預設值移至grok-build-0.1，且Anthropic adaptive models現在遵循現代thinking contract（它們永遠不會傳送reasoning欄位）。²¹
• Desktop和dashboard。Desktop新增background subagents，可透過即時「watch-windows」串流委派活動（delegate_task(background=true)）、Composer model selector、可重新綁定的keyboard shortcuts、原生OS notifications、per-thread composer drafts、VS Code Marketplace themes，以及日文＋繁體中文UI。dashboard新增完整profile builder（不用編輯config.yaml即可設定model/skills/MCPs）、global profile switcher、重做的Skills Hub並包含security scan、Automation Blueprints（橫跨form、slash command、conversation和docs的參數化templates），以及在OAuth gate後方會回傳401的secure login。²¹
• Skills和tools。image_generate現在不只可從零建立影像，也能在每個受支援的image provider中編輯和轉換來源影像；memory工具新增operations陣列，可在單一呼叫中進行atomic batch add/replace/remove；新的simplify-code skill會執行parallel three-agent review-and-cleanup pass，並以Chesterton’s-Fence risk tier把關；boolean write_approval取代tri-state write_mode。²¹
• Architecture。Background subagents會立即回傳handle，並將其結果作為新turn重新進入；MCP elicitation handler允許mid-tool-call confirmation，而延後連線的MCP tools會在turns之間公開（cache-safe）；cron成為可插拔CronScheduler，並提供Chronos managed-cron provider；新的Managed scope（/etc/hermes）讓管理員可以釘選使用者不可變更的config，並搭配Gateway-Gateway relay支援multi-gateway topologies。²¹
• 新commands。/version、/billing（interactive terminal billing）、hermes photon login（iMessage auth）和hermes curator run --consolidate——consolidation現在為opt-in，因此例行background curation不會消耗token。²¹
• Security。v0.17.0修補shell-escape denylist bypass；在缺少approval modules和own-policy gateway adapters時採fail closed；為cron job-script subprocesses清理environment；在request debug dumps中遮蔽secrets；篩檢MCP stdio configs中的exfil patterns；並升級urllib3和PyJWT以清除CVEs。²¹

如果您正從v0.16.x升級，這裡沒有任何會破壞CLI的變更；它是在相同agent周邊新增channels、models和surfaces。免relay的iMessage、官方WhatsApp adapters，以及管理員用的Managed scope，是升級的主要理由。

v0.16.0 新增內容（The Surface Release）

Hermes Agent v0.16.0（標籤 v2026.6.5，2026年6月5日）以它放在 CLI 優先 agent 前方的新操作介面命名。重點是 Hermes 不再只限於終端機使用。²⁰

• 原生桌面應用程式。 Hermes Desktop 是全新的 Electron 應用程式，支援 macOS、Linux 和 Windows，提供一鍵安裝與應用程式內自我更新。它提供串流聊天視窗、拖放檔案、剪貼簿圖片貼上、Cmd+K 指令面板、具備封存與搜尋功能的工作階段清單，以及狀態列模型選擇器。它可以透過安全的 WebSocket 連線到遠端 Hermes gateway，並透過 OAuth 或使用者名稱/密碼驗證；也支援每個 profile 設定遠端主機，以及透過跨 profile @session 參照串連的多 profile 並行工作階段。桌面 UI 也透過型別化 i18n 層（display.language；英文仍為預設值）內建完整的簡體中文翻譯。²⁰
• 瀏覽器管理面板。 本機網頁 dashboard 已從狀態檢視升級為完整管理面板：包含 MCP 目錄與啟用/停用切換、憑證管理、webhook 與 hook 建立、記憶體設定、gateway 控制，以及具備更新前檢查與一鍵 Debug Share 的 System 頁面。新的 Channels 頁面可從瀏覽器設定每個 gateway 訊息平台（Telegram、Discord、Slack 及其他平台）。驗證現在可插拔：使用者名稱/密碼登入、通用自架 OIDC provider、用於自架 OAuth client 的 hermes dashboard register，以及 refresh-token 工作階段輪替。²⁰
• 新的 CLI 與 slash commands。 /undo [N] 會備份最後 N 個使用者回合，支援預填與軟刪除，並可在 CLI、TUI 及各訊息平台上運作。可設定的預設介面（cli 或 tui）已加入，並提供 --cli 覆寫；TUI 新增統一的 /model 指令與 Sessions overlay。hermes portal 是 Nous Portal onboarding 流程的人類可讀別名，新增首次執行的 Quick Setup 與 Full Setup 路徑，並加入兩個診斷工具：hermes prompt-size 和 hermes sessions optimize。²⁰
• 新的模型與 providers。 選擇器新增 deepseek-v4-flash、MiniMax-M3（1M context、原生 MiniMax providers）、qwen3.7-plus（Nous + OpenRouter）和 gemini-3.5-flash（Gemini OAuth + API key）。第一級 xAI Grok OAuth provider 加入桌面啟動器；模型選擇器在所有介面都支援模糊搜尋，多 endpoint providers 會彙整在同一列，目錄重新整理也從每日改為每小時。²⁰
• 更精簡的 skills 與漸進式揭露。 預設 skill 集移除了重複與停用的 skills（Spotify 移至原生 plugin，Linear 移至 hermes mcp install linear，並移除數個過時項目），將更多內容改為選用，並新增 environments: frontmatter 相關性閘門（kanban/docker/s6），讓特定情境 skills 在被請求前不會進入索引。NVIDIA/skills 現在與 OpenAI、Anthropic、HuggingFace 並列為預設信任的 Skills Hub tap。MCP 與 plugin tools 新增漸進式（範圍限定）tool 揭露，並修正一個 MCP bug：在未取得 token 時卻回報 OAuth 成功。²⁰
• 安全性。 v0.16.0 鎖定已修補的 Starlette（≥1.0.1）以處理 CVE-2026-48710（BadHost），在 async 路徑中將 SSRF URL 檢查移出 event loop，從 subprocess env 移除 Bedrock 推論 bearer token，將 bws_cache.json 加入檔案安全讀取防護，將 docker restart/stop/kill 加入危險模式清單，並清理已審核 skill 內容中的不可見 Unicode。此版本修復了 2 個 P0 和 62 個 P1 問題，其中 16 個帶有安全性標籤。²⁰

如果您是從 v0.15.x 升級，這些變更都不會破壞 CLI 本身；它們是在同一個 agent 周邊新增介面與 providers。若您想讓非終端機使用者執行 Hermes，或從瀏覽器管理遠端 gateway，桌面應用程式與管理面板就是升級主因。

安裝

單行安裝程式仍是大多數使用者的建議引導路徑。它會處理 Python、uv、Node.js、ripgrep、ffmpeg、repo clone、virtual environment，以及全域 hermes 指令。⁷ v0.14.0 也提供真正的 PyPI package，因此當您已能控制 Python 環境時，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（安裝程式會自動偵測 Termux，並切換到已測試的 Android bundle）。⁷ v0.14.0 透過 PowerShell 安裝程式加入早期 beta 的原生 Windows 支援，但在 Windows 路徑更成熟之前，正式環境仍建議使用 WSL2，會更穩妥。¹⁹

完成後：

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

唯一前置需求是 git。安裝程式會透過 uv 自動配置 Python 3.11（不需要 sudo）、Node.js v22（用於瀏覽器自動化與 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 討論串的診斷指令；它會以純文字摘要呈現整個設定，並遮蔽 secrets。⁸

手動安裝

如果您需要完整控制權，例如自訂 Python 版本、指定 extras，或整合 Nix/NixOS，上游安裝指南已逐步記載手動流程。⁷ 可與 uv pip install -e ".[<extras>]" 搭配的主要選用 extras 如下：

Termux 安裝指令不同，它使用帶有 constraints file 的 pip，而不是 uv pip：

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

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

驗證與 Providers

Hermes 支援約 19 個第一級 providers 加上自訂端點，並提供 3 種不同的驗證路徑。以下整理完整的驗證範圍，依路徑分類，方便您找到符合手上設定的方式。

3 種驗證路徑

Hermes 中的每個 provider 都屬於以下 3 種驗證模式之一：

路徑 1 — .env 中的 API key。 將您的 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，以及多數第三方 providers 都使用此方式。²

路徑 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。²

完整 Provider 矩陣

以下是第一級 providers 的完整清單，並列出每個 provider 的確切設定流程。²

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 不支援 classic 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 Providers（第一級支援）

Hermes 內建支援 z.ai/GLM、Kimi/Moonshot、MiniMax（global + China endpoints），以及具備專用 provider IDs 的 Alibaba Cloud。²

# 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 provider 時，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 與歷史紀錄。² 這會自動運作，無需設定。

hermes auth 指令

hermes auth 是用於 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 可讓您為同一個 provider 輪替多個 API keys 或 OAuth tokens。這對於在多個 keys 之間分散 rate limits 很有用，而且不需要修改程式碼。⁶ 舊版 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" routing path 的後備，因此如果您在那裡使用它們，請不要貿然刪除。）⁴

在 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（單獨使用，不帶 model name）會查詢您端點的 /v1/models API；若只載入 1 個 model，就會自動選取該 model。這對執行單一 model 的本機伺服器很實用。²

本機 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 長度非常低（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 參數，model 會嘗試在回應文字中寫入 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 會從 model metadata 讀取 context length，但許多 GGUF models 會回報 2048 或 4096 的預設值。請務必在 LM Studio model settings 中明確設定 context length：點選 model picker 旁的齒輪圖示，將 “Context Length” 設為至少 16384（最好是 32768），然後重新載入 model。²

具名自訂 Providers

如果您使用多個自訂端點（例如本機開發伺服器和遠端 GPU 伺服器），請在 config.yaml 中將它們定義為具名 custom providers：²

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 選單選取具名 custom providers。²

可插拔 Provider 架構（v0.13.0+）

v0.13.0 提供 ProviderProfile ABC 與 plugins/model-providers/ 目錄，讓第三方 inference providers 無需修改核心即可接入。¹⁸ 如果某個 provider 支援 OpenAI、Anthropic 或 Codex 相容的 API 模式，您可以實作 ProviderProfile 子類別，宣告驗證路徑、base URL、model catalog 與 caching headers；Hermes 會透過內建 providers 也使用的相同 runtime_provider.py 路徑解析它。這正是 v0.13.0 provider 擴充背後的架構變更：新增 provider 不再需要編輯核心程式碼，而是發布 plugin。

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

hermes proxy 會公開 OpenAI 相容的本機端點，其後端是 Hermes 已登入的 OAuth provider，例如 Claude Pro、ChatGPT Pro、SuperGrok，或其他相容且已設定的 provider。¹⁹ 這代表期待 OpenAI-style API 的工具，包括 Codex CLI、Aider、Cline、Continue 或自訂 scripts，都能重用您由訂閱支援的 Hermes auth，而不需要另外的 API key。請將此 proxy 視為本機開發基礎設施：有意識地綁定它，不要廣泛公開，並留意 provider 特定條款。

Context Length 偵測

根據上游文件，以下兩個設定經常被混淆：²

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

當自動偵測得到錯誤的 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-aware 能力，因此同一個 model 依 serving provider 不同，可能有不同的 context limits（例如 claude-opus-4.6 在 Anthropic direct 是 1M，但在 GitHub Copilot 是 128K）。²

Provider Rotation 與 Fallback

Credential pools。 當您對同一個 provider 有多個 API keys 時，可透過 hermes auth 設定 rotation strategy。這就是在多個 keys 之間分散 rate limits 的方式。⁶

Fallback model。 設定備用 provider:model，當 primary model 失敗時（rate limits、server errors、auth failures），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

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。²

輔助 Models

Hermes 會使用輕量級「輔助」models 處理附帶任務：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）。

您可以設定每個輔助任務使用哪個 model 與 provider。 每個 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 選項代表「使用我的 main agent 正在使用的任何 provider」；它只能用在 auxiliary:、compression: 和 fallback_model: 設定中。它不能用於頂層 model.provider 設定。如果您使用自訂 OpenAI-compatible endpoint 作為 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 registry。

設定檔版面配置

根據上游文件，以下檔案構成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為準。⁴規則如下： - Secrets（API keys、bot tokens、passwords）→ .env - 其他所有項目（model、terminal backend、compression settings、memory limits、toolsets）→ config.yaml

Secrets可以使用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. Environment variables——在程序啟動時套用
3. config.yaml——主要設定檔
4. .env——僅用於secrets
5. Built-in defaults——沒有其他來源設定值時套用

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

在地化（v0.13.0+）

v0.13.0為CLI和gateway訊息新增了7種locale：Chinese (Simplified)、Japanese、German、Spanish、French、Ukrainian和Turkish。¹⁸v0.14.0將所有gateway命令與web dashboard在地化，新增8種locale，總數達到16種。¹⁹目前文件僅提供zh-Hans在地化。Locale會從LC_ALL／LANG環境變數解析，或由config.yaml中的明確locale:鍵指定。English仍是預設值，也是任何尚未翻譯字串的事實來源。

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

Profiles讓您擁有多個彼此隔離的Hermes執行個體，每個都有自己的config、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命令參考。⁶

全域選項

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

頂層命令

hermes chat——主要進入點

不帶引數執行hermes會進入互動式 chat。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——結構化 Log 查詢

hermes logs比直接對 log 檔案執行tail -f更強大，因為它支援同時依層級、session 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

Log 檔案位於~/.hermes/logs/：⁶ - agent.log——所有 agent 活動（API calls、tool dispatch、session lifecycle、INFO+） - errors.log——僅包含 warnings 與 errors（agent.log 的篩選子集） - gateway.log——messaging gateway 活動（platform connections、dispatch、webhooks）

Rotation 會透過Python的RotatingFileHandler自動進行——請尋找agent.log.1、agent.log.2等檔案。⁶

hermes doctor——診斷

hermes doctor [--fix]是發生問題時應先執行的命令。它會檢查 config 有效性、dependency 是否存在、API key 可用性、service 狀態，並可搭配--fix嘗試自動修復。⁶

若要與他人分享診斷資訊，請使用hermes dump——它會產生精簡的純文字摘要，並遮蔽API keys，可直接貼到GitHub issue 或 Discord thread。⁶

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。⁹

工具與 toolset

Hermes 內建廣泛的工具登錄，涵蓋網頁搜尋、瀏覽器自動化、終端機執行、檔案編輯、記憶、委派、RL 訓練、訊息傳遞、Home Assistant 整合等功能。¹⁰工具會依邏輯整理成不同的 toolset，可按平台啟用或停用。

高階分類

常見的 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> 切換工具；這會重設工作階段，讓新的工具集合生效。⁹

終端機後端

終端機工具可在 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 後，已安裝的套件、檔案與設定會跨工作階段保留。¹⁰

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

背景程序

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

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

Multi-Agent Kanban（v0.13.0+）

v0.13.0 將多 agent 協作提升為一等基礎能力：一個持久 Kanban 看板，可跨 agent 與跨重新啟動追蹤工作、狀態與工作者身分。¹⁸這個看板讓一群 Hermes worker 能真正完成工作，而不是卡在失效的交接上。

Kanban 看板很自然地搭配 /goal（鎖定目標的 Ralph 迴圈）作為目標端，也可搭配既有的 delegate_task 工具處理生成語意。其結果是一種 swarm 模式：每個 agent 都共享同一個事實來源，知道下一步要做什麼、誰正在處理，以及哪些項目卡住。

Skills System

Skills 是代理程式可在需要時載入的隨選知識文件。它們採用漸進式揭露模式，以盡量降低 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

## Verification
How to confirm it worked.

條件式啟用

Skills 可以根據可用工具顯示或隱藏自己。這對備援 skills 特別有用，也就是只有在付費工具無法使用時才應出現的免費或本機替代方案：¹¹

範例：內建的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。當您設定了 FIRECRAWL_API_KEY，web toolset 就會可用，代理程式會使用 web_search，DuckDuckGo skill 則維持隱藏。若沒有 API key，DuckDuckGo skill 會自動以備援方案出現。¹¹

代理程式管理的 Skills

代理程式可以透過 skill_manage 工具建立、更新與刪除自己的 skills。這是代理程式的程序性記憶：當它摸索出非平凡的工作流程時，會將做法儲存為 skill，供日後重複使用。¹¹

代理程式建立 skills 的時機：¹¹ - 成功完成複雜任務後（5 次以上工具呼叫） - 曾遇到錯誤或死路，並找到可行路徑時 - 使用者修正其做法時 - 發現非平凡的工作流程時

動作：¹¹

Skill Hub

從線上登錄檔瀏覽、搜尋、安裝與管理 skills：⁶¹¹

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 安裝的 skills 都會經過安全性掃描器檢查，涵蓋資料外洩、prompt injection、破壞性命令、供應鏈訊號與其他威脅。¹¹

信任層級：¹¹

--force 可以覆寫 community skills 的非危險政策封鎖。它無法覆寫 dangerous 掃描判定。¹¹

外部 Skill 目錄

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

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

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

持久記憶

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

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

凍結快照模式：系統提示注入只會在工作階段開始時擷取一次，工作階段中不會變更。這是有意為之——它會保留LLM的前置快取以提升效能。工作階段中所做的變更會立即持久化到磁碟，但直到下一個工作階段才會出現在系統提示中。¹²

要儲存什麼

儲存這些項目（代理會主動執行）：¹² - 使用者偏好：「我偏好TypeScript而不是JavaScript」→ user - 環境事實：「此伺服器執行Debian 12與PostgreSQL 16」→ memory - 修正事項：「不要對Docker命令使用sudo，使用者在docker群組中」→ memory - 慣例：「專案使用tab、120字元行寬、Google風格docstrings」→ 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隨附8個外部記憶提供者外掛：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)

一次只能啟用1個外部提供者。內建記憶永遠啟用。⁶

工作階段自動續接（v0.13.0+）

v0.13.0讓代理執行中斷不再造成災難。gateway會在重新啟動後自動續接中斷的工作階段；/update重新啟動會在升級期間保留工作階段狀態；開發期間重新載入原始檔時，會保持作用中的工作階段，而不是強制建立新的工作階段。¹⁸實際效果是：長時間執行的gateway工作和cron驅動的工作，在程序重新啟動時不再重設其脈絡視窗。

Checkpoints v2（v0.13.0+）

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

Personality與SOUL.md

SOUL.md是Hermes實例的主要身分。它佔用系統提示中的第1個插槽，取代硬編碼的預設身分。¹³

Hermes會在~/.hermes/SOUL.md（或自訂profile的$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特定工作流程、命令、連接埠、路徑、部署備註。

一個實用規則：如果它應該到哪都跟著您，就放在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是工作階段層級的疊加。¹³建議保留務實的預設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授權，且完全開放原始碼。改變之處在於，您的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中移除。Managed tools現在會透過每個工具的use_gateway設定欄位啟用，並依據您的Portal訂閱狀態進行控管。²⁶

定位：此版本不是什麼

Hermes Agent CLI不是由訂閱鎖住。此專案仍採MIT授權，所有核心功能（CLI、skills、memory、messaging gateway、cron、MCP、本機dashboard、每個提供者的BYOK）都能在不付費給任何人的情況下端到端運作。v0.10.0為已經付費使用Nous Portal的使用者新增便利路徑——並沒有從免費路徑移除任何東西。

Messaging Gateway

Hermes可以作為長時間執行的gateway程序，從單一gateway程序連接到22個messaging platforms：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配接器。^325171819 v0.9.0透過BlueBubbles加入iMessage（自動webhook註冊、設定精靈、當機韌性），並透過iLink Bot API加入原生WeChat支援，且為企業app提供WeCom callback模式。¹⁶ 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 plugin hooks。¹⁸ v0.14.0加入LINE與SimpleX Chat，並以Graph auth、webhook listener、pipeline runtime與outbound delivery，完整補齊Microsoft Teams堆疊。¹⁹ v0.17.0（2026年6月19日）加入透過Photon Spectrum實現的免relay iMessage（device-code OAuth搭配hermes photon login——不需要Mac/BlueBubbles relay）、官方WhatsApp Business Cloud API配接器（取代bridge-process需求）、SimpleX groups與原生attachments，並將Raft作為內建平台plugin。²¹

設定

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

每個messaging platform都會經過與CLI相同的AIAgent對話迴圈。這就是為什麼slash commands在兩處都以相同方式運作，也解釋了為什麼在Telegram排程的cron job可以將輸出傳送到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對話。使用者從自己的messaging platform傳送配對碼；您使用hermes pairing approve核准後，該使用者自此便取得授權。⁶

排程任務（Cron）

Hermes具備一級cron系統，其中jobs是agent tasks，不是shell commands。每個scheduled job都會透過全新的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

或是在messaging chat中以對話方式建立：

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

agent會透過其tools設定cron job。Jobs會保存在JSON中，並在重新啟動後持續存在。³

MCP整合

Hermes同時支援作為client與server使用Model Context Protocol：⁶

作為client——將Hermes連接到外部MCP servers，以擴充其tool表面：

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內。compression summarizer是獨立的LLM呼叫——您可以將它指向任何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，因為它會收到對話的完整中段內容以進行壓縮。⁴

Budget Pressure Warnings

當agent處理需要大量tool calls的複雜任務時，可能在未察覺的情況下耗盡iteration budget（預設：90 turns）。Budget pressure會自動警告模型：⁴

Stream Timeouts

LLM streaming connection有兩層timeout，會針對local providers（localhost、LAN IPs）自動調整：⁴

對local endpoints而言，socket read timeout會提高到30分鐘，因為local LLMs在大型contexts上可能需要數分鐘進行prefill，才會產生第一個token。⁴

本機Web Dashboard（v0.9.0+）

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

Background Process Monitoring（v0.9.0+）

watch_patterns讓您設定要在background process輸出中監控的patterns，並在符合時即時收到通知。¹⁶ 可監控errors、等待特定events（「listening on port」），或觀察build logs——全程無須polling。結合v0.8.0的notify_on_complete（在background task完成時通知），Hermes如今具備完整的background process observability layer。¹⁵

Pluggable Context Engine（v0.9.0+）

Context管理現在可透過hermes plugins作為可插拔slot。您可以替換自訂context engines，控制agent每一turn看到的內容——包括filtering、summarization，或注入domain-specific context。¹⁶ 這將context策略與核心agent loop解耦，允許依project或domain客製context。

Backup & Restore（v0.9.0+）

hermes backup會建立包含config、sessions、skills與memory的完整封存檔。hermes import可從backup archive還原。¹⁶ 可用於在不同機器間遷移、重大變更前建立snapshot，或與隊友共享已知良好的configuration。

Termux / Android支援（v0.9.0+）

Hermes可透過Termux在Android上原生執行。經調整的install paths、針對行動螢幕最佳化的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    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

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

您的banner中顯示「47 tools / 20 toolsets」與「28 tools」的差異。「47 tools」是上游儲存庫的工具註冊總數，也就是Hermes隨原始碼提供的所有toolset中的每個工具。實際執行中的CLI會在啟動banner中顯示較小的數字（我用來驗證本指南的安裝顯示為28 tools / 89 skills）。這不是錯誤。許多toolset是選擇性啟用，必須在config.yaml的toolsets:下明確開啟，例如訊息平台adapter、瀏覽器自動化、較重的擷取工具等。註冊總數代表「可用項目」；banner數字代表「目前profile中已啟用的項目」。使用hermes tools --list檢查哪些toolset處於啟用狀態，並透過~/.hermes/config.yaml中的toolsets:區塊啟用或停用個別toolset（或在執行中的session內使用/tools list／/tools enable <name>／/tools disable <name>；移除工具會觸發session重設，讓agent重建其工具manifest）。

三種API模式

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

runtime_provider.pyresolver會將(provider, model)tuple對應到(api_mode, api_key, base_url)，支援18個以上provider，並處理OAuth流程、憑證pool與alias解析。³

CLI Session中的資料流程

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

出自上游架構頁面。³

Prompt組裝順序

prompt stack包含：¹³

1. SOUL.md（agent身分；若無法使用，則採用內建fallback）
2. 具備工具意識的行為指引
3. 記憶／使用者情境（MEMORY.md、USER.md）
4. Skills指引
5. 情境檔案（AGENTS.md、.cursorrules）
6. 時間戳記
7. 平台特定格式提示
8. 選用的system-prompt overlay，例如/personality

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

Session儲存

以SQLite為基礎的session儲存，搭配FTS5全文搜尋。Session具備lineage tracking（compression之間的parent/child）、各平台隔離，以及具備競爭處理的atomic writes。³

Plugin系統

三個探索來源：~/.hermes/plugins/（使用者）、.hermes/plugins/（專案），以及pip entry points。Plugin會透過context 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、預設model、自訂providers、MCP servers、訊息平台token與允許清單（Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost）、agent defaults（reasoning effort、compression、human delay、timezone、sandbox）、session reset policies、approval rules、TTS config、browser settings、tool settings、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解析會依優先順序檢查三個來源：config values → ~/.openclaw/.env → auth-profiles.json。⁶

疑難排解

「API key not set」

執行hermes model以互動方式設定您的 provider，或執行hermes config set OPENROUTER_API_KEY your_key。hermes doctor命令會明確告訴您缺少哪些 key。⁷

啟動時出現「Context limit: 2048 tokens」（本機 models）

Hermes 會從您伺服器的/v1/models端點自動偵測 context 長度，但許多本機伺服器會回報偏低的預設值。請在config.yaml中明確設定：²

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

Tool calls 顯示成文字，而不是執行

您的伺服器未啟用 tool calling，或該 model 不支援透過伺服器實作來使用此功能。²

回應在句子中途被截斷

可能有 2 種原因：²

1. 伺服器上的輸出上限偏低（max_tokens）——SGLang 預設每則回應為 128 tokens。請在伺服器上設定--default-max-tokens，或在config.yaml中設定model.max_tokens。
2. Context 耗盡——model 填滿了自己的 context window。請提高model.context_length，或在 Hermes 中啟用 context compression。

從 WSL2 連到 Windows 主控的 model 伺服器時出現「Connection refused」

WSL2 使用具有自身子網路的虛擬網路介面卡——WSL2 內的localhost指的是 Linux VM，而不是 Windows 主機。有 2 種選項：²

Mirrored networking（Windows 11 22H2 以上）：編輯%USERPROFILE%\.wslconfig：

[wsl2]
networkingMode=mirrored

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

Host IP fallback（較舊的 Windows）：從 WSL2 內取得 Windows 主機 IP，並改用它取代localhost：

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

您也需要讓 model 伺服器綁定到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會顯示所有 log 檔案及其大小。hermes config path會印出設定檔位置。hermes config env-path會印出.env位置。⁶

FAQ

Hermes Agent 和 Claude Code 有什麼不同？

Claude Code 是 Anthropic 官方的 CLI，綁定 Anthropic models。Hermes Agent 是 Nous Research 的開源 agent framework，可搭配任何 OpenAI-compatible provider 使用——Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google，或您自行託管的 endpoint。¹² Hermes 也內建 Telegram/Discord/Slack/WhatsApp/Signal 的 messaging gateway，這是 Claude Code 所沒有的。

我可以用 Anthropic API key 搭配 Hermes 嗎？

可以。有 3 種方式：²

1. 在~/.hermes/.env中設定ANTHROPIC_API_KEY，並執行hermes chat --provider anthropic --model claude-sonnet-4-6
2. 執行hermes model並選擇 Anthropic——可用時，Hermes 會使用 Claude Code 的 credential store
3. 設定手動ANTHROPIC_TOKEN（setup-token 或 OAuth token）作為 fallback

如果您已在同一台機器上使用 Claude Code，建議採用選項 2——它會讓可重新整理的 Claude credentials 維持可重新整理。

如何在不遺失對話的情況下切換 providers？

在 session 中使用/model provider:model。對話歷史、memory 和 skills 都會一併保留：⁹

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

我已設定 Anthropic，但 vision/web/compression 無法運作

您遇到的是 auxiliary model fallback。Vision、web summarization、compression 和其他側邊工作會使用獨立的 auxiliary LLM——預設透過自動偵測使用 Gemini Flash（OpenRouter → Nous → Codex）。如果這些都沒有設定，而您只設定了 Anthropic，這些功能會靜默降級。⁴

修正方式：加入OPENROUTER_API_KEY供 auxiliary tasks 使用，或將 auxiliary slots 重新設定為使用您的主要 provider。請注意，context compression 位於自己的頂層compression:區塊，並使用summary_provider，而不是auxiliary.compression.provider——auxiliary.compressionslot 只公開timeout。完整修正如下：

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

compression:
  summary_provider: "main"

SOUL.md 和 AGENTS.md 有什麼不同？

SOUL.md是您的 agent 身分——語氣、風格、溝通預設值。它位於~/.hermes/SOUL.md，會一路跟著您。AGENTS.md則是專案專用——架構、慣例、命令、路徑——並位於您的專案目錄中。¹³ 如果內容應該處處跟著您，放在SOUL.md。如果它屬於某個專案，放在AGENTS.md。

如何並行執行多個 Hermes instances？

使用 profiles。每個 profile 都有自己的HERMES_HOME、config、memory、sessions 和 gateway 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 支援本機 LLMs 嗎？

支援，透過 custom endpoint 路徑即可。Hermes 可搭配任何 OpenAI-compatible server 使用：Ollama、vLLM、SGLang、llama.cpp/llama-server、LM Studio、LocalAI、Jan，或您自己的伺服器。² 請參閱Custom & Self-Hosted Endpoints了解各伺服器設定。

為什麼我的啟動畫面顯示的 tools 比指南所說的 Hermes 擁有數量更少？

本指南引用的是 upstream architecture registry 中的 47 tools / 20 toolsets——這是 Hermes 在所有 toolset 中提供原始碼的完整 tools 數量。您的執行中安裝版本會在啟動畫面顯示較小的數字（本指南使用的參考安裝回報 28 tools），因為 Hermes 啟動時只會啟用預設 toolset 集合。許多 toolsets 是選擇性啟用：messaging gateway adapters、browser automation、較重的 scraping stacks，以及數個專門 integrations，都必須先在~/.hermes/config.yaml的toolsets:下明確列出才會載入。Registry total =「啟用後可用的項目」。Banner total =「目前 profile 實際載入的項目」。使用hermes tools --list查看哪些 toolsets 已啟用，以及哪些可用但停用。可在執行時用/tools enable <name>和/tools disable <name>切換個別 toolsets（停用會觸發 session reset，讓 agent 以新的形狀重建 tool manifest）。

當主要 provider 失敗時，Hermes 如何處理 model fallback？

在config.yaml中設定fallback_model區塊：²

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

當主要 provider 失敗（rate limit、server error、auth failure）時，Hermes 會在 session 中途切換到 fallback，而不會遺失對話歷史。每個 session 最多觸發一次。

Agent 可以隨時間改善自己的 skills 嗎？

可以——這正是 Hermes Agent「self-improving」的部分。Agent 可以透過skill_managetool 建立、更新和刪除 skills。當它找出非平凡的 workflow 時，會把做法保存為 skill，以便日後重複使用。¹¹ Agent 會在複雜任務後（5 次以上 tool calls）、遇到錯誤並找到可行路徑時、您修正它的做法時，或它發現非平凡 workflow 時建立 skills。

是否有 IDE integration？

有——Hermes 可以作為 VS Code、Zed 和 JetBrains 的 ACP（Agent Client Protocol）伺服器執行：⁶

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

變更記錄

參考資料