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

重點摘要： Hermes Agent 是 Nous Research 推出的開源自我改進型 AI 代理程式。它可作為 CLI 執行，也能充當多平台訊息 gateway；它會將持久身分與長期記憶儲存在磁碟上，彙整可隨使用持續改進的 skills，並支援任何與 OpenAI 相容的 LLM 供應商——包括 Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Qwen Cloud、Hugging Face、Google、xAI/SuperGrok，以及您自行託管的端點。¹²¹⁹ 自 v0.14.0（2026年5月16日）起，Hermes 新增支援具備 grok-4.3 100萬 context 的 SuperGrok OAuth、供 OAuth 供應商使用且與 OpenAI 相容的本機 proxy（hermes proxy）、原生 x_search、PyPI 安裝支援（此方式自 v0.19.0 起已棄用——目前支援的安裝方式為單行安裝程式）、延遲安裝相依套件、涵蓋 LINE 與 SimpleX Chat 的 22 個訊息平台、/handoff、寫入後的 LSP 語意診斷、統一的 video_generate、透過 cua-driver 為非 Anthropic 供應商提供的 computer_use、原生 Windows Beta 版，以及 12 項 P0／50 項 P1 問題結案。¹⁹ 對多數新使用者而言，最困難的環節是供應商驗證：Hermes 支援約 20 個一級供應商及自訂端點，並提供 3 種不同的驗證途徑（.env 中的 API 金鑰、透過 hermes model 使用 OAuth，或在 config.yaml 中設定自訂端點）。驗證模型是首要掌握的重點——後續一切都取決於最終解析出的供應商。

Hermes Agent 是完整的代理程式執行環境，而非聊天介面的簡單包裝。它能讀取您的檔案系統、在沙箱後端執行指令、擷取網頁、產生子代理程式、執行排程 cron 工作，並透過單一 gateway 程序與 Telegram／Discord／Slack／WhatsApp／Signal／Email 通訊，還能從經驗中建立自己的 skills。¹ CLI 是建構於 run_agent.py 對話迴圈之上的終端機 UI；gateway 則是長時間執行的程序，負責將訊息平台傳來的訊息導向同一個對話迴圈。³

Hermes 的一般用法與專家級用法，差別歸根究柢在於 5 套系統。 掌握這些系統後，Hermes 就能讓您的工作效能倍增：

1. 供應商解析：驗證流程如何對應至 API 呼叫
2. 設定階層：config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. 工具與 toolset 系統：代理程式能執行哪些操作，以及各平台如何限制其權限
4. Skills 系統：由代理程式建立並持續演進的程序性記憶
5. Gateway、cron 與 profiles：讓 Hermes 在您日常使用的平台上運作，而不只侷限於目前所在的介面

重點整理

• 供應商驗證有 3 種途徑，而非只有一種。 在 .env 中設定 API 金鑰、透過 hermes model／hermes auth 使用 OAuth，或在 config.yaml 中設定自訂端點。請選擇符合供應商的途徑，而非僅憑熟悉程度決定。
• 切換供應商只需一行指令。 hermes model 會以互動方式引導您設定每個支援的供應商，包括 OAuth 登入；/model provider:model 則可在工作階段途中切換，且不會遺失歷史記錄。²
• 使用者可編輯的設定介面由 2 個檔案構成。 ~/.hermes/config.yaml 儲存設定，~/.hermes/.env 儲存機密資料。auth.json、SOUL.md、MEMORY.md 與 skills/ 皆由 Hermes 直接管理——您可以手動編輯 SOUL.md，其餘項目則由代理程式自行處理。⁴
• Hermes 是 OpenClaw 的後繼者。 若要移轉，hermes claw migrate 可自動匯入超過 30 類狀態資料。⁵
• 服務品質取決於您的輔助模型。 視覺處理、網頁摘要、壓縮與記憶體寫回皆使用另一個輔助 LLM。預設會透過自動偵測選用 Gemini Flash（OpenRouter → Nous → Codex）——若上述服務皆未設定，這些功能會悄然降級，直到您將輔助欄位指向主要供應商為止。⁴

v0.14 的變更

v0.14.0 並非著重於某項指標性功能，而是致力於降低設定門檻，同時擴大 Hermes 的執行環境。¹⁹ 主要操作變更如下：

• 安裝與啟動更加輕量。 可透過 PyPI 執行 pip install hermes-agent，大型轉接器會在首次使用時才安裝，而啟動流程也會延後足夠多的工作，使冷啟動時間縮短約 19 秒。（v0.19.0 此後已棄用 pip 安裝——請參閱安裝。）
• 訂閱服務可轉換為本機 API 端點。 hermes proxy 可將 Claude Pro、ChatGPT Pro 與 SuperGrok 等採用 OAuth 的供應商，轉換為與 OpenAI 相容的本機端點，供 Codex、Aider、Cline 與 Continue 等工具使用。
• Gateway 的觸及範圍進一步擴大。 LINE 與 SimpleX Chat 將平台總數提升至 22 個，Microsoft Teams 已完成端對端串接，Discord 預設啟用歷史記錄回填，而 Telegram／Discord 的 clarify 提示現在會使用原生按鈕。
• 寫入時驗證更加完善。 編輯完成後，Hermes 可在下一輪互動前顯示每輪的檔案變更摘要與語言伺服器語意診斷，使其更接近以證據為本的代理程式工作方式。
• 桌面與媒體工具的支援範圍更廣。 非 Anthropic 供應商可透過 cua-driver 使用 computer_use，video_generate 已整合至可插拔後端架構，而 vision_analyze 會將原始像素傳送至真正具備視覺能力的模型。

以下各節皆以 hermes-agent.nousresearch.com/docs 的上游文件，以及 github.com/NousResearch/hermes-agent 的原始碼樹狀結構為依據。每項事實陳述皆附有註腳，指向其出處的特定上游頁面。

選擇您的路徑

Hermes 的運作方式：心智模型

Hermes 以單一對話迴圈為核心，任何進入點都能呼叫此迴圈。進入點包括 CLI（cli.py）、訊息 gateway（gateway/run.py）、用於編輯器整合的 ACP 介接器、批次執行器，以及 API 伺服器。³這些進入點最終都會呼叫 run_agent.py 中的 AIAgent.run_conversation()，其流程如下：

1. 透過 prompt_builder.py，根據 SOUL.md、MEMORY.md、USER.md、skills、context 檔案及工具指引建構系統提示³
2. 透過 runtime_provider.py 解析執行階段 provider——此步驟會選定您的驗證方式、基底 URL 及 API 模式³
3. 使用下列 3 種 API 模式之一呼叫 provider：chat_completions、codex_responses 或 anthropic_messages³
4. 透過 model_tools.py 與中央工具登錄檔（tools/registry.py）分派傳回的所有工具呼叫³
5. 持續迴圈，直到模型產生最終回覆，再將工作階段持久化至採用 FTS5 的 SQLite³

理解此迴圈至關重要，因為每項功能——personality、記憶、skills、壓縮、fallback——都會附加至其中一個階段。閱讀某個設定鍵並思考其用途時，答案通常是：「它是用來調整上述迴圈第 1、2、3 或 4 階段的控制項。」

跨平台核心。單一 AIAgent 類別即可服務 CLI、gateway、ACP、批次作業及 API 伺服器。平台差異存在於進入點，而非 agent 本身。³因此，相同的斜線命令能同時在終端機與 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.19.0（Quicksilver Release）有哪些新功能

Hermes Agent v0.19.0（標籤 v2026.7.20，2026年7月20日）以信使之神自身的速度命名：本次版本的主軸是全面提升回應速度，所有平台的首輪首個 token 等候時間皆縮短約 80%。圍繞此主軸推出的功能還包括終端機帳務管理、密碼管理器密鑰來源、預設啟用智慧核准、可觀測的 subagents，以及不受當機影響的回覆傳送機制。自 v0.18.0 以來的開發規模更創下專案新高：約 2,245 次提交、約 1,065 個合併的 PR、約 3,300 個已關閉的議題，以及超過 450 位社群貢獻者。²³

• 在任何平台上，首個 token 都快約 80%。從冷啟動送出到分派的時間，在 CLI、gateway、TUI、桌面版及 cron 中均由約 4.3 秒降至約 0.9 秒——Discord 功能偵測已移出關鍵路徑；遇到已知非 Ollama provider 時會略過 Ollama 探測；agent 初始化階段也不再執行阻塞作業。感知延遲亦經過專門改善：推理模型現在預設會即時串流其思考過程（display.show_reasoning 為 ON），回覆方塊也改為逐 token 繪製，而非逐行繪製。²³
• 桌面版與 TUI 的算繪革新。桌面應用程式經歷約 20 個 PR 的速度大幅改造：串流 Markdown 分割器藉由增量區塊詞法分析，CPU 使用量減少 14 倍；檢閱窗格採用虛擬化差異檢視；大型逐字稿的工作階段切換更加迅速；側邊欄與工具列也不再隨每個 token 重新算繪。TUI 現在則會依區塊增量算繪串流 Markdown。²³
• pip 與 Homebrew 安裝方式已淘汰。這兩種途徑現已標示為「不受支援的舊版」安裝方式——所有介面都會發出警告，但不會阻止使用，並已規劃停止透過 PyPI/Homebrew 發布。官方支援的途徑是一行式安裝程式；若先前透過 pip 或 brew 安裝，請立即規劃移轉。²³
• 密鑰可取自密碼管理器。全新的可插拔 SecretSource 介面會在載入時，從 Bitwarden 與 1Password（op:// 參照）擷取密鑰；可同時啟用多個保存庫，並提供明確且固定的優先順序、衝突警告，以及逐變數的來源追蹤——API 金鑰不必再存放於純文字 .env 中。未來的保存庫 provider 也能以 plugins 形式直接加入。²³
• 智慧核准現已成為預設選項。當 Hermes 想執行遭標記的命令時，獨立的 LLM 檢閱者會進行評估，不再每次都提示您——而且每項裁決僅適用於該次確切命令。使用者定義的 deny rules 即使在 YOLO 模式下也會封鎖符合條件的命令；/deny <reason> 會將您的拒絕理由傳回，讓 agent 修正方向；plugin 的 pre_tool_call 核准動作（重新加入 rule keys 後再次推出）則會將工具呼叫升級為由人員把關。²³
• 終端機帳務管理：/subscription 與 /topup。無須離開終端機，即可管理 Nous Portal 方案——查看方案與剩餘額度、準確預覽升級費用或降級生效時間，並套用變更且可復原。桌面應用程式也新增了對應的帳務設定分頁。²³
• 即時查看 subagents 的工作，完成的答案永不遺失。delegate_task 分派後會傳回即時逐字稿檔案，subagents 一啟動即可使用 tail -f 追蹤——每個工具呼叫、結果及串流回覆都會記錄在各 child 專屬、易於閱讀的日誌中。背景委派即使重新啟動也能保留完成狀態；gateway 的最終回覆則會記錄於 state.db 內的 傳送義務帳本。若 gateway 在傳送途中終止，便會於下次啟動時重新傳送。max_async_children 設定選項已淘汰，改由統一的委派並行上限取代。²³
• 單一 gateway，多個 profiles。單一多工 gateway 可共用同一個機器人 token，並將特定 guild、頻道或討論串路由至不同 profiles——各自擁有完全隔離的設定、skills、記憶及密鑰——亦可透過 GATEWAY_MULTIPLEX_PROFILES 覆寫。路由索引已移至 state.db；sessions.json 現為選用的舊版鏡像。²³
• Providers 與模型更新浪潮。Fireworks AI 獲得第一級支援（包括成本估算，且在 provider 選擇器中位居第 2），DeepInfra 與 Upstage Solar 也同步加入。模型目錄新增 GPT-5.6（Sol/Terra/Luna + Pro，完整串接端對端流程）、grok-4.5（正式推出）、kimi-k3（kimi-k2.x 已退役），以及完整串接的 Claude Sonnet 5。每個 provider 可使用 enabled: false 旗標，並透過 excluded_providers 設定，從 /model 選擇器與解析流程中徹底移除未使用的 providers。²³
• 推理強度成為可調旋鈕。所有介面均新增 max 與 ultra 強度層級，並支援設定中的逐模型覆寫、MoA presets 中的逐 slot 強度（advisors 深入思考，synthesizer 維持快速）、輔助模型的逐任務強度，以及 CLI 中僅限當前工作階段的 /reasoning。²³
• CLI 與 MCP 介面。hermes sessions export 可匯出 Markdown、Quarto、HTML、僅提示內容及 Hugging Face trace 格式，並提供選用的 --redact 清除功能；/model --once 可單次覆寫一輪模型；斜線 skill 呼叫可堆疊使用（/skill-a /skill-b do XYZ）；--safe-mode 有助於疑難排解；hermes config get/unset 補齊設定管理功能；hermes serve 成為真正的無介面後端；MCP 工具則採用 mcp__server__tool 命名慣例。²³

若要從 v0.18.x 升級，應優先留意 2 項變更：透過 pip 或 Homebrew 安裝現會顯示「不受支援的舊版」警告（請改用一行式安裝程式），而 max_async_children 也已淘汰，改由統一的委派並行上限取代。其餘變更皆為新增功能——最值得升級的理由包括首輪延遲縮短約 80%、智慧核准，以及讓完成答案不受當機影響的傳送帳本。

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

Hermes Agent v0.18.0（標籤 v2026.7.1，2026年7月1日）以「判斷」為名：agent 會驗證自己的成果，不再只是宣稱成功；您也能實際檢視整合式推理過程。此版本還清空了所有 P0/P1 待辦事項——在 12 天內解決約 692 個最高優先級項目。²²

• 將 Mixture-of-Agents 提升為第一級模型。 現在，您可以像選擇其他模型一樣，在所有介面中選用 MoA，並查看整合式推理過程。每個參考模型的完整輸出都會呈現為獨立的標示區塊，並即時串流答案——您能親眼觀察模型群如何思考，而不是只得到內容不透明的合併答案。²²
• /goal 的完成契約。 agent 會先執行專案檢查，驗證自己的成果，再回報目標已完成，而非逕自宣稱成功——將判斷力用在自身。²²
• /learn——將任何描述轉化為 skill。 只要描述工作流程，就能將其轉換成可重複使用的 skill；產生的 skill 會自動遵循儲存庫的 CONTRIBUTING.md 慣例。²²
• /journey 時間軸。 以視覺化方式呈現記憶與 skills 隨時間演進的歷程，支援編輯，桌面版另提供記憶關聯圖。²²
• 背景 subagent 扇出執行。 可委派多項任務同時執行，且不會阻塞對話——v0.17.0 的單一背景 subagent 如今擴展為一支團隊。²²
• 桌面版 Projects。 提供第一級程式開發 Projects，採用 project/repo/lane 組織模型。²²
• 可縮減至零的 gateway。 gateway 可在閒置時休眠，並協調流量排空以實現無縫部署——對於將 Hermes 作為常駐服務執行的使用者而言，意義重大。²²
• 支援 Google Vertex AI。 可透過 GCP 服務帳戶存取 Gemini，並自動重新整理 OAuth2 token，正式納入 provider 目錄。²²
• /prompt 編輯器指令。 開啟 $EDITOR 編寫多行提示，不必再受限於單行輸入。²²

若從 v0.17.x 升級，此版本不會破壞 CLI。最值得升級的功能包括完成契約（能自行驗證的目標）、具備可檢視模型群的第一級 MoA，以及用於擷取 skill 的 /learn。

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

Hermes Agent v0.17.0（標籤 v2026.6.19，2026年6月19日）以 agent 如今觸及的廣度為名——新增訊息通道、模型 provider，以及更深入的桌面版與 dashboard 控制功能。此版本在 v0.16.x 的基礎上擴充，CLI 介面維持不變。²¹

• 新增訊息通道。 iMessage 現在可透過 Photon Spectrum 運作，無須 Mac relay（使用裝置代碼 OAuth、hermes photon login）；WhatsApp Business Cloud API 成為 Meta 官方 adapter，取代原有的 bridge process 要求；SimpleX 新增群組、原生附件、文字批次處理及自動接受功能；Raft 也以內建 platform plugin 之姿加入，採用以隱私契約為基礎的喚醒通道設計。²¹
• 新增模型與 provider。 目錄新增 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 模型，200k context）。xAI 的預設模型已改為 grok-build-0.1，Anthropic adaptive 模型現在也遵循現代 thinking contract（絕不傳送 reasoning 欄位）。²¹
• 桌面版與 dashboard。 桌面版新增背景 subagent，透過即時「watch-windows」串流委派活動（delegate_task(background=true)），並提供 Composer 模型選擇器、可重新綁定的鍵盤快速鍵、原生作業系統通知、各 thread 獨立的 composer 草稿、VS Code Marketplace 主題，以及日文與繁體中文介面。dashboard 則新增完整的 profile 建立工具（無須編輯 config.yaml 即可設定 model/skills/MCPs）、全域 profile 切換器、經過重新設計且具備安全掃描功能的 Skills Hub、Automation Blueprints（適用於表單、slash command、對話與文件的參數化範本），以及安全登入機制；位於 OAuth gate 後方時會傳回 401。²¹
• Skills 與工具。 image_generate 現在不僅能從頭建立圖片，也能在所有支援的圖片 provider 上編輯及轉換來源圖片；memory 工具新增 operations 陣列，可在單次呼叫中以不可分割的批次方式新增、取代或移除內容；新的 simplify-code skill 會執行由 3 個 agent 並行處理的檢閱與清理流程，並以 Chesterton’s-Fence 風險等級把關；布林值 write_approval 則取代了三態的 write_mode。²¹
• 架構。 背景 subagent 會立即傳回 handle，並將結果作為新的 turn 重新帶入；MCP elicitation handler 可在 tool call 進行期間要求確認，較晚連線的 MCP 工具則會在 turn 之間公開（可安全快取）；cron 改為可插拔的 CronScheduler，並支援 Chronos 代管 cron provider；新的 Managed scope（/etc/hermes）可讓管理員固定使用者無法修改的設定，另提供 Gateway-Gateway relay，以支援多 gateway 拓撲。²¹
• 新增指令。 /version、/billing（互動式終端機帳務）、hermes photon login（iMessage auth），以及 hermes curator run --consolidate——consolidation 現在改為選用，因此例行的背景整理不會耗用任何 token。²¹
• 安全性。 v0.17.0 修補 shell escape denylist 繞過問題；缺少 approval module 或自有政策 gateway adapter 時，改為採取封閉式失敗；清理 cron 工作指令碼子行程的環境；遮蔽 request debug dump 中的秘密資訊；掃描 MCP stdio 設定中的資料外洩模式；並升級 urllib3 與 PyJWT，以排除 CVE。²¹

若從 v0.16.x 升級，此版本不會破壞 CLI；它只是在同一個 agent 周邊加入新的通道、模型與介面。無須 relay 的 iMessage、官方 WhatsApp adapter，以及供管理員使用的 Managed scope，是本次升級的重點。

v0.16.0 的新功能（The Surface Release）

Hermes Agent v0.16.0（標籤 v2026.6.5，2026年6月5日）以它為 CLI 優先的 agent 帶來全新介面而得名。最大亮點是 Hermes 不再僅限於終端機。²⁰

• 原生桌面應用程式。 Hermes Desktop 是適用於 macOS、Linux 與 Windows 的全新 Electron 應用程式，支援一鍵安裝與應用程式內自動更新。它提供串流聊天視窗、檔案拖放、從剪貼簿貼上圖片、Cmd+K 選單、支援封存與搜尋的 session 清單，以及狀態列模型選擇器。它能透過安全的 WebSocket 連線至遠端 Hermes gateway，並以 OAuth 或使用者名稱與密碼進行驗證；還支援各 profile 獨立的遠端主機，以及透過跨 profile 的 @session 參照連結多個並行 profile session。桌面介面亦透過強型別 i18n 層（display.language；英文仍為預設語言）提供完整的簡體中文（简体中文）翻譯。²⁰
• 瀏覽器管理面板。 本機 web dashboard 已從狀態檢視畫面升級為完整的管理面板，包含具備啟用／停用切換功能的 MCP 目錄、憑證管理、webhook 與 hook 建立功能、記憶設定、gateway 控制，以及提供更新前檢查與一鍵 Debug Share 的 System 頁面。新的 Channels 頁面可直接從瀏覽器設定所有 gateway 訊息平台（Telegram、Discord、Slack 等）。驗證機制現在可插拔，包括使用者名稱／密碼登入、通用的自行代管 OIDC provider、用於自行代管 OAuth client 的 hermes dashboard register，以及 refresh token session rotation。²⁰
• 新增 CLI 與 slash command。 /undo [N] 可回退最近 N 個使用者 turn，並提供預先填入與軟刪除功能；此指令可在 CLI、TUI 與各訊息平台使用。新增可設定的預設介面（cli 或 tui），並可使用 --cli 覆寫；TUI 則新增統一的 /model 指令與 Sessions overlay。hermes portal 是 Nous Portal 新手設定流程中易於理解的別名，首次執行時新增 Quick Setup 與 Full Setup 路徑，另提供兩項診斷功能：hermes prompt-size 與 hermes sessions optimize。²⁰
• 新增模型與 provider。 選擇器新增 deepseek-v4-flash、MiniMax-M3（1M context、原生 MiniMax provider）、qwen3.7-plus（Nous + OpenRouter）與 gemini-3.5-flash（Gemini OAuth + API key）。第一級 xAI Grok OAuth provider 也加入桌面啟動器；模型選擇器在所有介面上都改為模糊搜尋；多 endpoint provider 會歸在同一列；目錄重新整理頻率則從每日一次改為每小時一次。²⁰
• 更精簡的 skills 與漸進式揭露。 預設 skill 組合移除重複及已失效的 skills（Spotify 移至原生 plugin，Linear 改用 hermes mcp install linear，另移除數個過時項目），將更多 skills 改為選用，並新增 environments: frontmatter 關聯性 gate（kanban／docker／s6），在使用者提出要求前，不會讓特定情境的 skills 出現在索引中。NVIDIA/skills 現在與 OpenAI、Anthropic 及 HuggingFace 一同列為 Skills Hub 的預設信任 tap。MCP 與 plugin 工具新增漸進式（範圍限定）工具揭露功能；此外，先前 MCP 在未取得 token 時仍錯誤回報 OAuth 成功的問題也已修正。²⁰
• 安全性。 v0.16.0 固定使用已修補的 Starlette（≥1.0.1），以處理 CVE-2026-48710（BadHost）；在非同步路徑中，將 SSRF URL 檢查移出 event loop；從子行程環境中移除 Bedrock inference bearer token；將 bws_cache.json 加入檔案安全讀取防護；將 docker restart/stop/kill 加入危險模式清單；並清理經審查 skill 內容中的不可見 Unicode 字元。此版本關閉了 2 個 P0 與 62 個 P1 問題，其中 16 個標記為安全性問題。²⁰

若從 v0.15.x 升級，這些變更都不會對 CLI 本身造成破壞性影響；它們只是在同一個 agent 周邊增添介面與 provider。若您希望讓不使用終端機的使用者也能操作 Hermes，或要從瀏覽器管理遠端 gateway，桌面應用程式與管理面板便是升級的主要理由。

安裝

單行安裝程式是官方支援的安裝方式。它會處理Python、uv、Node.js、ripgrep、ffmpeg、複製儲存庫、虛擬環境，以及全域hermes指令。⁷

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

自v0.19.0起，已不建議使用pip和Homebrew安裝。 v0.14.0推出的PyPI套件（pip install hermes-agent）與Homebrew公式，如今均標示為「不受支援的舊版」安裝方式。Hermes偵測到其中任一方式時，所有介面都會顯示警告（但不會阻擋執行），並計畫停止透過PyPI/Homebrew發布。若先前使用pip或brew安裝，請改用上述安裝程式。²³

支援Linux、macOS、WSL2及Android/Termux（安裝程式會自動偵測Termux，並改用通過測試的Android套件組合）。⁷ v0.14.0透過PowerShell安裝程式新增仍處於早期測試階段的原生Windows支援；但在Windows安裝方式更加成熟之前，正式環境仍建議使用較穩妥的WSL2。¹⁹

完成後：

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

唯一的先決條件是git。安裝程式會透過uv自動佈建Python 3.11（無須sudo權限）、Node.js v22（供瀏覽器自動化及WhatsApp橋接器使用）、ripgrep與ffmpeg。⁷

驗證安裝

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

hermes doctor會明確指出缺少哪些項目，以及修正方式。⁷ 尋求協助時，可執行hermes dump並將診斷結果貼到GitHub議題或Discord討論串。它會以純文字摘要呈現完整設定，並遮蔽其中的機密資訊。⁸

手動安裝

若需要完整掌控安裝流程，例如自訂Python版本、指定額外套件或整合Nix/NixOS，上游安裝指南提供了逐步操作說明。⁷ 以下是可搭配uv pip install -e ".[<extras>]"組合使用的主要選用額外套件：

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

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

這是因為Android上的.[all]會透過voice額外套件引入faster-whisper，而後者依賴尚未針對Android發布的ctranslate2wheel套件。⁷

驗證與供應商

Hermes 支援約22個一級供應商及自訂端點（v0.19.0 新增 Fireworks AI、DeepInfra 與 Upstage Solar），並提供3種不同的驗證路徑。以下按路徑整理完整的驗證方式，方便您找到符合現有條件的選項。

3種驗證路徑

Hermes 中的每個供應商都採用以下3種驗證模式之一：

路徑1—將 API 金鑰存入 .env。 將金鑰放入 ~/.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，以及大多數第三方供應商皆採用此方式。² 自 v0.19.0 起，金鑰不再必須存放於純文字檔案：可插拔的 SecretSource 介面能在載入時從 Bitwarden 或 1Password（op:// 參照）擷取機密資料，且可同時啟用多個密碼庫，提供明確固定的優先順序、衝突警告及個別變數的來源追蹤；.env 則仍作為後備方案。（這與 v0.15.0 的 Bitwarden Secrets Manager 啟動權杖不同；後者以單一權杖集中管理供應商金鑰。SecretSource 直接取代純文字檔案本身，未來的密碼庫供應商也能以外掛形式加入。）²³

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

完整供應商對照表

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

自 v0.19.0 起，還能排除不使用的供應商：個別供應商的 enabled: false 旗標及 excluded_providers 設定鍵，可將其從 /model 選擇器和內建供應商解析流程中移除。²³

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 自己的憑證儲存區，而非將權杖複製到 ~/.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：2種模式

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

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

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

依上游文件，驗證會按以下順序檢查：² 1. COPILOT_GITHUB_TOKEN 環境變數 2. GH_TOKEN 環境變數 3. GITHUB_TOKEN 環境變數 4. gh auth token CLI 後備方式 5. 透過 hermes model 使用 OAuth 裝置代碼登入

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

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

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

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

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

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

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

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

您可以使用 GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL 或 DASHSCOPE_BASE_URL 環境變數覆寫基礎 URL。²

Z.AI 會自動偵測端點。 使用 z.ai/GLM 供應商時，Hermes 會探測多個端點（全球、中國及程式開發版本），找出可接受您 API 金鑰的端點。可用端點會自動快取，因此多數使用者不必設定 GLM_BASE_URL。²

xAI (Grok) 會自動啟用提示快取。 當基礎 URL 包含 x.ai 時，Hermes 會在每個請求中傳送 x-grok-conv-id 標頭，讓同一對話工作階段的請求路由至相同伺服器，藉此重複使用已快取的系統提示與歷史記錄。² 此流程全自動，無須設定。

hermes auth 指令

hermes auth 是管理憑證集區與 OAuth 憑證的指令。⁶

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

憑證集區可為相同供應商輪替多個 API 金鑰或 OAuth 權杖，適合在不變更程式碼的情況下，將速率限制分散至多組金鑰。⁶ 舊版 hermes login / hermes logout 指令已移除；請改用 hermes auth。⁶

自訂與自行託管的端點

Hermes 可搭配任何與 OpenAI 相容的 API 端點使用。只要伺服器實作 /v1/chat/completions，即可讓 Hermes 指向該端點。²

互動式設定（建議）：

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

手動設定 config.yaml：

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

兩種方式都會永久儲存至 config.yaml；此檔案是主要模型、供應商及基礎 URL 的唯一真實來源。² 舊版環境變數 OPENAI_BASE_URL 與 LLM_MODEL 已不再用於讀取主要模型設定；請使用 hermes model，或直接編輯 config.yaml。²（OPENAI_BASE_URL + OPENAI_API_KEY 仍會作為輔助 provider: "main" 路由路徑的後備設定；若正在該處使用，切勿貿然刪除。）⁴

在工作階段中切換自訂端點：

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

/model custom（僅輸入此指令，不附模型名稱）會查詢端點的 /v1/models API；若恰好只載入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 長度很低（VRAM 低於24GB時為4,096個權杖）。您必須透過 OLLAMA_CONTEXT_LENGTH 或 Modelfile 提高限制；與 OpenAI 相容的 API 不接受用戶端傳入的 context 長度，因此 Hermes 無法代為設定。² 用於 agent 時，至少應設為16k–32k。

vLLM—高效能 GPU 服務：

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

工具呼叫必須使用 --enable-auto-tool-choice 與 --tool-call-parser <name>。支援的解析器包括：hermes（Qwen 2.5、Hermes 2/3）、llama3_json、mistral、deepseek_v3、deepseek_v31、xlam、pythonic。若未加入這些旗標，工具呼叫會以純文字傳回。²

SGLang—使用 RadixAttention 重複運用 KV 快取的高速服務：

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

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

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

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

工具呼叫必須使用 --jinja。 若未啟用，llama-server 會完全忽略 tools 參數，模型只能在回應文字中寫出 JSON 來嘗試呼叫工具；Hermes 無法將其解析為真正的工具呼叫。²

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

從 LM Studio 應用程式啟動伺服器（Developer 分頁 → Start Server），或透過 CLI 執行：lms server start（在連接埠1234上啟動）及 lms load qwen2.5-coder --context-length 32768。² 接著讓 hermes model 指向 http://localhost:1234/v1。

LM Studio 的關鍵陷阱： LM Studio 會從模型中繼資料讀取 context 長度，但許多 GGUF 模型回報的預設值是2048或4096。請務必在 LM Studio 的模型設定中明確指定 context 長度：按一下模型選擇器旁的齒輪圖示，將「Context Length」設為至少16384（最好是32768），再重新載入模型。²

具名自訂供應商

若您使用多個自訂端點（例如本機開發伺服器和遠端 GPU 伺服器），可在 config.yaml 中將其定義為具名自訂供應商：²

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

接著使用三段式語法，在工作階段中切換：

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

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

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

v0.13.0 提供 ProviderProfile ABC 及 plugins/model-providers/ 資料夾，讓第三方推論供應商無須修改核心即可直接加入。¹⁸ 若供應商採用與 OpenAI、Anthropic 或 Codex 相容的 API 模式，您可以實作 ProviderProfile 子類別，宣告驗證路徑、基礎 URL、模型目錄及快取標頭；Hermes 會透過內建供應商所使用的相同 runtime_provider.py 路徑進行解析。這正是 v0.13.0 供應商擴充背後的架構變革：新增供應商不必再編輯核心程式碼，只需發布外掛即可。

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

hermes proxy 會公開與 OpenAI 相容的本機端點，後端採用 Hermes 已登入的 OAuth 供應商，例如 Claude Pro、ChatGPT Pro、SuperGrok，或其他已設定且相容的供應商。¹⁹ 因此，包括 Codex CLI、Aider、Cline、Continue 或自訂指令碼在內，凡是預期使用 OpenAI 風格 API 的工具，都能重複使用 Hermes 以訂閱為基礎的驗證，無須另備 API 金鑰。請將此 proxy 視為本機開發基礎設施：審慎選擇繫結介面，切勿廣泛公開，並留意各供應商的特定條款。

Context 長度偵測

依據上游文件，以下2項設定經常遭到混淆：²

• context_length—context window 的總長度（輸入與輸出權杖預算合計，例如 Claude Opus 4.7 為1,000,000，Sonnet 4.6 為200,000）。Hermes 會據此判斷何時壓縮歷史記錄。
• model.max_tokens—輸出上限（模型單次回應最多可產生的權杖數）。與歷史記錄長度無關。

自動偵測的 window 大小有誤時，請設定 context_length：

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

Hermes 透過多來源解析鏈偵測 context window：設定覆寫 → 自訂供應商的個別模型設定 → 永久快取 → 端點 /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev（由社群維護、收錄超過3800個模型的登錄檔）→ 後備預設值（128K）。² 此系統能辨識供應商，因此同一模型可能因服務供應商不同而具有不同的 context 限制（例如 claude-opus-4.6 直接透過 Anthropic 使用時為1M，但在 GitHub Copilot 上僅有128K）。²

供應商輪替與後備機制

憑證集區。 若同一供應商有多個 API 金鑰，請透過 hermes auth 設定輪替策略。如此即可將速率限制分散至多組金鑰。⁶

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

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

後備機制會在工作階段中切換模型與供應商，同時保留對話內容。每個工作階段最多觸發1次。² 支援後備機制的供應商：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 使用輕量「輔助」模型處理周邊工作：影像分析、網頁摘要、瀏覽器螢幕截圖分析、危險指令核准分類、context 壓縮、工作階段搜尋摘要、skill 配對、MCP 工具分派及記憶體排清。⁴ 預設會透過自動偵測使用 Gemini Flash（OpenRouter → Nous → Codex）。

您可以設定每項輔助工作要使用的模型與供應商。 每個輔助插槽都使用相同的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" 供應商選項代表「使用主要 agent 所使用的供應商」；此選項僅能用於 auxiliary:、compression: 及 fallback_model: 設定，不能用於最上層的 model.provider 設定。若主要模型採用自訂且與 OpenAI 相容的端點，請在 model: 區段設定 provider: custom。⁴

這為何重要： 若只設定 Anthropic OAuth（沒有 OpenRouter 金鑰），視覺處理、網頁摘要及壓縮功能可能品質下降或直接失敗，因為預設輔助後備鏈會先嘗試 OpenRouter。請為輔助工作加入 OPENROUTER_API_KEY，或重新設定各輔助插槽以使用主要供應商：

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

這是 Hermes 新使用者最常遇到的「功能悄悄失效」陷阱。

設定系統

Hermes 採用分層設定系統。理解其優先順序至關重要，因為較高層級會覆寫較低層級；其中一層是您無法在 config.yaml 中看到的全域提供者登錄檔。

設定檔案配置

根據上游文件，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 金鑰、機器人權杖、密碼）→ .env - 其他所有項目（模型、終端機後端、壓縮設定、記憶體限制、toolsets）→ config.yaml

您可以在 config.yaml 中使用 shell 風格的插值語法參照機密資訊：⁴

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

管理設定

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config get KEY        # Print a single value (v0.19.0+)
hermes config unset KEY      # Remove a key so the default applies again (v0.19.0+)
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 update 後，都應執行 hermes config check 與 hermes config migrate——這些命令能找出新增但尚未納入您檔案的設定選項。⁶

設定優先順序

Hermes 會從數個來源載入設定。若多個來源設定了相同的值，則以優先順序較高者為準：⁴

1. CLI 引數——hermes chat --model anthropic/claude-sonnet-4（覆寫單次叫用的設定）
2. 環境變數——於程序啟動時套用
3. config.yaml——主要設定檔案
4. .env——僅用於機密資訊
5. 內建預設值——未由其他來源設定值時套用

CLI 旗標在該次叫用中一律具有最高優先權。config.yaml 則是長期採用的單一真實來源。

在地化（v0.13.0+）

v0.13.0 為 CLI 與 gateway 訊息新增了 7 種語系：簡體中文、日文、德文、西班牙文、法文、烏克蘭文及土耳其文。¹⁸v0.14.0 將所有 gateway 命令與網頁儀表板在地化，另增 8 種語系，使總數達到 16 種。¹⁹目前文件僅提供 zh-Hans 在地化版本。語系會根據 LC_ALL／LANG 環境變數，或 config.yaml 中明確指定的 locale: 鍵來決定。英文仍為預設語言，也是翻譯尚未涵蓋之字串的單一真實來源。

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

Profiles 可讓您建立多個彼此隔離的 Hermes 執行個體，每個執行個體都有各自的設定、工作階段、skills、記憶體與 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指令參考。⁶

全域選項

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更為強大，因為它支援同時依層級、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

日誌檔案位於~/.hermes/logs/：⁶ - agent.log——所有代理程式活動（API呼叫、工具分派、session生命週期、INFO以上層級） - errors.log——僅包含警告與錯誤（agent.log經篩選後的子集） - gateway.log——訊息gateway活動（平台連線、分派、webhook）

系統會透過Python的RotatingFileHandler自動輪替日誌——可查看agent.log.1、agent.log.2等檔案。⁶

hermes doctor——診斷

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

若要與他人分享診斷資訊，請使用hermes dump。它會產生精簡的純文字摘要，並遮蔽API金鑰，方便直接貼至GitHub議題或Discord討論串。⁶

Slash 指令

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

工作階段控制

設定與模型

/model 指令是工作階段進行期間切換 provider 的主力工具：⁹

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

v0.19.0 新增 /model --once，可暫時覆寫一輪所用的模型，並在回覆後自動恢復先前的模型。²³

工具、Skills 與資訊

動態 Skill Slash 指令

每個已安裝的 skill 都會自動公開為 Slash 指令：⁹

/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

自 v0.19.0 起，Slash skill 呼叫可以堆疊：/skill-a /skill-b do XYZ 能在單一輪次中依序載入兩個 skill，並為串連的名稱提供自動完成與預覽文字。²³

您也可以在 config.yaml 中定義快速指令，以簡短名稱作為較長 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）— 將目前聊天設為平台首頁
• /approve [session|always] — 核准待處理的危險指令
• /deny [reason] — 拒絕待處理的危險指令。自 v0.19.0 起，/deny <reason> 會將您的拒絕理由轉達給 agent，使其能調整方向，而非在毫無頭緒的情況下反覆嘗試²³
• /update — 將 Hermes Agent 更新至最新版本
• /commands [page] — 分頁瀏覽所有指令與 skill

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

Tools 與 Toolsets

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）、捨棄除 DAC_OVERRIDE、CHOWN 與 FOWNER 以外的所有 Linux capability、禁止權限提升、PID 限制（256 個程序）、完整的命名空間隔離，以及透過 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 工作者群能真正完成工作，不會因無效交接而停滯不前。

Kanban 看板可自然地搭配 /goal（鎖定目標的 Ralph 迴圈）處理目標端，並以現有的 delegate_task 工具處理生成語意。最終形成的工作者群模式，讓每個 Agent 都能共用唯一可信的資訊來源，清楚掌握接下來該做什麼、由誰執行，以及哪些工作陷入停滯。

skill 系統

skill 是代理程式可視需要載入的隨選知識文件。採用漸進式揭露模式，以盡量減少 token 用量，並相容於 agentskills.io 開放標準。¹¹

所有 skill 均位於 ~/.hermes/skills/——這是主要目錄，也是唯一可靠的資料來源。全新安裝時，內建 skill 會從儲存庫複製至此。透過 Hub 安裝及代理程式建立的 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)

只有在實際需要時，代理程式才會載入 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 即可使用，代理程式會改用 web_search，因此 DuckDuckGo skill 會保持隱藏。若未設定 API 金鑰，DuckDuckGo skill 便會自動顯示為備援方案。¹¹

代理程式管理的 skill

代理程式可透過 skill_manage 工具建立、更新及刪除自己的 skill。這就是代理程式的程序性記憶——當它摸索出一套不平凡的工作流程後，便會將方法儲存為 skill，以便日後重複使用。¹¹

代理程式建立 skill 的時機：¹¹ - 成功完成複雜任務（使用工具達 5 次以上）後 - 遇到錯誤或走入死胡同，並找到可行做法時 - 使用者修正其處理方式時 - 發現不平凡的工作流程時

動作：¹¹

Skill Hub

從線上登錄中心瀏覽、搜尋、安裝及管理 skill：⁶¹¹

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

整合的 Hub 來源：¹¹

預設 GitHub taps（無須設定即可瀏覽）：openai/skills、anthropics/skills、VoltAgent/awesome-agent-skills、garrytan/gstack。¹¹

安全性掃描

所有透過 Hub 安裝的 skill 都會經過安全性掃描，檢查資料外洩、提示詞注入、破壞性命令、供應鏈風險訊號及其他威脅。¹¹

信任層級：¹¹

對於社群 skill，--force 可覆寫非危險的政策封鎖，但無法覆寫掃描結果為 dangerous 的判定。¹¹

外部 skill 目錄

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

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

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

永久記憶

Hermes 具備容量有限且經過整理的記憶，可跨工作階段保留。代理程式的記憶由兩個檔案組成，皆儲存於~/.hermes/memories/：¹²

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

凍結快照模式：系統提示的注入內容只會在工作階段開始時擷取一次，且不會在工作階段進行期間變更。這是刻意設計，旨在保留LLM的前綴快取以提升效能。工作階段期間所做的變更會立即保存至磁碟，但要到下一個工作階段才會出現在系統提示中。¹²

應儲存的內容

儲存以下內容（代理程式會主動執行）：¹² - 使用者偏好：「相較於JavaScript，我偏好TypeScript」→ user - 環境資訊：「此伺服器執行Debian 12與PostgreSQL 16」→ memory - 修正事項：「執行Docker命令時不要使用sudo，使用者已加入docker群組」→ memory - 慣例：「專案使用Tab、每行上限120個字元，以及Google風格的docstring」→ memory - 已完成的工作：「已於2026年1月15日將資料庫從MySQL移轉至PostgreSQL」→ memory

略過以下內容：¹² - 瑣碎或顯而易見的資訊 - 容易重新查明的資訊 - 原始資料傾印（對記憶而言過於龐大） - 僅與當前工作階段相關的短暫資訊 - 情境檔案中已有的資訊

工作階段搜尋

除了MEMORY.md與USER.md，代理程式還能使用session_search工具搜尋過往對話。所有CLI與訊息工作階段皆儲存於SQLite（~/.hermes/state.db），並透過FTS5進行全文搜尋。查詢會傳回相關的過往對話，並由Gemini Flash產生摘要。¹²

外部記憶供應商

若需要比MEMORY.md與USER.md更深入的永久記憶，Hermes 隨附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)

一次只能啟用一個外部供應商。內建記憶則會永遠保持啟用。⁶

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

v0.13.0讓代理程式即使在執行途中遭到中斷，也能恢復運作。gateway會在重新啟動後自動續接中斷的工作階段；透過/update重新啟動時，升級過程仍會保留工作階段狀態；開發期間重新載入原始檔案時，也會維持目前工作階段，不再被迫建立新的工作階段。¹⁸實際效果是：長時間執行的gateway工作與cron驅動的作業，不再因程序重新啟動而重設context engine視窗。

Checkpoint v2（v0.13.0+）

v0.13.0將狀態持久化改寫為單一儲存區設計，具備真正的修剪機制、磁碟防護措施，且不會產生孤立的影子儲存庫。¹⁸舊版checkpoint系統會在長時間執行的profile中持續累積磁碟狀態；v2儲存區為本機checkpoint儲存空間設定明確上限，並移除導致空間不斷增長的重複簿記資料。使用者無須變更任何設定；下一次寫入checkpoint時便會採用v2路徑。

個性與SOUL.md

SOUL.md是Hermes實例的主要身分。它位於系統提示的第1個位置，取代硬式編碼的預設身分。¹³

Hermes會自動在~/.hermes/SOUL.md（自訂profile則位於$HERMES_HOME/SOUL.md）建立預設的SOUL.md。現有的使用者檔案絕不會遭到覆寫。Hermes只會從HERMES_HOME載入SOUL.md，不會在目前的工作目錄中尋找。如此一來，個性便能在不同專案間保持一致且可預期。¹³

SOUL.md應包含的內容

請用它設定長期適用的語氣與個性指引：¹³ - 語氣 - 溝通風格 - 直接程度 - 預設互動風格 - 應避免的文風 - Hermes應如何處理不確定性、意見分歧與模糊情況

以下內容則應少用：¹³ - 一次性的專案指示 - 檔案路徑 - repo慣例 - 暫時性的工作流程細節

這些內容應放在AGENTS.md，而非SOUL.md。

SOUL.md與AGENTS.md的差異

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

SOUL.md——身分、語氣、風格、預設溝通方式，以及個性層級的行為。

AGENTS.md——專案架構、程式設計慣例、工具偏好、repo專屬工作流程、命令、通訊埠、路徑及部署備註。

有個實用原則：若某項設定應隨時隨地跟著您，就應放在SOUL.md；若只屬於特定專案，則應放在AGENTS.md。¹³

內建個性

Hermes隨附多種內建個性，可使用/personality切換：¹³

config.yaml中的自訂個性：¹³

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

接著使用/personality codereviewer切換。

SOUL.md與/personality的差異

SOUL.md是基準語氣，/personality則是工作階段層級的疊加設定。¹³建議在SOUL.md中維持務實的預設值，再於教學對話中使用/personality teacher，或在腦力激盪時使用/personality creative。

Nous Tool Gateway（v0.10.0+）

自Hermes Agent v0.10.0（2026年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 auth中設定的Portal OAuth憑證，自動偵測訂閱狀態，無須另行登入。自v0.19.0起，您也能直接在工作階段中管理訂閱：/subscription會顯示方案與剩餘額度、準確預覽升級費用或降級生效時間，並套用變更，同時顯示排程變更橫幅並提供復原功能；/topup則可加購額度。桌面應用程式也提供對應的帳務設定分頁。²³

定價與存取權限

定價與方案名稱公布於Nous Portal定價頁面（https://portal.nousresearch.com/pricing）。本指南不逐一列出方案，因為這些方案由Portal產品負責，而非Hermes CLI，且其變更不依附於Hermes版本。請前往https://portal.nousresearch.com/註冊，並在定價頁面查看目前方案。

棄用通知

• HERMES_ENABLE_NOUS_MANAGED_TOOLS環境變數已於v0.10.0中移除。代管工具現在透過各工具的use_gateway設定欄位啟用，並依您的Portal訂閱狀態決定是否開放。²⁸

釐清：此版本並非如此

Hermes Agent CLI並未受訂閱限制。此專案仍採用MIT授權；所有核心功能（CLI、skills、記憶、messaging gateway、cron、MCP、本機儀表板，以及所有供應商的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介接器。^327171819 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外掛掛鉤。¹⁸ v0.14.0新增LINE與SimpleX Chat，並完成Microsoft Teams的端對端技術堆疊，包括Graph驗證、webhook監聽器、管線執行階段與對外傳送功能。¹⁹ v0.17.0（2026年6月19日）新增透過Photon Spectrum且無須中繼的iMessage支援（使用hermes photon login進行裝置代碼OAuth，不再需要Mac／BlueBubbles中繼）、官方WhatsApp Business Cloud API介接器（取代原有的橋接程序需求）、SimpleX群組與原生附件支援，並將Raft納入內建平台外掛。²¹

設定

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權杖、bot ID、頻道對應與允許清單。⁶

訊息流程

根據上游架構文件：³

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

每個通訊平台都使用與CLI相同的AIAgent對話迴圈。因此，斜線指令在兩者中的運作方式完全一致，而在Telegram中排程的cron工作，也能將輸出傳送至Discord。平台之間的差異只存在於邊緣層。³

v0.19.0新增以profile為基礎的訊息路由與持久化傳送機制。共用單一bot權杖的多工gateway，可將特定guild、頻道或討論串路由至不同profile；每個profile的設定、skills、記憶與密鑰皆完全隔離，並可透過GATEWAY_MULTIPLEX_PROFILES覆寫。經過一系列強化後，單一profile設定錯誤也不會再拖垮整個gateway。底層路由索引已移至state.db（sessions.json如今僅為選用的舊版鏡像），最終回應則會在平台傳送前後，記錄至持久化的傳送責任帳本。若完成的回答因gateway當機而未能送出，系統會在下次啟動時重新傳送，而不會無聲遺失。²³

使用者授權與配對

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任務，而非shell指令。每個排程工作都會使用設定的提示、可選的附加skills，透過全新的AIAgent執行，並將結果傳送至任何平台：³⁶

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：⁶

作為用戶端——將Hermes連接至外部MCP伺服器，以擴充其工具範圍：

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

或在config.yaml中手動設定：¹⁴

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

自v0.19.0起，MCP工具會依照mcp__server__tool命名慣例提供給模型。每個工具名稱都會包含其伺服器名稱，因此兩部伺服器即使提供同名工具，也不會再發生衝突；MCP伺服器的日誌通知也會顯示於agent.log。²³

作為伺服器——將Hermes對話開放給其他agent：

hermes mcp serve
hermes mcp serve -v    # Verbose

Context 壓縮

Hermes 會自動壓縮過長的對話，使其維持在模型的 Context Window 範圍內。壓縮摘要器會另外呼叫一次 LLM，您可以將其指向任何提供者或端點。⁴

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

提供者選項：⁴

summary_model 支援的 Context Length 必須至少與主要模型相同，因為它會接收對話中間的完整內容進行壓縮。⁴

預算壓力警告

當 agent 執行包含大量工具呼叫的複雜任務時，可能會在不知不覺間耗盡迭代預算（預設：90 輪）。預算壓力機制會自動警告模型：⁴

串流逾時

LLM 串流連線設有兩層逾時機制，並會針對本機提供者（localhost、區域網路 IP）自動調整：⁴

本機端點的 Socket 讀取逾時會提高至 30 分鐘，因為本機 LLM 在處理大型 Context 時，可能需要數分鐘才能完成預填並產生第一個 Token。⁴

本機 Web 儀表板（v0.9.0+）

這是一套透過瀏覽器操作的儀表板，可在本機管理 Hermes Agent。無須接觸設定檔或終端機，即可調整設定、監控工作階段、瀏覽 skills，以及管理 gateway。¹⁶請使用 hermes dashboard 啟動。對於偏好 GUI 的新使用者而言，這是最容易上手的途徑。

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

watch_patterns 可讓您設定要在背景程序輸出中監控的模式，並於符合條件時即時收到通知。¹⁶無須輪詢，即可監控錯誤、等待特定事件（「listening on port」），或查看建置記錄。搭配 v0.8.0 推出的 notify_on_complete（會在背景任務完成時發出通知），Hermes 如今已具備完整的背景程序可觀測性層。¹⁵

可插拔式 Context Engine（v0.9.0+）

現在可透過 hermes plugins 將 Context 管理作為可插拔的插槽。您可以換用自訂 context engine，控制 agent 在每一輪看到的內容，包括篩選、摘要或注入特定領域的 Context。¹⁶這使 Context 策略與 agent 核心迴圈彼此解耦，從而能依專案或領域自訂 Context。

備份與還原（v0.9.0+）

hermes backup 會建立完整封存檔，其中包含設定、工作階段、skills 與記憶。hermes import 則可從備份封存檔還原。¹⁶您可以利用這項功能在不同機器間移轉、於重大變更前建立快照，或與團隊成員分享經過驗證的設定。

Termux / Android 支援（v0.9.0+）

Hermes 可透過 Termux 在 Android 上原生執行。經過調整的安裝路徑、針對行動裝置螢幕最佳化的 TUI、語音後端支援，以及 /image 指令，皆可直接在裝置上運作。¹⁶

安全性強化（v0.13.0+）

v0.13.0 修正了 8 項 P0 安全性問題，並調整一項預設值，使其更有利於使用者。¹⁸隨後推出的 v0.14.0 又修正了 12 項 P0 與 50 項 P1 問題，包括防範 sudo 暴力破解與強化 sudo-stdin、修正危險指令繞過漏洞、在將工具錯誤重新注入模型前進行清理、儀表板外掛 API 驗證、補強 skills-hub 的 SSRF 防護範圍，以及在安裝期間掃描供應鏈安全公告。¹⁹

若您負責維護 Hermes 部署環境，應將 v0.13.0 與 v0.14.0 視為攸關安全性的升級，而非單純的功能更新。v0.13.0 修正了 Discord 跨 guild 繞過漏洞與兩個 TOCTOU 時窗；v0.14.0 則進一步強化 sudo 處理、工具錯誤重新注入、外掛 APIs、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 個工具／20 個 toolset」與「28 個工具」有何差異？「47 個工具」是上游儲存庫完整工具登錄表的總數，也就是 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 重新建置工具資訊清單）。

3 種 API 模式

Hermes 將不同提供者之間的差異抽象化為 3 種 API 模式，並在執行階段自動選用：³

runtime_provider.py 解析器會為 18 個以上的提供者，將 (provider, model) 元組對應至 (api_mode, api_key, base_url)，同時處理 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 全文搜尋。工作階段具備譜系追蹤功能（記錄壓縮前後的父子關係）、各平台相互隔離，以及包含競爭狀況處理的不可分割寫入機制。³

外掛系統

共有 3 個探索來源：~/.hermes/plugins/（使用者）、.hermes/plugins/（專案）及 pip 進入點。外掛透過情境 API 登錄工具、掛鉤與 CLI 命令。記憶提供者是位於 plugins/memory/ 下的特殊外掛類型。³

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

設計原則

出自上游架構頁面：³

從 OpenClaw 移轉

Hermes Agent 是 OpenClaw 的後繼產品。若要從現有的 OpenClaw 安裝環境移轉：⁶⁵

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

hermes claw migrate 預設會從 ~/.openclaw 讀取資料（也會自動偵測舊版 ~/.clawdbot 與 ~/.moldbot 目錄），並寫入 ~/.hermes。⁶

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

封存以供手動檢閱：cron 工作、外掛、掛鉤／webhook、記憶後端（QMD）、skills 登錄設定、UI／身分、記錄、多 agent 設定、頻道繫結、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API 金鑰會依下列優先順序檢查 3 個來源：設定值 → ~/.openclaw/.env → auth-profiles.json。⁶

疑難排解

「尚未設定推論供應商。請執行 ‘hermes model’ 選擇供應商與模型」

每次全新安裝最先遇到的錯誤：Hermes 尚未解析出可用的供應商。這正如訊息所示——3 種驗證路徑均未產生可用的供應商。請執行：

hermes model

互動式選擇器會引導您完成所有支援的供應商設定，包括 OAuth 裝置代碼流程（Nous Portal、GitHub Copilot、Anthropic、OpenAI Codex），以及自架伺服器的自訂端點。若您原本預期供應商已設定完成，hermes doctor 會顯示 Hermes 實際可存取哪些憑證。常見原因包括：API 金鑰設在錯誤的位置（應放在 .env 中或透過 hermes config set 設定，而非放在 shell profile）、~/.hermes/auth.json 中的 OAuth 憑證已過期，或 config.yaml 的自訂端點遺失了 base_url。如需深入瞭解驗證路徑，請參閱驗證與供應商。²⁷

「未設定 API 金鑰」

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

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

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

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

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

您的伺服器未啟用工具呼叫，或該模型無法透過伺服器的實作方式支援此功能。²

回應在句子中途遭到截斷

可能有以下 2 種原因：²

1. 伺服器上的輸出上限過低（max_tokens）——SGLang 預設每次回應為 128 個 token。請在伺服器上設定 --default-max-tokens，或在 config.yaml 中設定 model.max_tokens。
2. Context 耗盡——模型已填滿 context window。請提高 model.context_length，或在 Hermes 中啟用 context 壓縮。

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

WSL2 使用具有獨立子網路的虛擬網路介面卡——WSL2 內的 localhost 指向 Linux VM，而非 Windows 主機。有 2 種解決方式：²

鏡像網路（Windows 11 22H2 以上版本）：編輯 %USERPROFILE%\.wslconfig：

[wsl2]
networkingMode=mirrored

接著執行 wsl --shutdown 並重新啟動。現在 localhost 可進行雙向連線。

主機 IP 備援方式（舊版 Windows）：從 WSL2 內取得 Windows 主機 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 推出的開放原始碼 agent 框架，可搭配任何與 OpenAI 相容的供應商——包括 Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google，或您自行架設的端點。¹² Hermes 還內建 Telegram／Discord／Slack／WhatsApp／Signal 的訊息 gateway，而 Claude Code 並未提供此功能。

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

可以，共有 3 種方式：²

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。對話記錄、memory 與 skills 都會完整保留：⁹

/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 以處理輔助工作，或重新設定輔助 slot，讓其使用主要供應商。請注意，context 壓縮位於獨立的頂層 compression: 區塊，並使用 summary_provider，而不是 auxiliary.compression.provider——auxiliary.compression slot 僅提供 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 執行個體？

使用 profiles。每個 profile 都有各自的 HERMES_HOME、設定、memory、工作階段與 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 支援本機 LLM 嗎？

支援，可透過自訂端點路徑使用。Hermes 可搭配任何與 OpenAI 相容的伺服器，包括 Ollama、vLLM、SGLang、llama.cpp／llama-server、LM Studio、LocalAI、Jan，或您自行架設的伺服器。² 各伺服器的設定方式，請參閱自訂與自行架設的端點。

為什麼啟動橫幅顯示的工具數量少於指南所述？

本指南引用上游架構登錄中的 47 項工具／20 個 toolsets——這是 Hermes 在所有 toolset 中提供原始程式碼的完整工具數量。您執行中的安裝版本會在橫幅顯示較少的數量（本指南使用的參考安裝環境顯示 28 項工具），因為 Hermes 啟動時只會啟用預設的 toolset 組合。許多 toolsets 必須自行啟用：訊息 gateway 介接器、瀏覽器自動化、較大型的擷取技術堆疊，以及數種專用整合，都必須明確列在 ~/.hermes/config.yaml 的 toolsets: 下方才會載入。登錄總數＝「啟用後可使用的項目」；橫幅總數＝「目前 profile 實際載入的項目」。請使用 hermes tools --list 查看哪些 toolsets 已啟用，以及哪些可用但尚未啟用。執行時可使用 /tools enable <name> 和 /tools disable <name> 切換個別 toolsets（停用時會重設工作階段，讓 agent 依照新的工具組成重建工具資訊清單）。

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

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

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

主要供應商發生失敗時（速率限制、伺服器錯誤或驗證失敗），Hermes 會在工作階段進行期間切換至備援模型，且不會遺失對話記錄。每個工作階段最多觸發 1 次。

Agent 能否隨時間推移改善自己的 skills？

可以——這正是 Hermes Agent「自我改進」的核心。Agent 可透過 skill_manage 工具建立、更新及刪除 skills。當它掌握一套不簡單的工作流程後，便會將方法儲存為 skill，供日後重複使用。¹¹ Agent 會在完成複雜工作（呼叫工具 5 次以上）、遇到錯誤並找到可行做法、您修正其處理方式，或發現不簡單的工作流程後建立 skills。

是否提供 IDE 整合？

有——Hermes 可作為 ACP（Agent Client Protocol）伺服器執行，供 VS Code、Zed 與 JetBrains 使用：⁶

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

變更日誌

參考資料