<!-- Source: https://hermesbible.com/docs/user-guide/configuring-models -->

Section: 使用 Hermes · URL: https://hermesbible.com/docs/user-guide/configuring-models

設定模型

Hermes 使用兩種模型槽位：

• 主模型 — Agent 思考時使用的模型。每個使用者訊息、每次工具呼叫迴圈、每段串流回應都經過此模型。
• 輔助模型 — Agent 卸載的次要工作所用的小型模型。包括上下文壓縮、視覺（圖片分析）、網頁摘要、審批評分、MCP 工具路由、會話標題生成和技能搜尋。每個輔助任務都有獨立的槽位，可個別覆寫。

本頁說明如何透過儀表板設定這兩者。如果你偏好使用設定檔或 CLI，請跳至底部的替代方法。

提示 — 最快速途徑：Nous Portal

Nous Portal 提供一個訂閱即可使用的 300+ 模型。全新安裝後，執行 hermes setup --portal 登入並以單一指令將 Nous 設為你的供應商。執行 hermes portal info 可查看目前的連線狀態。

• Portal 訂閱者另享 token 計費供應商 9 折優惠。

注意 — model: 架構 — 空字串與對映結構

全新安裝時，內建的預設設定檔使用 model: ""（空字串哨兵值，表示「尚未設定」）。首次執行 hermes setup 或 hermes model 時，該鍵值會就地升級為包含 provider、default、base_url 和 api_mode 子鍵的對映結構 — 即本頁及 profiles.md / configuration.md 中所示的格式。如果在 config.yaml 中看到空字串，執行 hermes model（或在儀表板中點擊變更），Hermes 會自動寫入字典格式。

Models 頁面

打開儀表板並點擊側邊欄中的 Models。你會看到兩個區塊：

1. Model Settings — 頂部面板，用於將模型分配到槽位。
2. Usage analytics — 以排名卡片顯示在選定期間內執行過會話的所有模型，包含 token 數量、成本和能力徽章。

頂部卡片是 Model Settings 面板。主要列始終顯示新會話將啟動的模型。點擊變更即可開啟選擇器。

設定主模型

點擊 Main model 列的變更：

選擇器分為兩欄：

• 左側 — 已驗證的供應商。僅顯示你已設定過的供應商（已設定 API 金鑰、已完成 OAuth 認證，或已定義為自訂端點）。如果缺少某個供應商，請前往 Keys 新增其憑證。
• 右側 — 該供應商的精選模型清單。這是 Hermes 推薦給該供應商的 agentic 模型，而非原始 /models 完整清單（例如 OpenRouter 上的完整清單包含 400+ 模型，涵蓋 TTS、圖片生成器和 reranker）。

在篩選框中輸入文字，可依供應商名稱、slug 或模型 ID 縮小範圍。

選擇模型後按下 Switch，Hermes 會將其寫入 ~/.hermes/config.yaml 的 model 區段。此設定僅適用於新會話 — 已開啟的聊天分頁會繼續使用原有的模型。若要熱切換當前聊天中的模型，請在聊天中使用 /model 斜線命令。

設定輔助模型

點擊 Show auxiliary 展開 11 個任務槽位：

每個輔助任務預設為 auto — 表示 Hermes 會嘗試使用主模型處理該任務。若該路徑不可用或發生容量類型的錯誤，auto 會依序嘗試：該任務專屬的 auxiliary.<task>.fallback_chain、主要的 fallback_providers / fallback_model 串列，最後是 Hermes 內建的輔助模型發現機制。當你想為次要工作指定更便宜或更快的模型時，可覆寫特定任務的設定。

常見覆寫模式

單一任務覆寫

點擊任何輔助列的變更。會開啟相同的選擇器，操作方式相同 — 選擇供應商和模型後按下 Switch。該列會更新顯示 provider · model 取代原本的 auto (use main model)。

重置為 auto

如果你過度調校想重新開始，點擊輔助區塊頂部的 Reset all to auto。所有槽位都會回到使用你的主模型。

「Use as」快捷方式

頁面上每個模型卡片都有 Use as 下拉選單。這是最快的途徑 — 在分析數據中看到想用的模型，點擊 Use as，即可一鍵將其分配至主模型槽位或任何特定的輔助任務：

下拉選單包含：

• Main model — 與在主列點擊變更相同。
• All auxiliary tasks — 一次將此模型分配至所有 11 個輔助槽位。當你想讓所有次要工作都使用便宜的 Flash 模型時很方便。
• Individual task options — Vision、Web Extract、Compression 等。每個任務目前分配的模型會標記為 current。

已分配至某處的卡片會顯示 main 或 aux · <task> 徽章 — 你可以一目了然地看出歷史模型中哪些已連線到哪些位置。

寫入 config.yaml 的內容

透過儀表板儲存時，Hermes 會寫入 ~/.hermes/config.yaml：

主模型：

model:
  provider: openrouter
  default: anthropic/claude-opus-4.7
  base_url: ''        # 切換供應商時會清空
  api_mode: chat_completions

輔助覆寫範例（視覺功能使用 gemini-flash）：

auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash
    base_url: ''
    api_key: ''
    timeout: 120
    extra_body: {}
    download_timeout: 30

輔助任務為 auto（預設）：

auxiliary:
  compression:
    provider: auto
    model: ''
    base_url: ''
    # ... 其他欄位不變

provider: auto 搭配 model: '' 表示 Hermes 使用主模型處理該任務，同時在主路線無法服務輔助呼叫時遵循降級策略。

可選的任務專屬降級串列位於同一輔助任務下：

auxiliary:
  title_generation:
    provider: auto
    model: ''
    fallback_chain:
      - provider: openrouter
        model: inclusionai/ring-2.6-1t:free

當未設定 fallback_chain 時，auto 會在使用內建輔助模型發現機制之前，先嘗試頂層的 fallback_providers 串列。

何時生效？

• CLI（hermes chat）：下一次 hermes chat 呼叫時生效。
• Gateway（Telegram、Discord、Slack 等）：下一個新會話生效。既有會話維持原模型。若要強制所有會話套用變更，請重新啟動 gateway（hermes gateway restart）。
• 儀表板聊天分頁（/chat）：下一個新的 PTY 生效。目前開啟的聊天維持原模型 — 請在聊天中使用 /model 進行熱切換。

變更永遠不會使執行中會話的 prompt 快取失效。這是刻意的設計：在會話中切換主模型需要重設快取（系統提示詞包含模型特定內容），我們將此操作保留給聊天中的 /model 斜線命令。

疑難排解

選擇器中顯示「No authenticated providers」

Hermes 僅列出已設定有效憑證的供應商。請檢查側邊欄中的 Keys — 你應該會看到以下其中一項：API 金鑰、成功的 OAuth 認證，或自訂端點 URL。如果缺少你要的供應商，執行 hermes setup 進行設定，或前往 Keys 新增環境變數。

主模型在執行中的聊天未變更

這是正常的。儀表板寫入的是 config.yaml，新會話會讀取此檔案。目前開啟的聊天是一個即時運作的 Agent 進程 — 它會維持啟動時使用的模型。請在聊天中使用 /model <name> 來熱切換該特定會話的模型。

輕助覆寫「未生效」

請檢查三件事：

1. 你是否已開啟新會話？ 既有聊天不會重新讀取設定檔。
2. provider 是否設定為非 auto 的值？ 若該欄位顯示 auto，則該任務仍在使用你的主模型。點擊變更並選擇實際的供應商。
3. 供應商是否已驗證？ 如果你將 minimax 分配給某個任務但沒有 MiniMax API 金鑰，該任務會降級為 openrouter 預設值，並在 agent.log 中記錄警告。

我選了模型但 Hermes 切換了供應商

在 OpenRouter（或任何聚合器）上，裸模型名稱會先在聚合器內部解析。因此 OpenRouter 上的 claude-sonnet-4 會解析為 anthropic/claude-sonnet-4.6，繼續使用你的 OpenRouter 認證。但如果你在原生 Anthropic 認證下輸入 claude-sonnet-4，它會保持為 claude-sonnet-4-6。如果遇到意外的供應商切換，請確認當前供應商是否符合預期 — 選擇器始終在對話框頂部顯示目前的主模型。

替代方法

CLI 斜線命令

在任何 hermes chat 會話中：

/model gpt-5.4 --provider openrouter             # 僅限本會話
/model gpt-5.4 --provider openrouter --global    # 同時寫入 config.yaml

--global 的作用與儀表板的變更按鈕相同，同時也會就地切換當前執行中的會話。

自訂別名

為常用的模型定義自己的簡短名稱，然後在 CLI 或任何訊息平台中使用 /model <alias>。有兩種等效格式 — 選擇適合你工作流程的即可。

標準格式（頂層 model_aliases:） — 完整控制 provider + base_url：

# ~/.hermes/config.yaml
model_aliases:
  fav:
    model: claude-sonnet-4.6
    provider: anthropic
  grok:
    model: grok-4
    provider: x-ai

簡短字串格式（model.aliases.<name>: provider/model） — 從 shell 操作更方便，因為 hermes config set 只能寫入純量值，無法攜帶自訂 base_url：

hermes config set model.aliases.fav anthropic/claude-opus-4.6
hermes config set model.aliases.grok x-ai/grok-4

兩種路徑都使用相同的載入器（hermes_cli/model_switch.py）。model_aliases: 中宣告的條目優先於同名的 model.aliases: 條目。

然後在聊天中使用 /model fav 或 /model grok。使用者別名會覆蓋內建的簡短名稱（sonnet、kimi、opus 等）。完整參考請見自訂模型別名。

hermes model 子命令

hermes model            # 互動式供應商 + 模型選擇器（切換預設模型的標準方式）

hermes model 會引導你選擇供應商、進行認證（OAuth 流程會開啟瀏覽器；API 金鑰供應商會提示輸入金鑰），然後從該供應商的精選目錄中選擇特定模型。選擇結果會寫入 ~/.hermes/config.yaml 中的 model.provider 和 model.model。

如需在不開啟選擇器的情況下列出供應商/模型，請使用儀表板或下方的 REST 端點。若要查看 CLI 當前實際使用的設定：hermes config show | grep '^model\.' 和 hermes status。

直接編輯設定檔

編輯 ~/.hermes/config.yaml 並重新啟動讀取該檔案的服務。完整架構請參閱設定參考。

REST API

儀表板使用以下三個端點。可用於腳本化操作：

# 列出已驗證的供應商 + 精選模型清單
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/options

# 讀取目前的主模型 + 輔助分配
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/auxiliary

# 設定主模型
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"main","provider":"openrouter","model":"anthropic/claude-opus-4.7"}' \
  http://localhost:PORT/api/model/set

# 覆寫單一輔助任務
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"vision","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set

# 將同一模型分配至所有輔助任務
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set

# 將所有輔助任務重置為 auto
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"__reset__","provider":"","model":""}' \
  http://localhost:PORT/api/model/set

Session token 會在啟動時注入儀表板 HTML 中，並在每次伺服器重啟時輪換。若要對執行中的儀表板進行腳本化操作，可從瀏覽器開發者工具中取得（window.__HERMES_SESSION_TOKEN__）。

---

---

Sessions