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

重點摘要：Hermes Agent是Nous Research推出的開源自我改進AI agent。它可作為CLI與多平台訊息gateway運作，會將持久身分與長期記憶儲存在磁碟上，彙整會隨使用而改進的skills，並可搭配任何與OpenAI相容的LLMprovider——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新增搭配grok-4.3 1M context的SuperGrok OAuth、適用於OAuthproviders的OpenAI相容本機proxy（hermes proxy）、原生x_search、PyPI安裝支援（自v0.19.0起已淘汰——單行安裝程式才是支援路徑）、延遲安裝相依項目、涵蓋LINE與SimpleX Chat的28個訊息平台、/handoff、寫入後的LSP語意診斷、統一的video_generate、透過cua-driver為非Anthropicproviders提供的computer_use、原生Windows beta，以及12項P0／50項P1的結案。¹⁹對多數新使用者而言，最困難的部分是provider驗證：Hermes支援約20個一級provider及自訂endpoint，並提供3種不同的驗證路徑（.env中的API key、透過hermes model使用的OAuth，或config.yaml中的自訂endpoint）。驗證模型是最該優先掌握的事——其餘一切都取決於解析出哪個provider。

Hermes Agent是完整的agent runtime，不是聊天包裝器。它會讀取您的檔案系統、在沙箱化backend中執行命令、擷取網頁、建立subagent、執行排程cron工作，並透過單一gateway程序與Telegram／Discord／Slack／WhatsApp／Signal／Email互動，也會根據經驗建立自己的skills。¹CLI是在run_agent.py對話迴圈之上建構的終端UI；gateway則是長時間執行的程序，會透過相同的對話迴圈路由來自訊息平台的訊息。³

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

1. Provider解析：驗證流程如何對應至API呼叫
2. 設定階層：config.yaml+.env+auth.json+SOUL.md+AGENTS.md
3. Tool+toolset系統：agent能做什麼，以及各平台的存取限制
4. Skills系統：agent建立並持續演進的程序性記憶
5. Gateway+cron+profiles：讓Hermes在您生活所在之處運作，而不只是在您當下所在之處

重點整理

• Provider驗證有3條路徑，不是一條。.env中的API key、透過hermes model／hermes auth使用的OAuth，或config.yaml中的自訂endpoint。請選擇符合provider的路徑，而不是選擇看起來熟悉的方式。
• 切換provider只需一個命令。hermes model會以互動方式引導您完成所有支援provider的設定，包括OAuth登入；而/model provider:model可在不遺失歷程的情況下於session中途切換。²
• 有2個檔案是使用者可編輯的設定介面。~/.hermes/config.yaml儲存設定，~/.hermes/.env儲存機密資料。auth.json、SOUL.md、MEMORY.md與skills/由Hermes直接管理——您可以手動編輯SOUL.md，但其餘項目會由agent自行處理。⁴
• Hermes是OpenClaw的後繼者。若要遷移，hermes claw migrate會自動匯入30多類狀態。⁵
• 服務品質取決於您的輔助model。視覺、網頁摘要、壓縮與記憶體flush都使用另一個輔助LLM。預設會透過自動偵測使用Gemini Flash（OpenRouter→Nous→Codex）——若這些都未設定，在您將輔助slot指向主要provider之前，這些功能會悄然降級。⁴

v0.14的變更

v0.14.0與其說是推出單一主打功能，不如說是減少設定阻力，同時擴大Hermes可運作的範圍。¹⁹主要的操作變更如下：

• 安裝與啟動更輕量。pip install hermes-agent可透過PyPI運作，重量級adapter會在首次使用時延遲安裝，且啟動路徑延後足夠多的工作，使冷啟動時間縮短約19秒。（v0.19.0之後已淘汰pip安裝——請參閱安裝。）
• 訂閱可成為本機APIendpoint。hermes proxy可將由OAuth支援的provider，例如Claude Pro、ChatGPT Pro與SuperGrok，轉換為與OpenAI相容的本機endpoint，供Codex、Aider、Cline與Continue等工具使用。
• Gateway涵蓋範圍擴大。LINE與SimpleX Chat使平台總數達到22個，Microsoft Teams已完成端對端串接，Discord歷程回填預設啟用，Telegram／Discord的clarify提示現在使用原生按鈕。
• 寫入時驗證有所提升。編輯後，Hermes可在下一輪之前顯示每輪檔案異動摘要與language server語意診斷，使其更接近以證據為導向的agent工作模式。
• 桌面與媒體工具更為完善。非Anthropicproviders可透過cua-driver使用computer_use，video_generate統一置於可插拔backend之後，而vision_analyze會將原始像素傳送至真正具備視覺能力的model。

以下每個章節皆以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 解析執行階段供應商——此步驟會選定驗證方式、基礎 URL 與 API 模式³
3. 使用下列3種 API 模式之一呼叫供應商：chat_completions、codex_responses 或 anthropic_messages³
4. 透過 model_tools.py 與中央工具登錄檔（tools/registry.py），分派傳回的所有工具呼叫³
5. 持續迴圈，直到模型產生最終回應，接著將工作階段儲存至支援 FTS5 的 SQLite³

理解此迴圈至關重要，因為所有功能——個性、記憶、skills、壓縮、備援——都附掛於其中某個階段。閱讀某個設定鍵並思索其作用時，答案通常是：「它是用來調整上述迴圈第1、2、3或4階段的旋鈕。」

與平台無關的核心。單一 AIAgent 類別可供 CLI、gateway、ACP、批次作業及 API 伺服器使用。平台差異存在於進入點，而非代理本身。³因此，相同的斜線命令能同時在終端機與 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.20.0（The Herald Release）有何新功能

Hermes Agent v0.20.0（標籤 v2026.8.3，2026年8月3日）是目前的功能版本；v0.20.1（8月13日）與 v0.20.2（8月16日）是在其基礎上的穩定化標籤，而 v0.20.3（標籤 v2026.8.16.2，8月17日發布）與 v0.20.4（標籤 v2026.8.18，8月18日）則延續彙整發布節奏，各自也包含功能更新——請參閱下方小節。自 v0.19.0 以來，此更新區間涵蓋約3,650次提交、1,400個合併的 PR，以及由650多位貢獻者結案的1,200個議題。²⁴

其中3項變更推翻了本指南舊版提供的操作方式。請優先閱讀以下內容：

• 目前必須使用 Node 26。安裝程式固定採用 NODE_VERSION="26"，並會拒絕較舊的執行階段，顯示「Node.js … is too old (Hermes requires Node >=26)」。安裝程式、heal 與 upgrade 均會強制執行此要求。請注意，文件網站的安裝頁面仍標示 Node v22——安裝指令碼與版本資訊較新，應以兩者為準。²⁴
• pip 與 Homebrew 已停止支援，而不只是棄用。原文為：「brew + pip/PyPI wheel channels retired (shell installer / Docker / Nix are the supported channels).」若仍使用 pip 或 brew 安裝，該管道已不再提供新版本。²⁴
• 預設工具呼叫迭代上限已從90次提高至500次。長時間自主執行不會再撞上人為限制，下文所有預算壓力門檻也會依據新上限計算。read_file 的預設值亦從500行提高至2,000行。²⁴

此版本的其他內容如下：

• 對話式語音。支援可插話打斷的串流 TTS，以及裝置端喚醒詞。²⁴
• A2A v1.0。新增代理對代理通訊協定外掛，完成議題 #514 中長期懸而未決的需求。²⁴
• 已簽署的對外 Webhook。hermes webhook 過去僅支援傳入；v0.20.0 新增以 HMAC 簽署的對外生命週期 Webhook，涵蓋工作階段、對話輪次與工具事件。²⁴
• 有依據的引用。新增具備事實查核模式的 skill。²⁴
• 進階使用者 CLI 功能浪潮。!command 可立即執行 shell 命令，無須耗用模型對話輪次；/init 會掃描專案，並寫入或更新 AGENTS.md；/diff 可從任何介面顯示已暫存、全部或工作階段中的變更；/context 會分析內容視窗的占用情形；/focus 提供精簡輸出檢視，並可還原隱藏行；Ctrl+S 可暫存尚未寫完的提示詞。hermes import-agent 能以單一命令移轉 Claude Code 或 Codex CLI 設定。²⁴
• 新增機密資料相關功能。新增可與各種保存庫搭配的命令輔助程式機密來源、附有可採取行動之啟動錯誤的一鍵權杖輪替、可選用的 Bitwarden 加密緊急存取快取、依各 profile 主目錄限定範圍的保存庫注入金鑰，以及 config.yaml 與 MCP 設定之間的 ${env:VAR} SecretRef 一致性。下文所述的3路徑驗證模型維持不變。²⁴
• 加快暖啟動。hermes -w 的冷啟動時間從約14秒降至1.8秒。²⁴
• 桌面版正式成為平台。新增具備版本卡片與沙箱化即時預覽的成品、以 Kanban 作為首個桌面外掛的 Plugin SDK、快速輸入全域快速鍵、多個 GUI 視窗、SSH 遠端後端模式，以及 RFC 8252 原生登入。²⁴

v0.20.3 與 v0.20.4 彙整版本（8月17日至18日）

v0.20.0 之後，專案採取高頻率的標籤彙整發布節奏，而最新兩個版本不僅止於穩定化。兩者均聲明：「full curated release notes for this window will ship with v0.21.0」——因此，以下摘要取自各版本本身的更新區間說明，而非經過編整的功能清單。²³

v0.20.3（自 v0.20.2 起約250次提交、約125個 PR）：

• MCP 2.x SDK 移轉，並支援2026年7月28日的無狀態通訊協定。Hermes 遷移至目前的 MCP SDK 世代，並採用該通訊協定的無狀態修訂版。²³
• Bot Mode 以內建外掛形式推出（hermes-bots），其中包含核心隊友通訊協定。²³
• 新增 CommandCode 供應商外掛，納入供應商目錄。²³
• 用於電腦操作的 Cua Driver 0.20 執行階段合約，以及強化子程序 Python 執行階段的所有權管理（隔離 PYTHONHOME/PYTHONPATH）。²³
• 可靠性：cron 排程器自我修復（EMFILE 復原、過期宣告協調、卡住工作重新啟用）、修正工作階段交接的資料遺失問題、桌面版遠端 gateway 連線自我修復，以及一系列生態系功能移植（外掛安裝安全掃描、/worktree、/rollback 保留手動編輯內容、讀取 UTF-16 檔案）。²³

v0.20.4（自 v0.20.3 起約146次提交、約74個 PR）：

• 桌面版的玻璃介面：新增霧面玻璃與半透明效果、霧化選擇器，以及 macOS 預先選取功能。²³
• 分頁式 SESSIONS|BOTS 側邊欄，可逐一隱藏或取消隱藏 Bot；另修正 Bot Mode 群組聊天問題（長時間執行的成員對話輪次、Markdown 呈現、跨機器路由）。²³
• 安裝 skill 時採用 NVIDIA SkillEvaluator Tier 1 諮詢式掃描——安裝 skill 時會執行授權條款與安全性檢查。²³
• 強化 cron 媒體傳送功能（可設定逾時、手動執行附件、顯示錯過的觸發）、修正 SessionDB 事件迴圈執行緒與競爭問題、讓 hermes update 如實呈現擱置分支狀態，以及新增 Kanban 原生作業系統通知。²³

更新方式維持不變：現有安裝可執行 hermes update，全新安裝則使用 shell 安裝程式。²³

v0.19.0新增內容（Quicksilver版本）

Hermes Agent v0.19.0（標籤v2026.7.20，2026年7月20日）以信使之神般的速度命名：本次版本的核心是極致的即時反應能力，所有平台首輪首次輸出 token 的時間縮短約80%。圍繞此核心，還加入終端計費、密碼管理工具祕密來源、預設智慧核准、可觀察的子代理，以及防止當機遺失回應的傳遞機制。自v0.18.0以來，這是專案規模最大的一段開發週期：大約2,245次提交、約1,065個合併的PR、約3,300個已關閉議題，以及450多位社群貢獻者。²⁵

• 首次輸出 token全面加速約80%。從冷啟動提交到派送的時間，無論是CLI、gateway、TUI、桌面版或cron，皆從約4.3秒降至約0.9秒——Discord能力偵測已移出關鍵路徑、已知非Ollama供應商會略過Ollama探測，並移除了代理初始化中的阻塞性工作。感知延遲也獲得改善：推理模型現在預設會即時串流其思考過程（display.show_reasoning為ON），回應框則改為逐token繪製，而非逐行繪製。²⁵
• 桌面版與TUI渲染效能提升。桌面應用程式歷經約20個PR的速度改造：透過增量區塊詞法分析，串流Markdown分割器的CPU用量減少14倍；檢閱窗格的diff改為虛擬化；大型逐字稿可快速切換工作階段；側邊欄與工具列不再每個token都重新渲染。TUI現在也會逐區塊增量渲染串流Markdown。²⁵
• pip與Homebrew安裝方式已棄用。兩種途徑均被標示為「不支援的舊版」安裝方式，並規劃移除。該移除作業已於v0.20.0完成——brew及pip/PyPI wheel管道均已退役，目前支援的管道為shell安裝程式、Docker及Nix。²⁵²⁴
• 祕密資料可來自密碼管理工具。新的可插拔SecretSource介面會在載入時，從Bitwarden與1Password（op://參照）擷取祕密資料；可同時啟用多個保險庫，並提供確定性的優先順序、衝突警告與每個變數的來源追蹤——API金鑰不必再存放於純文字.env。未來的保險庫供應商可透過外掛隨插即用。²⁵
• 智慧核准現為預設選項。當Hermes要執行被標記的指令時，獨立的LLM審查器會進行評估，而不是每次都要求您確認——每項判定僅涵蓋該確切指令。使用者定義的拒絕規則即使在YOLO模式下也會封鎖相符指令；/deny <reason>會傳達您的拒絕理由，使代理修正方向；外掛的pre_tool_call核准動作（已重新導入並加入規則金鑰）會將工具呼叫升級為人工審核關卡。²⁵
• 終端計費：/subscription與/topup。無須離開終端，即可管理Nous Portal方案——查看方案與剩餘額度、精確預覽升級費用或降級何時生效，並可套用後復原。桌面應用程式也新增對應的計費設定分頁。²⁵
• 觀察子代理工作；不再遺失已完成的答案。delegate_task派送會在子代理啟動後立即回傳可用tail -f追蹤的即時逐字稿檔案——每個子代理都有一份人類可讀的日誌，記錄所有工具呼叫、結果與串流回覆。背景委派完成狀態可跨重新啟動保留；最終gateway回應會寫入state.db的傳遞義務帳本，若gateway在傳送途中終止，會於下次啟動時重新傳遞。max_async_children設定選項已棄用，改用統一的委派並行上限。²⁵
• 一個gateway，多個profile。單一多工gateway可共用一個bot token，並將特定guild、channel或thread路由至不同profile——各profile的設定、skill、記憶與祕密資料皆完全隔離——並可透過GATEWAY_MULTIPLEX_PROFILES覆寫。路由索引已移至state.db；sessions.json現在是可選的舊版鏡像。²⁵
• 供應商與模型更新。Fireworks AI正式成為一級支援項目（可估算成本，並在供應商選擇器中位居第2），同時加入DeepInfra與Upstage Solar。模型目錄新增GPT-5.6（Sol/Terra/Luna與Pro，已端對端串接）、grok-4.5（GA）、kimi-k3（kimi-k2.x已退役），以及完整串接的Claude Sonnet 5。每個供應商可使用enabled: false旗標，並透過excluded_providers設定，從/model選擇器與解析流程移除未使用的供應商。²⁵
• 推理強度成為可調整的旋鈕。所有介面皆新增max與ultra強度層級，支援在設定中覆寫個別模型；MoA預設集可為每個slot設定強度（顧問深入思考，綜合器維持快速）；輔助模型可設定每項任務的強度；CLI則提供工作階段範圍的/reasoning。²⁵
• CLI與MCP介面更新。hermes sessions export可輸出Markdown、Quarto、HTML、僅提示詞及Hugging Face trace格式，並可選用--redact清理；/model --once提供單輪模型覆寫；slash-skill呼叫可堆疊（/skill-a /skill-b do XYZ）；--safe-mode有助於疑難排解；hermes config get/unset補足設定管理；hermes serve成為真正的無頭後端；MCP工具則採用mcp__server__tool命名慣例。²⁵

若您正從v0.18.x升級，有兩項變更應優先留意：pip或Homebrew安裝現在會警告為不支援的舊版方式（請遷移至單行安裝程式），而max_async_children已棄用，改用統一的委派並行上限。其餘皆為增量功能——升級的主要理由是首輪延遲縮短約80%、智慧核准，以及讓已完成答案不怕當機遺失的傳遞帳本。

v0.18.0新增內容（Judgment版本）

Hermes Agent v0.18.0（標籤v2026.7.1，2026年7月1日）以判斷力命名：代理會驗證自己的工作，而非直接宣稱成功；您也能實際檢視集成推理。此版本也清除了整個P0/P1待辦清單——約692個最高優先順序項目在12天內完成解決。²²

• Mixture-of-Agents成為一級模型。現在可如同其他模型般，在所有介面選擇MoA，且集成推理過程清晰可見：每個參考模型的完整輸出都會以獨立標示區塊呈現，並即時串流答案——您可以觀察集成如何思考，而非只收到不透明的合併結果。²²
• /goal的完成契約。代理會在回報目標完成前執行專案檢查來驗證自己的工作，而非直接宣稱成功——將判斷力用於自身。²²
• /learn——將任何描述轉為skill。只要描述工作流程，即可將其轉成可重複使用的skill；產生的skill會自動遵循儲存庫CONTRIBUTING.md慣例。²²
• /journey時間軸。以視覺化方式呈現記憶與skill隨時間的歷程，並支援編輯；桌面版另有記憶圖表。²²
• 背景子代理扇出。可委派多項工作並行執行，不會阻塞對話——v0.17.0原本單一背景子代理如今擴展為一支團隊。²²
• 桌面版Projects。提供一級支援的程式設計Projects，採用project/repo/lane組織模型。²²
• 可縮減至零的gateway。gateway閒置時可進入休眠，並協調drain流程以實現無縫部署——對將Hermes作為常駐服務執行的人尤其重要。²²
• Google Vertex AI支援。透過GCP服務帳戶存取Gemini，並自動重新整理OAuth2 token，現已加入供應商目錄。²²
• /prompt編輯器指令。開啟$EDITOR以撰寫多行提示詞，不必再與輸入列周旋。²²

若您正從v0.17.x升級，這裡沒有任何變更會破壞CLI。升級的主要理由是完成契約（會自行驗證的目標）、可檢視集成的一級MoA，以及用於擷取skill的/learn。

v0.17.0 的新功能（Reach Release）

Hermes Agent v0.17.0（標籤 v2026.6.19，2026年6月19日）以代理現在能觸及的廣度命名——新增訊息頻道、模型提供者，以及更深入的桌面版與儀表板控制。此版本是在 v0.16.x 之上擴充；CLI 介面維持不變。²¹

• 新增訊息頻道。iMessage 現在可透過 Photon Spectrum（裝置碼 OAuth、hermes photon login）不經 Mac 中繼器運作；WhatsApp Business Cloud API 是官方 Meta 介接器，取代原本需要橋接程序的做法；SimpleX 支援群組、原生附件、文字批次處理與自動接受；Raft 則以內建平台外掛加入，採用以隱私契約為核心的喚醒頻道設計。²¹
• 新增模型與提供者。目錄新增 z-ai/glm-5.2（1M context）、anthropic/claude-fable-5、laguna-m.1、nemotron-3-ultra 與 grok-composer-2.5-fast（Cursor 透過 xAI OAuth 提供的模型，200k context）。xAI 預設值改為 grok-build-0.1，而 Anthropic 自適應模型現在遵循現代思考契約（絕不傳送 reasoning 欄位）。²¹
• 桌面版與儀表板。桌面版新增具即時「watch-windows」串流委派活動的背景子代理（delegate_task(background=true)）、Composer 模型選擇器、可重新綁定的鍵盤快速鍵、原生 OS 通知、每個討論串的 Composer 草稿、VS Code Marketplace 主題，以及日文與繁體中文 UI。儀表板新增完整的 profile 建立器（無須編輯 config.yaml 即可設定模型、skill 與 MCP），全域 profile 切換器，以及重新打造、含安全掃描功能的 Skills Hub、Automation Blueprints（可在表單、斜線指令、對話與文件間使用的參數化範本），並提供可在 OAuth 閘門後正確回傳 401 的安全登入機制。²¹
• Skills 與工具。image_generate 現在可在每個支援的圖像提供者上編輯與轉換來源圖片，不再僅能從零開始建立圖片；memory 工具新增 operations 陣列，可在單次呼叫中原子性批次新增、取代或移除；新的 simplify-code skill 會執行平行的三代理審查與清理流程，並以 Chesterton’s-Fence 風險層級作為閘門；布林值 write_approval 取代三態的 write_mode。²¹
• 架構。背景子代理會立即回傳控制代碼，並在新回合中重新帶入結果；MCP 引導處理常式允許在工具呼叫期間進行確認，而延後連線的 MCP 工具會在回合之間公開（快取安全）；cron 改為可插拔的 CronScheduler，並支援 Chronos 受管理的 cron 提供者；新的 Managed scope（/etc/hermes）可讓管理員釘選使用者不可變更的設定，另提供適用於多 gateway 拓撲的 Gateway-Gateway 中繼。²¹
• 新增指令。/version、/billing（互動式終端帳務）、hermes photon login（iMessage 驗證），以及 hermes curator run --consolidate——整併現在採選用方式，因此例行背景整理不會耗用任何 token。²¹
• 安全性。v0.17.0 修補 shell 跳脫字元拒絕清單繞過問題；在核准模組或自有政策 gateway 介接器缺失時採取失敗即關閉；清理 cron 工作腳本子程序的環境；在請求偵錯傾印中遮蔽祕密資訊；篩檢 MCP stdio 設定中的資料外洩模式；並升級 urllib3 與 PyJWT 以修補 CVE。²¹

若要從 v0.16.x 升級，此版本不會破壞 CLI；它是在相同代理周圍加入新頻道、模型與操作介面。免中繼的 iMessage、官方 WhatsApp 介接器，以及管理員用的 Managed scope，是最值得升級的主因。

v0.16.0 的新功能（Surface Release）

Hermes Agent v0.16.0（標籤 v2026.6.5，2026年6月5日）以它為 CLI 優先代理帶來的新操作介面命名。最大亮點是 Hermes 不再只能在終端機中使用。²⁰

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

若要從 v0.15.x 升級，這些變更都不會破壞 CLI 本身；它們是在相同代理周圍新增操作介面與提供者。若您希望讓非終端機使用者使用 Hermes，或從瀏覽器管理遠端 gateway，桌面應用程式與管理面板就是升級的理由。

安裝

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

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

自v0.19.0起，pip與Homebrew安裝方式已棄用。v0.14.0推出的PyPI套件（pip install hermes-agent）與Homebrew formula現在都標示為「不受支援的舊版」安裝方式——Hermes偵測到其中任一方式時，所有介面都會發出警告（但不會阻擋使用），並計畫停止發布至PyPI/Homebrew。若您透過pip或brew安裝，請改用上述安裝程式。²⁵

支援Linux、macOS、WSL2及Android/Termux（安裝程式會自動偵測Termux，並切換至已測試的Android套件）。⁷原生Windows現已列為Tier 1平台，不再是v0.14.0推出時的早期beta版本——請使用iex (irm https://hermes-agent.nousresearch.com/install.ps1)安裝。文件明確指出一項限制：macOS僅支援Apple Silicon，不支援Intel Mac。²⁴回顧來看，v0.14.0曾透過PowerShell安裝程式在早期beta階段加入原生Windows支援；但在Windows路徑趨於成熟前，正式環境仍建議優先使用WSL2。¹⁹

完成後：

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

唯一的前置需求是git。安裝程式會透過uv自動佈建Python3.11（不需要sudo）、Node.js 26（供瀏覽器自動化與WhatsApp bridge使用）、ripgrep和ffmpeg。自v0.20.0起，Node 26是硬性最低要求——安裝程式會拒絕任何較舊版本，並改為安裝由Hermes管理的Node版本。²⁴⁷

驗證安裝

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

hermes doctor會精確告訴您缺少哪些項目，以及修正方式。⁷當您需要協助時，hermes dump是應貼到GitHub issue或Discord討論串中的診斷命令——它會以純文字彙整整個設定，並遮蔽敏感資訊。⁸

手動安裝

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

Termux的安裝命令不同——它使用附帶constraints檔案的pip，而非uv pip：

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

這是因為Android上的.[all]會透過voiceextra拉入faster-whisper，而它依賴尚未針對Android發布wheel套件的ctranslate2。⁷

驗證與提供者

Hermes支援約22個一級提供者及自訂端點（v0.19.0新增Fireworks AI、DeepInfra與Upstage Solar），並提供3種不同的驗證路徑。以下依路徑整理完整驗證介面，方便您找到符合需求的方式。

3種驗證路徑

Hermes中的每個提供者都符合以下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，以及多數第三方提供者。²自v0.19.0起，key不必再放在純文字檔案中：可插拔的SecretSource介面可在載入時從Bitwarden或1Password（op://參照）取得祕密資料，並支援同時啟用多個保管庫、確定性的優先順序、衝突警告與每個變數的來源資訊；.env仍是備援機制。（這與v0.15.0的Bitwarden Secrets Manager啟動權杖不同；後者以單一權杖整合提供者key，而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設定key，可將其從/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 Tokens（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（全球版與中國端點），以及具有專屬提供者ID的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

可使用GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL或DASHSCOPE_BASE_URL環境變數覆寫Base URL。²

Z.AI會自動偵測端點。使用z.ai/GLM提供者時，Hermes會探測多個端點（全球、中國、程式設計變體），以找出接受您API key的端點。可用端點會自動快取——多數使用者不需要設定GLM_BASE_URL。²

xAI（Grok）會自動啟用提示快取。當Base 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 key或OAuth權杖——適合在不變更程式碼的情況下，將速率限制分散至多個key。⁶舊版hermes login/hermes logout命令已移除；請改用hermes auth。⁶

自訂與自行託管端點

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

互動式設定（建議使用）：

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

手動設定config.yaml：

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

兩種方式都會持續儲存至config.yaml，它是主模型、提供者與Base 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；若剛好只載入一個模型，便會自動選取，適合執行單一模型的本機伺服器。²

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

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

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

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

Ollama關鍵陷阱：Ollama預設內容長度極低（24GB VRAM以下為4,096個token）。必須透過OLLAMA_CONTEXT_LENGTH或Modelfile提高它——與OpenAI相容的API不接受由用戶端設定內容長度，因此Hermes無法代為設定。²作為agent使用時，請至少設定16k–32k。

vLLM——高效能GPU服務：

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

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

SGLang——使用RadixAttention進行KV快取重複使用的快速服務：

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

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

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

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

工具呼叫需要--jinja。若未啟用，llama-server會完全忽略tools參數，模型則會在回應文字中寫入JSON來嘗試呼叫工具——Hermes無法將其剖析為真正的工具呼叫。²

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

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

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

具名自訂提供者

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

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

接著可在工作階段中途使用三段式語法進行切換：

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

您也可從互動式hermes model選單選取具名自訂提供者。²

可插拔提供者架構（v0.13.0+）

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

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

hermes proxy會公開一個與OpenAI相容的本機端點，後端使用Hermes已登入的OAuth提供者——Claude Pro、ChatGPT Pro、SuperGrok，或其他相容的已設定提供者。¹⁹這表示預期使用OpenAI風格API的工具，包括Codex CLI、Aider、Cline、Continue或自訂指令碼，都可重複使用您由訂閱支援的Hermes驗證，無須另行設定API key。請將proxy視為本機開發基礎設施：謹慎繫結，不要廣泛公開，並留意各提供者的特定條款。

內容長度偵測

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

• context_length——總內容視窗（合計輸入與輸出token預算，例如Claude Opus 4.7的1,000,000，或Sonnet 4.6的200,000）。Hermes依此決定何時壓縮歷程記錄。
• model.max_tokens——輸出上限（模型在單次回應中最多可產生的token數）。與歷程記錄長度無關。

當自動偵測誤判視窗大小時，請設定context_length：

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

Hermes使用多來源解析鏈偵測內容視窗：設定覆寫→自訂提供者的各模型設定→持續性快取→端點/models→Anthropic/v1/models→OpenRouter API→Nous Portal→models.dev（由社群維護、收錄3800+模型的registry）→備援預設值（128K）。²系統具備提供者感知能力，因此同一模型依提供者不同可能有不同內容限制（例如claude-opus-4.6在Anthropic直接服務時為1M，但在GitHub Copilot上為128K）。²

智慧模型路由：提供者輪替與備援

Hermes不會將您固定在單一提供者的單一模型。智慧模型路由是一組決定實際由哪個提供者與模型處理特定請求的 機制：憑證集區將負載分散至多個key，設定的備援會在主要模型失敗時接手，而 下方的輔助槽位會獨立將側邊工作路由至比主模型更便宜的模型。²⁶請一併設定這3項——它們正是 在速率限制下停滯的agent，與能持續運作的agent之間的差異。

憑證集區。當同一提供者有多個API key時，可透過hermes auth設定輪替策略。這是將速率限制分散至多個key的方式。⁶

備援模型。設定備援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

備援會在工作階段中途替換模型與提供者，而不遺失您的對話。每個工作階段最多觸發一次。²支援備援的提供者：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使用輕量「輔助」模型處理側邊工作：影像分析、網頁摘要、瀏覽器螢幕截圖分析、危險命令核准分類、內容壓縮、工作階段搜尋摘要、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 key），影像、網頁摘要與壓縮功能將降級或失敗，因為預設輔助備援鏈會先嘗試OpenRouter。請為輔助工作加入OPENROUTER_API_KEY，或重新設定每個輔助槽位使用您的主要提供者：

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為準。⁴規則如下： - 機密資訊（API keys、bot tokens、密碼）→.env - 其他所有項目（model、terminal backend、compression settings、memory limits、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 arguments——hermes chat --model anthropic/claude-sonnet-4（單次呼叫覆寫）
2. 環境變數——在程序啟動時套用
3. config.yaml——主要設定檔
4. .env——僅供機密資訊使用
5. 內建預設值——其他來源皆未設定值時套用

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

在地化（v0.13.0+）

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

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

Profiles讓您擁有多個彼此隔離的Hermes執行個體，各自具備獨立的設定、sessions、skills、memory與gateway PID。您可藉此並行執行「工作用Hermes」與「個人用Hermes」，且雙方都無法看見彼此的狀態。⁶

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

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

CLI 指令

本節為實務工作者整理頂層 CLI 指令的參考資料。如需以原始碼為依據的權威參考，請參閱上游的CLI 指令參考。⁶

全域選項

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

頂層指令

hermes chat——主要入口

不帶任何引數執行 hermes會進入互動式聊天。hermes chat是提供選項的明確形式：⁶

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

主要選項：

hermes setup——完整精靈

執行完整設定精靈，或直接進入其中一個區段：⁶

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

hermes logs——結構化日誌查詢

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

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

日誌檔位於 ~/.hermes/logs/：⁶ - agent.log——所有 agent 活動（API 呼叫、工具派送、工作階段生命週期、INFO+） - errors.log——僅包含警告與錯誤（agent.log 的篩選子集） - gateway.log——訊息 gateway 活動（平台連線、派送、webhook）

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

hermes doctor——診斷

出現問題時，首先應執行 hermes doctor [--fix]。它會檢查 config 有效性、相依項目是否存在、API key 是否可用、服務狀態，並可透過 --fix嘗試自動修復。⁶

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

斜線指令

斜線指令會在進行中的聊天工作階段（CLI或訊息平台）內執行。它們由hermes_cli/commands.py中的共用COMMAND_REGISTRY派送，因此大多數指令在各種介面上的運作方式完全一致。⁹

工作階段控制

設定與模型

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

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

v0.19.0新增/model --once——單回合模型覆寫，回應後會自動還原為先前的模型。²⁵

工具、Skills與資訊

動態Skill斜線指令

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

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

自v0.19.0起，斜線skill呼叫可堆疊：/skill-a /skill-b do XYZ會在單一回合中依序載入兩個skill，並為串接名稱提供自動完成與預輸文字。²⁵

您也可以在config.yaml中定義快速指令，將簡短名稱設為較長提示的別名：⁹

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

接著在CLI中輸入/review、/deploy或/morning。

前綴比對

指令支援前綴比對：輸入/h會解析為/help，/mod會解析為/model。當前綴含義不明確時，會由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]——瀏覽所有指令與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）、除了DAC_OVERRIDE、CHOWN與FOWNER以外皆移除Linux能力、不允許權限提升、PID限制（256個程序）、完整的命名空間隔離，以及透過volumes提供持久工作區。¹⁰

背景程序

終端機工具支援透過明確的程序管理執行背景工作：¹⁰

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

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

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

Sudo

如果命令需要sudo，Hermes會提示您輸入密碼（會在該工作階段快取）。或者，可在~/.hermes/.env中設定SUDO_PASSWORD。¹⁰

多Agent Kanban（v0.13.0+）

v0.13.0將多Agent協作提升為一項一級原語：可跨Agent、跨重新啟動追蹤任務、狀態與工作者身分的持久Kanban看板。¹⁸此看板讓一群Hermes工作者真正完成工作，而不是卡在無法交接的死結中。

Kanban看板可自然搭配/goal（鎖定目標的Ralph迴圈）處理目標端，並搭配既有的delegate_task工具處理生成語意。結果形成一種群體模式：每個Agent都共享同一個事實來源，清楚掌握下一步該做什麼、由誰處理，以及哪些事項卡住了。

什麼是Hermes Swarm？

swarm是數個Hermes工作者針對同一個共享Kanban看板平行運作。 它不是需要另外啟用的獨立子系統——而是看板所帶來的可能性。看板 提供了平行Agent無法自行提供的一項要素：對於接下來該認領什麼，以及是否已有其他人處理的單一權威 答案。

v0.15.0將此模式提升為受支援的拓撲，新增了用於 平行工作者協調的swarm拓撲、將高層目標自動拆解為子任務、 每項任務的模型覆寫、排程任務與worktree管理，讓平行 工作者不會在同一個checkout中互相衝突。²⁸

實際做法是：為swarm提供目標，讓自動拆解將其分解為看板任務， 再由工作者認領、執行並回傳結果。重試額度依任務設定（max_retries）， 因此單一脆弱子任務不會耗盡整次執行的容錯空間。由於看板具有 持久性，swarm可跨重新啟動持續運作——工作者會重新附著並依相同狀態繼續執行。

swarm的品質取決於拆解品質。看板負責協調工作者；它不會 將拆分不良的目標變成良好的目標。共享隱藏狀態的任務仍然會互相衝突， 無論是否使用worktree。

Skills 系統

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

條件式啟用

Skills可依據可用的工具決定是否顯示。這對於備援 skill尤其實用——也就是僅在付費工具不可用時才應出現的免費或本機替代方案：¹¹

範例：內建的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。設定 FIRECRAWL_API_KEY 後，web toolset 便可使用，代理會使用 web_search——DuckDuckGo skill 會維持隱藏。若沒有 API key，DuckDuckGo skill 便會自動作為備援出現。¹¹

由代理管理的 Skills

代理可透過 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 來源（無需設定即可瀏覽）：openai/skills、anthropics/skills、huggingface/skills、NVIDIA/skills、garrytan/gstack。claude-marketplace來源已於 v0.20.0 移除；來源清單中改由 browse-sh 取代。¹¹²⁴

安全掃描

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

信任等級：¹¹

--force可覆寫社群 skill 的非危險政策封鎖；但無法覆寫 dangerous 掃描判定。¹¹

外部 Skill 目錄

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

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

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

持久記憶

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

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

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

應儲存的內容

請儲存這些內容（代理程式會主動執行）：¹² - 使用者偏好：「我偏好 TypeScript 而非 JavaScript」→ user - 環境事實：「此伺服器執行搭載 PostgreSQL 16 的 Debian 12」→ memory - 修正事項：「不要對 Docker 指令使用 sudo，使用者在 docker 群組中」→ memory - 慣例：「專案使用 Tab、120 字元行寬與 Google 風格 docstring」→ memory - 已完成工作：「已於 2026-01-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 window。

Checkpoints v2（v0.13.0+）

v0.13.0 將狀態持久化改寫為單一儲存區設計，具備真正的清除機制、磁碟防護措施，且不再有孤立的 shadow repo。¹⁸ 舊版 checkpoint 系統會在長時間執行的 profile 中持續累積磁碟狀態；v2 儲存區為本機 checkpoint 儲存設下硬性上限，並移除導致該成長的重複記帳作業。不需要變更任何面向使用者的設定；下一次寫入 checkpoint 時便會使用 v2 路徑。

Personality 與 SOUL.md

SOUL.md 是 Hermes 執行個體的主要身分。它會佔據系統提示中的第 1 個位置，取代硬式編碼的預設身分。¹³

Hermes 會自動在 ~/.hermes/SOUL.md 建立預設的 SOUL.md（自訂 profile 則位於 $HERMES_HOME/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。¹³

內建 Personality

Hermes 內建多種 Personality，您可以透過 /personality 切換：¹³

config.yaml 中的自訂 Personality：¹³

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起，也能直接在session內管理訂閱：/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、memory、messaging gateway、cron、MCP、本機dashboard，以及每個供應商的BYOK）都無須付費即可端對端運作。v0.10.0為已付費使用Nous Portal的使用者新增便利途徑，並未從免費途徑移除任何功能。

Messaging Gateway

Hermes可作為長時間執行的gateway程序運作，透過單一gateway程序連接28個訊息平台：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 adapter。^329171819 v0.9.0透過BlueBubbles新增iMessage支援（自動註冊webhook、設定精靈、當機韌性），並透過iLink Bot API新增原生WeChat支援，以及供企業應用程式使用的WeCom callback模式。¹⁶ v0.11.0新增QQBot。²⁹ v0.12.0新增Microsoft Teams與Tencent Yuanbao。¹⁷ v0.13.0新增Google Chat，成為第20個平台，沿用相同的可插拔adapter架構；IRC與Microsoft Teams也遷移至新的adapter模式，並使用通用的env_enablement_fn／cron_deliver_env_varplugin hooks。¹⁸ v0.14.0新增LINE與SimpleX Chat，並透過Graph驗證、webhook listener、pipeline runtime與對外傳送功能，完成Microsoft Teams的端對端整合。¹⁹ v0.17.0（2026年6月19日）透過Photon Spectrum新增無relay的iMessage支援（使用hermes photon login進行裝置代碼OAuth，無須Mac／BlueBubbles relay）、官方WhatsApp Business Cloud API adapter（取代bridge-process需求）、SimpleX群組與原生附件，以及作為內建平台plugin的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)

互動式設定會引導您連接各個平台：APItokens、bot IDs、channel mappings與allowlists。⁶

訊息流程

摘自上游架構文件：³

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

每個訊息平台都透過與CLI相同的AIAgent對話迴圈運作。這正是slash commands在兩種情境下皆能一致運作的原因，也是排程於Telegram的cron job能將輸出傳送至Discord的原因——平台差異僅存在於邊界層。³

v0.19.0新增以profile為基礎的訊息路由與持久化傳送。共用一個bot token的單一多工gateway，可將特定guild、channel或thread路由至不同profile；每個profile均有完全隔離的config、skills、memory與secrets，並提供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系統，其中job是agent任務，而非shell commands。每個排程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

或者，直接在訊息聊天中以對話方式建立：

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

agent會透過其tools設定cron job。job會持久儲存於JSON並在重新啟動後保留。³

MCP整合

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

作為client——將Hermes連接至外部MCPservers，以擴充其tool surface：

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起，MCPtools會以mcp__server__tool命名慣例提供給模型——每個tool名稱都帶有其server名稱，因此兩個server公開相同tool時不再衝突——而MCPserver的log notifications則會顯示在agent.log中。²⁵

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

hermes mcp serve
hermes mcp serve -v    # Verbose

Context 壓縮

Hermes會自動壓縮過長的對話，以維持在您模型的 context window 範圍內。壓縮摘要器是獨立的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，因為它會接收對話中間的完整區段來進行壓縮。⁴

預算壓力警告

當 agent處理包含許多 tool call的複雜任務時，可能在未察覺的情況下耗盡 iteration budget（截至v0.20.0，預設為500回合，原為90回合）。預算壓力會自動向模型發出警告：⁴

串流逾時

LLM的 streaming connection具有兩層 timeout，且會針對本機provider（localhost、LAN IP）自動調整：⁴

本機endpoint的 socket read timeout會提高至30分鐘，因為本機LLM在大型 context進行 prefill後，可能要數分鐘才會產生第一個 token。⁴

本機Web Dashboard（v0.9.0+）

用於在本機管理Hermes Agent的 browser-based dashboard。您可以設定選項、監看 session、瀏覽 skill，以及管理 gateway，無須接觸 config file或 terminal。¹⁶使用hermes dashboard啟動。對偏好GUI的新使用者而言，這是最容易上手的途徑。

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

watch_patterns可讓您設定要監控的 background process output模式，並在符合時即時收到通知。¹⁶您可監控錯誤、等待特定事件（「listening on port」），或觀察 build log，全程無須 polling。搭配v0.8.0的notify_on_complete（會在背景任務完成時通知），Hermes如今具備完整的 background process observability layer。¹⁵

可插拔Context Engine（v0.9.0+）

現在可透過hermes plugins以可插拔方式管理 context。您可以替換自訂context engine，控制 agent每回合看到的內容，例如篩選、摘要或注入特定領域的 context。¹⁶這會將 context strategy與核心 agent loop分離，讓您能依專案或領域自訂 context。

備份與還原（v0.9.0+）

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

Termux／Android支援（v0.9.0+）

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

安全性強化（v0.13.0+）

v0.13.0修正了8項P0 security issue，並將一項預設值改為更有利於使用者。¹⁸v0.14.0接續修正另外12項P0與50項P1問題，包含 sudo brute-force／sudo-stdin強化、危險command繞過修正、在重新注入模型前清理 tool error、dashboard plugin API auth、skills-hub SSRF涵蓋，以及安裝期間的 supply-chain advisory scanning。¹⁹

若您維護Hermes deployment，應將v0.13.0與v0.14.0視為與安全性相關的升級，而不只是功能更新。v0.13.0修正Discord跨guild繞過及兩個TOCTOU window；v0.14.0則針對 sudo handling、tool-error reinjection、plugin APIs、skills-hub SSRF與dependency advisory進行另一輪強化。

實務工作者的架構指南

本節適合想了解底層運作的人，以便除錯、擴充功能或分析效能。內容綜合整理自上游架構文件。³

進入點→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重新建立其工具資訊清單）。

三種API模式

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

runtime_provider.py解析器會將(provider, model)組合對應至(api_mode, api_key, base_url)，支援18種以上的provider，並處理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

出自上游架構頁面。³

Prompt組裝順序

prompt堆疊包含：¹³

1. SOUL.md（agent身分識別——若無法取得，則使用內建備援）
2. 工具感知的行為指引
3. 記憶／使用者內容（MEMORY.md、USER.md）
4. skill指引
5. 內容檔案（AGENTS.md、.cursorrules）
6. 時間戳記
7. 平台專屬的格式提示
8. 可選的system prompt疊加層，例如/personality

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

工作階段儲存

採用以SQLite為基礎的工作階段儲存，並支援FTS5全文搜尋。工作階段具備血緣追蹤（壓縮前後的父／子關係）、各平台隔離，以及可處理競爭狀況的原子寫入機制。³

Plugin系統

提供3個探索來源：~/.hermes/plugins/（使用者）、.hermes/plugins/（專案）及pip entry points。Plugin會透過context API註冊工具、hook與CLI命令。記憶體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個來源資料夾的skill、預設model、自訂provider、MCP伺服器、訊息平台token與allowlist（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent預設值（推理力度、壓縮、人為延遲、時區、sandbox）、工作階段重設政策、核准規則、TTS設定、瀏覽器設定、工具設定、exec逾時、命令allowlist、gateway設定，以及來自3個來源的API金鑰。⁶

封存以供人工檢視：cron工作、plugin、hook/webhook、記憶體後端（QMD）、skills registry設定、UI／身分識別、記錄、多agent設定、channel繫結、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

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

疑難排解

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

每次全新安裝都會遇到的第一個錯誤：Hermes尚未解析出提供者。訊息的意思就是字面所示——三種驗證途徑都未產生可用的提供者。請執行：

hermes model

互動式選擇器會帶您設定所有支援的提供者，包括OAuth裝置代碼流程（Nous Portal、GitHub Copilot、Anthropic、OpenAI Codex），以及自架伺服器的自訂端點。如果您原本預期已設定提供者，hermes doctor會顯示Hermes實際能讀取哪些憑證；常見原因包括：API金鑰設在錯誤位置（應放在.env或透過hermes config set設定，而非您的Shell設定檔）、~/.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端點自動偵測內容長度，但許多本機伺服器回報的預設值偏低。請在config.yaml中明確設定：²

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

Tool呼叫顯示為文字而未執行

您的伺服器尚未啟用tool calling，或模型不支援透過該伺服器實作進行tool calling。²

回應在句子中途被截斷

可能有兩個原因：²

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

從WSL2連線至Windows託管的模型伺服器時出現「Connection refused」

WSL2使用具有獨立子網路的虛擬網路介面卡——WSL2內的localhost指向Linux VM，而非Windows主機。有兩個選項：²

鏡像網路（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推出的開源代理框架，可搭配任何OpenAI相容提供者——Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google，或您自行託管的端點。¹²Hermes也隨附適用於Telegram/Discord/Slack/WhatsApp/Signal的訊息gateway，這是Claude Code所沒有的。

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

可以。有三種方式：²

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。對話歷程、記憶與skills都會一併保留：⁹

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

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

您遇到的是輔助模型備援機制。Vision、網頁摘要、壓縮及其他背景任務會使用另一個輔助LLM——預設透過自動偵測使用Gemini Flash（OpenRouter→Nous→Codex）。若這些都未設定，而您只設定了Anthropic，這些功能便會悄然降級。⁴

修正方式：為輔助任務加入OPENROUTER_API_KEY，或重新設定輔助插槽以使用主要提供者。請注意，內容壓縮位於獨立的頂層compression:區塊，使用的是summary_provider，而非auxiliary.compression.provider——auxiliary.compression插槽僅提供timeout。完整修正如下：

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

compression:
  summary_provider: "main"

SOUL.md與AGENTS.md有何差異？

SOUL.md是代理的身分——語氣、風格與溝通預設值。它位於~/.hermes/SOUL.md，會隨您到處使用。AGENTS.md則是專案專屬內容——架構、慣例、命令與路徑——位於您的專案目錄。¹³若應隨您到處使用，請放在SOUL.md；若屬於專案，請放在AGENTS.md。

如何並排執行多個Hermes執行個體？

使用profile。每個profile都有獨立的HERMES_HOME、設定、記憶、工作階段與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，或您自行託管的伺服器。²請參閱自訂與自架端點了解各伺服器的設定方式。

為什麼我的啟動橫幅顯示的tools數量比指南所述的Hermes功能更少？

指南引用上游架構登錄中的47個tools／20個toolsets——這是Hermes在所有toolset中附帶原始碼的完整工具數量。您正在執行的安裝版本會在橫幅中顯示較小的數量（本指南使用的參考安裝版本回報28個tools），因為Hermes只會在啟動時啟用預設toolset集合。許多toolsets採選用方式：訊息gateway介面卡、瀏覽器自動化、較重的爬取堆疊，以及若干專門整合，都必須先在~/.hermes/config.yaml的toolsets:下明確列出才會載入。登錄總數＝「啟用後可使用的內容」。橫幅總數＝「目前profile實際載入的內容」。請使用hermes tools --list查看哪些toolsets已啟用，以及哪些可用但已停用。可在執行期間以/tools enable <name>和/tools disable <name>切換個別toolsets（停用會觸發工作階段重設，讓代理依新結構重建其tool manifest）。

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

在config.yaml設定fallback_model區塊：²

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

當主要提供者失敗（速率限制、伺服器錯誤、驗證失敗）時，Hermes會在工作階段中途切換至備援模型，而不遺失對話歷程。每個工作階段最多觸發一次。

代理能隨時間改善自己的skills嗎？

可以——這正是Hermes Agent「self-improving」的部分。代理可透過skill_manage tool建立、更新及刪除skills。當它摸索出非瑣碎的工作流程時，會將方法儲存為skill供日後重複使用。¹¹代理會在複雜任務（5次以上tool呼叫）後、遇到錯誤並找到可行途徑時、您修正其做法時，或發現非瑣碎工作流程時建立skills。

是否有IDE整合？

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

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

變更紀錄

參考資料