<!-- Source: https://hermesbible.com/docs/user-guide/features/fallback-providers -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/fallback-providers

Fallback Providers（備援供應商）

Hermes Agent 具備三層彈性機制，當供應商發生問題時，能讓你的 Session 持續運作：

1. Credential Pools — 在同一個供應商的多組 API Key 之間輪替（優先嘗試）
2. 主要模型 Fallback — 當你的主模型失敗時，自動切換到不同的 供應商:模型
3. 輔助任務 Fallback — 針對視覺、壓縮、網頁擷取等副任務，提供獨立的供應商解析機制

Credential Pools 負責同供應商之間的輪替（例如多組 OpenRouter Key）。本頁說明的是跨供應商的 Fallback。兩者都是可選的，且各自獨立運作。

主要模型 Fallback

當你的主要 LLM 供應商遇到錯誤——速率限制、伺服器過載、驗證失敗、連線中斷——Hermes 能在 Session 中自動切換到備援的供應商:模型，而不用丟失你的對話。

設定方式

最簡單的方式是透過互動式管理工具：

hermes fallback

hermes fallback 複用了 hermes model 的供應商選擇器——相同的供應商清單、相同的憑證提示、相同的驗證流程。使用子指令 add、list（別名 ls）、remove（別名 rm）和 clear 來管理 Fallback 鏈。變更會儲存在 config.yaml 頂層的 fallback_providers: 清單中。

如果你偏好直接編輯 YAML，可在 ~/.hermes/config.yaml 加入頂層的 fallback_providers 清單：

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

每個條目都需要同時指定 provider 和 model。缺少任一欄位的條目會被忽略。

注意 — fallback_model 與 fallback_providers

fallback_providers（複數、清單）是目前的設定格式，支援多個備援供應商依序嘗試。fallback_model（單數）是舊版的單一備援鍵——Hermes 為了向後相容仍會採用，但 hermes fallback 會寫入目前的 fallback_providers 鍵，並在寫入時自動遷移舊版設定。兩者同時設定時，fallback_providers 優先。

支援的供應商

自訂端點 Fallback

若要使用自訂的 OpenAI 相容端點，請加入 base_url 以及可選的 key_env：

fallback_providers:
  - provider: custom
    model: my-local-model
    base_url: http://localhost:8000/v1
    key_env: MY_LOCAL_KEY            # 包含 API Key 的環境變數名稱

Fallback 何時觸發

當主要模型發生以下失敗時，Fallback 會自動啟用：

• 速率限制（HTTP 429）— 重試次數耗盡後
• 伺服器錯誤（HTTP 500、502、503）— 重試次數耗盡後
• 驗證失敗（HTTP 401、403）— 立即觸發（無重試必要）
• 找不到資源（HTTP 404）— 立即觸發
• 回應無效 — API 反覆回傳格式錯誤或空的回應時

觸發後，Hermes 會：

1. 解析備援供應商的憑證
2. 建立新的 API 客戶端
3. 就地替換模型、供應商和客戶端
4. 重設重試計數器並繼續對話

切換是無縫的——你的對話歷史、工具呼叫和上下文都會保留。Agent 會從離開的地方繼續，只是使用不同的模型。

資訊 — 逐輪（Per-Turn），非逐 Session

Fallback 是以輪為範圍：每一則新的使用者訊息都會先嘗試還原主要模型。如果主要模型在某一輪中失敗，Fallback 只在該輪啟用。下一則訊息時，Hermes 會再次嘗試主要模型。在同一輪中，Fallback 最多啟用一次——如果備援也失敗，會進入正常的錯誤處理流程（重試，然後顯示錯誤訊息）。這能防止一輪內的級聯切換迴圈，同時讓每一輪都有機會使用主要模型。

範例

OpenRouter 作為 Anthropic 原生的備援：

model:
  provider: anthropic
  default: claude-sonnet-4-6

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

Nous Portal 作為 OpenRouter 的備援：

model:
  provider: openrouter
  default: anthropic/claude-opus-4

fallback_providers:
  - provider: nous
    model: nous-hermes-3

本地模型作為雲端的備援：

fallback_providers:
  - provider: custom
    model: llama-3.1-70b
    base_url: http://localhost:8000/v1
    key_env: LOCAL_API_KEY

Codex OAuth 作為備援：

fallback_providers:
  - provider: openai-codex
    model: gpt-5.3-codex

Fallback 適用範圍

提示

主要 Fallback 鏈沒有對應的環境變數——只能透過 config.yaml 或 hermes fallback 來設定。這是刻意的設計：Fallback 設定應該是經過深思熟慮的選擇，不該被過時的 Shell 匯出值覆蓋。

---

輔助任務 Fallback

Hermes 會為副任務使用獨立的輕量模型。每個任務都有自己的供應商解析鏈，作為內建的 Fallback 機制。

具有獨立供應商解析的任務

自動探索鏈

當任務的供應商設為 "auto"（預設值）時，Hermes 會先嘗試主要供應商 + 主要模型來執行該輔助任務。如果該路徑不可用，或稍後因容量類型的錯誤失敗，Hermes 會先採用使用者設定的 Fallback 策略，然後才使用內建的探索鏈：

主要供應商 + 主要模型 → auxiliary.<task>.fallback_chain →
fallback_providers / fallback_model → 內建輔助探索鏈

個別任務的鏈最精確，優先度最高。頂層的 fallback_providers 鏈與主要 Agent 使用的策略相同，因此免費或同供應商的 Fallback 規則也會套用到 auto 的輔助任務。

內建文字探索鏈（壓縮、網頁擷取、標題產生等）：

OpenRouter → Nous Portal → 自訂端點 → Codex OAuth →
需 API Key 的供應商（z.ai、Kimi、MiniMax、Xiaomi MiMo、Hugging Face、Anthropic）→ 放棄

內建視覺探索鏈：

主要供應商（若支援視覺）→ OpenRouter → Nous Portal →
Codex OAuth → Anthropic → 自訂端點 → 放棄

這些內建鏈是為尚未設定個別任務或主要 Fallback 策略的使用者提供的便利機制。

設定輔助供應商

每個任務都可在 config.yaml 中獨立設定：

auxiliary:
  vision:
    provider: "auto"              # auto | openrouter | nous | codex | main | anthropic
    model: ""                     # 例如 "openai/gpt-4o"
    base_url: ""                  # 直接端點（優先於 provider）
    api_key: ""                   # base_url 的 API Key

  web_extract:
    provider: "auto"
    model: ""

  compression:
    provider: "auto"
    model: ""
    fallback_chain:              # 可選，個別任務的 Fallback 策略
      - provider: openrouter
        model: inclusionai/ring-2.6-1t:free

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

以上每個任務都遵循相同的 provider / model / base_url 模式。每個任務也可以宣告自己的 fallback_chain；若省略，provider: auto 會先使用頂層的 fallback_providers 鏈，然後才是 Hermes 內建的輔助探索鏈。

上下文壓縮設定在 auxiliary.compression 下：

auxiliary:
  compression:
    provider: main                                    # 與其他輔助任務相同的供應商選項
    model: google/gemini-3-flash-preview
    base_url: null                                    # 自訂 OpenAI 相容端點

而主要 Fallback 鏈使用：

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
    # base_url: http://localhost:8000/v1             # 可選的自訂端點

以上三者——輔助、壓縮、Fallback——運作方式相同：設定 provider 來選擇處理請求的供應商、model 來選擇模型、base_url 來指向自訂端點（覆蓋 provider）。

輔助任務的供應商選項

以下選項僅適用於 auxiliary:、compression: 和 fallback_providers: 條目——"main" 不是頂層 model.provider 的有效值。對於自訂端點，請在你的 model: 區塊中使用 provider: custom（參見 AI Providers）。

直接端點覆蓋

對於任何輔助任務，設定 base_url 會完全繞過供應商解析，直接將請求發送到該端點：

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url 優先於 provider。Hermes 使用設定的 api_key 進行驗證，若未設定則退回使用 OPENAI_API_KEY。自訂端點不會複用 OPENROUTER_API_KEY。

---

輔助容量錯誤 Fallback

當你設定了明確的輔助供應商（例如 auxiliary.vision.provider: glm）時，Hermes 會將其視為你的首選——但如果該供應商因為容量錯誤而無法處理請求（HTTP 402 付款_required、HTTP 429 每日配額耗盡、連線失敗），Hermes 會依序嘗試一層一層的 Fallback 鏈，而非靜默失敗：

1. 主要輔助供應商 — 你設定的那個（永遠優先嘗試）
2. auxiliary.<task>.fallback_chain — 你的個別任務覆蓋清單（若已設定）
3. 主要 Agent 供應商 + 模型 — 最後一道安全網（永遠嘗試，即使你沒有設定鏈）
4. 警告 + 重新拋出 — 若每一層都失敗，Hermes 會在 WARNING 層級記錄 Auxiliary <task>: ... all fallbacks exhausted 並重新拋出原始錯誤

短暫的 HTTP 429 速率限制（Retry-After: ...）會被視為請求限制，而非容量問題——它們會尊重你明確設定的供應商選擇，不會觸發 Fallback 梯隊。只有每日/每月配額耗盡、付款錯誤和連線失敗才會繞過明確供應商的門檻。

對於使用 provider: auto（未明確設定輔助供應商）的使用者，現有的自動探索鏈會在第 2–3 步的位置運行。它的第一步已經是主要 Agent 模型，所以 auto 使用者零設定就能獲得相同的結果。

選擇性：個別任務的 Fallback 鏈

如果你想要不同於「主要 Agent 模型優先」的 Fallback 預設順序，可以明確設定 fallback_chain。每個條目至少需要 provider；model、base_url 和 api_key 是可選的。

auxiliary:
  vision:
    provider: glm
    model: glm-4v-flash
    fallback_chain:
      - provider: openrouter
        model: google/gemini-3-flash-preview
      - provider: nous
        model: anthropic/claude-sonnet-4

  compression:
    provider: openrouter
    fallback_chain:
      - provider: openai
        model: gpt-4o-mini

你不需要設定 fallback_chain 來啟用 Fallback——主要 Agent 的安全網會持續運作。只有在你確實想要不同於預設的順序時才需要設定。

觸發 Fallback 的供應商配額錯誤

Hermes 會將以下錯誤視為與 402 信用耗盡等同的容量錯誤（非短暫速率限制）：

• Bedrock / LiteLLM：Too many tokens per day、daily limit、tokens per day
• Vertex AI / GCP：quota exceeded、resource exhausted、RESOURCE_EXHAUSTED
• 通用：daily quota、quota_exceeded

如果你的供應商使用了不同的每日配額耗盡訊息，而 Hermes 沒有觸發 Fallback，那就是 Bug——請開 Issue 並附上完整的錯誤字串。

---

上下文壓縮 Fallback

上下文壓縮使用 auxiliary.compression 設定區塊來控制哪個模型和供應商處理摘要：

auxiliary:
  compression:
    provider: "auto"                              # auto | openrouter | nous | main
    model: "google/gemini-3-flash-preview"

資訊 — 舊版遷移

舊版設定中的 compression.summary_model / compression.summary_provider / compression.summary_base_url 會在首次載入時自動遷移到 auxiliary.compression.*（設定版本 17）。

如果壓縮沒有可用的供應商，Hermes 會直接丟棄中間的對話輪次而不產生摘要，而非讓 Session 失敗。

---

委派供應商覆蓋

由 delegate_task 產生的 Subagent 會繼承父層 Agent 的主要 Fallback 鏈。你仍然可以將 Subagent 路由到不同的主要供應商:模型組合，以進行成本優化：

delegation:
  provider: "openrouter"                      # 覆蓋所有 Subagent 的供應商
  model: "google/gemini-3-flash-preview"      # 覆蓋模型
  # base_url: "http://localhost:1234/v1"      # 或使用直接端點
  # api_key: "local-key"

詳見 Subagent 委派 以了解完整的設定細節。

---

Cron 任務供應商

Cron 任務在建立 Agent 時會繼承你設定的 fallback_providers 鏈（或舊版的 fallback_model）。若要為 Cron 任務使用不同的主要供應商，請在 Cron 任務本身設定 provider 和 model 覆蓋：

cronjob(
    action="create",
    schedule="every 2h",
    prompt="Check server status",
    provider="openrouter",
    model="google/gemini-3-flash-preview"
)

詳見 排程任務（Cron） 以了解完整的設定細節。

---

總覽

---

---

Credential Pools