設定檔 Config（32 筆）

config.yaml 與環境設定相關的官方 issue。 資料來自官方 GitHub repo，狀態由官方 label 推導，每筆附原始連結與最後檢查日期。

#58320 討論中 P3 comp/tools

web_search / web_extract 失敗時完全沒有提示，使用者可能不知道搜尋功能已失效

當未設定任何 web backend API key 時，web_search 和 web_extract 會靜默失敗或回傳空結果，不會提示使用者搜尋功能不可用，可能導致使用者數週都不知道核心搜尋功能已失效。issue 建議在失敗時回傳明確錯誤訊息與解決步驟。

#58290 有暫時解法 P2 comp/cli

Bug：用 /model xxx --provider xxx 切換模型時，即使沒加 --global 也會自動改寫 config.yaml

使用者透過飛書（feishu）與 hermes agent 對話，發送 /model xxx --provider xxxx 切換模型時，agent 會自動把這個模型與 provider 設成 config.yaml 的預設值（並回覆「Saved to config.yaml (--global)」），但使用者並未輸入 --global 參數，預期應該只改變當前執行期的模型設定。

學校診斷與解法
#58281 有暫時解法 P2 comp/tools

Bug：停用 coding toolset 會連帶悄悄移除已明確啟用的 terminal / file 工具，導致模型收到 Tools: 0

當 config.yaml 的 agent.disabled_toolsets 包含複合 toolset（如 coding）時，Hermes 會扣除該複合 toolset 底下所有工具，即使使用者已明確啟用 terminal 和 file 這兩個子 toolset，最終結果是模型收到零個工具，過程中沒有任何警告，UI 上（/toolsets、hermes tools）仍顯示 terminal 和 file 是啟用的。

#58277 有暫時解法 P2 comp/cli

Bug：profile 的 config.yaml 中空的 YAML key（terminal:）會讓 load_cli_config 出現 TypeError 而當機

當 profile 的 config.yaml 出現 terminal:（有 key 但沒有值）這種空欄位時，YAML 會解析成 None，導致 load_cli_config() 用 defaults.get("terminal", {}) 拿到的是 None 而非預期的空字典，後續判斷式因此拋出 TypeError，使 agent 在第一輪對話前就直接當機。

學校診斷與解法
#58274 討論中 P3 comp/cron

功能請求：完整的 Profile 對等性（Dashboard、Sessions、Cron、路徑隔離）

使用者同時執行多個 Hermes profile，但發現非 default profile 在多個子系統中被當成次等公民對待，例如 cron job 會寫到錯誤 profile 的目錄、dashboard 功能只看得到 default profile、Desktop App 完全忽略非 default 的 session。issue 把這些個別問題彙整成一個總覽，指出根因是程式碼假設 ~/.hermes/（default 根目錄）才是唯一正式路徑。

#58265 有暫時解法 P2 comp/cli

Windows 上設定檔中未知的 provider key 觸發大量警告日誌，導致 log handler 鎖死並卡住 serve / gateway 事件迴圈

在 Windows 上，一個無害的自訂 config key 會讓 _normalize_custom_provider_entry() 在每次 load_picker_context() 呼叫時都印出警告，配合 Windows 上 concurrent-log-handler 的跨程序鎖，大量警告觸發 RuntimeError: Cannot acquire lock after 20 attempts 並重試，佔滿 CPU 並讓 asyncio 事件迴圈卡住約 14 秒，導致所有 desktop / TUI WebSocket 斷線，而 /health 端點仍顯示健康。

學校診斷與解法
#58150 有暫時解法 P2 comp/cli

[Bug] Hermes 在 Windows 上使用系統內建的 Node.js，而非自帶的 Node.js

回報者指出更新 Windows 系統自身的 Node.js 版本後，Hermes 會使用系統的 Node.js 而非內建版本，因版本不同導致終端機視窗持續閃爍。預期行為是 Hermes 應一律使用其內建的 Node.js。

學校診斷與解法
#58116 已修復 P2 comp/gateway

[Bug] 即使設定 platforms.weixin.enabled: false，只要環境變數存在 WEIXIN_* 仍會被忽略並照常連線

回報者指出在 config.yaml 設定 platforms.weixin.enabled: false 後，只要 .env 中仍存在 WEIXIN_ACCOUNT_ID、WEIXIN_TOKEN 等環境變數，gateway 啟動時仍會照常連上微信/iLink 平台，未遵守 enabled: false 的設定。此 issue 已關閉。

#58032 有暫時解法 P2 comp/gateway

Bug: multiplex_profiles 設為 false 後仍留下孤兒 session，導致訊息路由到錯誤 profile

把 gateway.multiplex_profiles 從 true 改回 false 後，先前在多工模式下建立的 profile session 仍殘留在共用的 state.db 中，gateway 會持續讀到這些過期 session 並把訊息路由到錯誤的 profile，即使該 profile 的 gateway 已停用。

#57705 討論中 P3 comp/cli

[Bug] 新增指定的 address model API 時出現錯誤，無法運作

此 issue 標題回報使用者在嘗試新增某個 address model API 時遇到錯誤且功能無法運作，內文僅附上一個外部文件連結與一張截圖，未提供進一步文字說明。

學校診斷與解法
#56058 討論中 P3 comp/desktop

[Bug] 桌面版聊天模型選擇器會寫入全域設定，而非只影響當前 session

回報者指出在 Windows 上使用 Hermes 桌面版狀態列的聊天模型選擇器切換模型時，會直接修改全域的 ~/.hermes/config.yaml，而非按文件所述僅套用於當前 session；預期應該只有透過 Settings → Model 才會變更全域預設值。

#52401 有暫時解法 P2 comp/cron

[Bug] macOS 桌面版：非預設 profile 會看到 default profile 的 session 與 cron（跨 profile 資料外洩）

在 macOS 桌面版切到自建 profile（例如只設定 WeChat 的 rucy）時，UI 仍會顯示屬於 default profile 的 sessions、通訊頻道與 cron jobs，屬於 UI 層的跨 profile 資料外洩。

#47917 已修復 P1 comp/cli

[Bug] 更新後 Desktop build 失敗：electronDist does not exist（快取失效）

這個 issue 指出即使先前 PR #47276 的修復曾經成功，在拉取最新程式碼更新後 Desktop build 又再次失敗，因為更新過程會清除 Electron binary 快取，出現「electronDist does not exist」錯誤，顯示 #47266 的修復並未徹底解決問題。此 issue 已關閉。

學校診斷與解法
#44022 已修復 P2 comp/gateway

桌面版/TUI 續接舊 session 時出現「No LLM provider configured」錯誤（session 只存了 billing_provider，如 custom 供應商）

回報者指出在桌面版（與 TUI gateway）點擊任何舊對話續接時都會失敗並顯示「resume failed: No LLM provider configured」，即使目前設定的預設 provider 完全有效、開新對話也正常；同樣的 session 用 CLI 的 hermes chat --resume 卻能正常續接，僅桌面版/TUI 的 resume 路徑會失敗，回報者已定位到 server.py 中 _stored_session_runtime_overrides() 的 provider 讀取邏輯疑似有問題。

#42961 有暫時解法 P2 comp/cli

[Bug] local 後端會忽略 terminal.cwd 設定，一律使用程式啟動時的目錄

回報者指出在 config.yaml 中設定 terminal.cwd 對 local 終端機後端完全無效，根因是 cli.py 中有一段無條件覆寫邏輯，當後端為 local 時會直接用 os.getcwd() 蓋掉設定值，導致該設定只在 docker、ssh 等非 local 後端才生效。

學校診斷與解法
#38975 討論中 P3 comp/tui

Desktop UI：完整支援設定自訂 OpenAI 相容 provider

Hermes Desktop 目前對許多已知 provider 有內建 API key 欄位，但對自訂的 OpenAI 相容端點（如 AI Router、LiteLLM、自架 gateway 等）只有部分 UI 支援，使用者只能借用其他 provider 的欄位或手動編輯設定檔，容易造成混淆並限制模型清單。此 issue 提議在 Providers 設定中直接加入「Custom provider」選項，只需填 Base URL 與 API key。

暫時解法

目前只能借用 LM Studio 等其他 provider 的欄位，或手動編輯設定檔/環境變數。

#38855 已修復 P1 comp/cli

桌面版「工作目錄」設定無法覆蓋殘留的舊 workspace cwd 記憶

回報者指出在 Hermes Desktop 中，即使在 Settings 中正確設定了新的 Working Directory 並寫入 config.yaml 的 terminal.cwd，若 renderer 端的 localStorage 已記住舊的 workspace 路徑，新 session 仍會在舊目錄啟動，造成 UI 顯示已設定新路徑但實際行為不一致。

學校診斷與解法
#38602 討論中 P3 comp/desktop

[Feature] 支援桌面版 Hermes 以純用戶端模式安裝，連線遠端 Hermes

回報者想把 Hermes Desktop 安裝成連線到遠端既有 Hermes 服務的輕量用戶端，但現況是只要偵測不到本機安裝，桌面 App 就一定會在首次啟動時自動跑 electron/main.cjs 裡的 bootstrap，執行 install.ps1 安裝 Python、Node 等依賴，沒有官方提供的純用戶端安裝版本。

暫時解法

body 提到可在首次啟動前先設定環境變數 HERMES_DESKTOP_REMOTE_URL 與 HERMES_DESKTOP_REMOTE_TOKEN，讓桌面 App 改連線遠端後端、跳過本機後端啟動；但 Electron 外殼本身仍會被安裝，且一旦取消設定這兩個環境變數，下次啟動仍會嘗試 bootstrap 本機環境。

#26879 討論中 P3 comp/agent

[Bug] 同時設定 provider、base_url 與 api_key 時，auxiliary task 的 provider 身分會遺失

回報者指出當 auxiliary 任務（如 auxiliary.vision）同時設定 provider、base_url 和 api_key 時，provider 名稱會被系統忽略並強制改為 custom，導致原本針對特定 provider 的處理邏輯（如 ZAI vision 的 max_tokens 略過、Anthropic transport 偵測等）被跳過，引發後續錯誤。

#24039 有暫時解法 P2 comp/agent

輔助 fallback chain 應該重用 fallback_providers 設定，而不是維護另一份寫死的清單

此 issue 指出 Hermes 目前維護兩套互不相通的 fallback 機制：使用者在 config.yaml 設定的 fallback_providers，以及給 compression、vision、title、web_extract、curator 等輔助任務使用、寫死在程式中的另一份 fallback 清單（含付費模型）。主要 agent 走使用者設定的 fallback_providers，但所有輔助任務卻走另一份寫死清單，兩者彼此不知道對方的存在。

#22791 討論中 P3

功能請求：新增 Infisical 作為外部 Vault 後端（#3630 的子 issue）

此 issue 是 #3630（外部 Vault 支援）的子項目，指出目前支援的外部 Vault 清單（HashiCorp Vault、AWS Secrets Manager、1Password CLI、Bitwarden CLI）缺少對 self-host 使用者很重要的 Infisical。回報者說明若採用 Infisical 建議的多專案架構，Hermes 目前沒有原生方式讀取這些機密。

暫時解法

目前只能用寫死單一專案 ID 的外部 shell wrapper，或把所有機密合併成一個扁平專案，兩者都違背 Infisical 多專案架構的用意。

#20859 討論中 P3

[Feature] 支援 Mistral 作為 LLM provider

此 issue 提議把 Mistral 加入 Hermes-Agent 原生支援的 LLM provider 清單，理由是 Mistral 使用者基數比某些既有支援的 provider 更大，且其語音模型已經整合進 Hermes，作者認為新增文字 LLM 應該不會太困難。目前只能透過 custom provider 選項使用 Mistral，較不方便。

#20510 討論中 P3

功能請求：跨裝置雲端同步 Hermes 所有設定

目前 Hermes 的設定、profile、skills、session 與 memory 都只存在本機 ~/.hermes/ 目錄，多台裝置間沒有內建同步機制，使用者需手動匯出匯入。此 issue 提議加入內建雲端同步功能，涵蓋 config、profiles、skills、memory、sessions 與憑證。

暫時解法

目前只能手動匯出匯入 profile、複製 skills 資料夾，在各裝置間手動同步設定。

#20249 討論中 P3 comp/agent

功能提案：Model Presets，可針對單一回合臨時升級到更強的模型

提案指出目前 Hermes 整個 session 只能用同一個模型，若平時用便宜或快速模型，遇到需要更強推理能力的回合時，只能手動切換模型（之後還要再切回來）或硬著頭皮用弱模型應付；提案建議新增 model_presets 設定，讓使用者能為單一回合臨時呼叫指定的 provider 加 model 組合，用完自動切回預設模型。

#18733 討論中 P3 comp/agent

功能請求：壓縮閾值（compression threshold）依模型 / provider 個別設定

目前 compression.threshold 是全域單一數值，對 1M context 模型（如 DeepSeek V4 Flash）門檻形同虛設，對小 context 模型又太保守。issue 提議在 config.yaml 新增依 provider 或依模型覆寫 threshold 的設定選項。

#17199 有暫時解法 P2 comp/cli

deepseek provider：模型名稱正規化與 base_url 覆寫機制會破壞自訂端點（如 Volcengine ARK）設定

設定 Hermes 使用 deepseek provider 搭配自訂 OpenAI-compatible 端點（如 Volcengine ARK）時有兩個 bug：非標準模型名稱會被強制正規化成 deepseek-chat 導致遠端回傳 404；credential pool 的 base_url 每次啟動都會被硬編碼預設值覆寫，忽略 config.yaml 或 auth.json 中的自訂設定。

暫時解法

目前只有設定 DEEPSEEK_BASE_URL 環境變數能讓自訂端點生效，但官方文件並未將其列為正式設定方式。

學校診斷與解法
#13181 討論中 P3 comp/agent

功能請求：簡化新增 OpenCode Go 等自訂模型到 Hermes Agent 的方式

目前要把 OpenCode Go 這類新模型串進 Hermes Agent，沒有明確或簡單的擴充機制，開發者必須深入內部程式碼才能實驗替代的 LLM provider 或自架推論服務。此 issue 提議建立設定式（YAML/JSON）的模型註冊機制與標準化 adapter 介面。

#12238 討論中 P3 comp/cli

[Feature] 為 Agent 資料（~/.hermes/）內建自動備份與版本控制

此 issue 提議為 Hermes 儲存在 ~/.hermes/ 的所有 agent 資料（記憶、skill、對話紀錄、輸出）內建自動備份機制與版本控制，避免使用者因硬碟故障等問題遺失 agent 累積學到的狀態，目前使用者只能自行架 cron job 或第三方工具。提案包含新增 hermes backup CLI 指令，可立即快照或設定每日排程等用法。

學校診斷與解法
#10567 討論中 P3 comp/cli

功能請求：為 hermes dashboard 新增 --host 與 CORS 設定以支援 Tailscale/VPN 存取

hermes dashboard 預設綁定在 127.0.0.1:9119，且程式碼中 CORS 的 allow_origin_regex 寫死只允許 localhost/127.0.0.1，即使加上 --host 0.0.0.0 讓前端能載入，後端 API 呼叫仍會被 CORS 擋下，導致無法透過 Tailscale 等 VPN 遠端存取 dashboard。此 issue 提議開放設定 dashboard 的 host/port 與 CORS 來源。

學校診斷與解法
#5143 討論中 P3 comp/gateway

[Feature] 透過 Gateway Hooks 實現多角色自動路由

此 issue 提議讓使用者能定義多個具名「角色」（例如營養師、開發者、財務顧問），各自擁有專屬 session 與系統提示，並用一個輕量分類器（如 Gemini Flash）自動把訊息路由到對應角色，藉此解決目前 Hermes 所有話題共用單一 session、單一人格，導致不同主題互相污染 context、無法給予特定領域專長、且需要使用者手動用 /title、/resume 管理 session 的問題。作者註記此提案在 2026 年 5 月已針對 v0.14.0 架構大幅重寫為 v2 版本，取代舊版有缺陷的做法，改用更乾淨的 contextual classifier 與誤路由回復機制，原始 v1 提案保留在摺疊區塊作為歷史紀錄。

#4431 討論中 P3 comp/gateway

功能請求：Gateway session 支援每個群組／主題的個別設定覆寫（topic_configs）

這個 issue 指出目前用同一個 gateway 跑多個 Telegram 群組或 Discord 伺服器時，所有 session 都共用同一組人格、system prompt、CLAUDE.md 與工作目錄，無法針對不同群組或討論串客製化。提案在 config.yaml 新增 topic_configs 區塊，依平台與聊天室 ID 對應各自的設定覆寫。

#1955 已修復 P2 comp/gateway

功能：讓 gateway 平台（Discord/Telegram 等）可依頻道分別設定模型與 system prompt

提案指出目前 gateway 對所有頻道只能使用同一組全域模型與 system prompt，但 Discord 或 Telegram 群組中不同頻道常有不同用途（如低成本摘要頻道、程式開發頻道、閒聊頻道），因此建議新增 channel_overrides 設定，讓每個頻道可個別指定模型、provider 與 system prompt，並定義優先順序（/model 指令高於 channel_overrides，channel_overrides 高於全域設定）。

其他分類

回官方 Issue 精選問答．看學校解法卡．常見問題排解