備用提供者

Hermes Agent 具有三層容錯機制，可在提供者出現故障時確保您的會話持續運行：

憑證池 — 在同一提供者的多個 API 密鑰之間輪換（優先嚐試）
主模型備援 — 當您的主模型失敗時，自動切換到不同提供者:模型組合
輔助任務備援 — 獨立的提供者解析機制，用於視覺、壓縮和網頁提取等輔助任務

憑證池處理同一提供者的輪換（例如多個 OpenRouter 密鑰）。本頁面介紹跨提供者的備援機制。兩者均為可選，且可獨立工作。

主模型備援

當您的主大語言模型提供者遇到錯誤時——如速率限制、服務器過載、認證失敗、連接中斷——Hermes 可在會話中自動切換至備用提供者:模型組合，而不會丟失對話。

配置

在 ~/.hermes/config.yaml 中添加 fallback_model 部分：

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

provider 和 model 均為必需。若任一缺失，備援將被禁用。

支持的提供者

提供者	值	要求
AI Gateway	`ai-gateway`	`AI_GATEWAY_API_KEY`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`
Nous Portal	`nous`	`hermes auth`（OAuth）
OpenAI Codex	`openai-codex`	`hermes model`（ChatGPT OAuth）
GitHub Copilot	`copilot`	`COPILOT_GITHUB_TOKEN`、`GH_TOKEN` 或 `GITHUB_TOKEN`
GitHub Copilot ACP	`copilot-acp`	外部進程（編輯器集成）
Anthropic	`anthropic`	`ANTHROPIC_API_KEY` 或 Claude Code 憑證
z.ai / GLM	`zai`	`GLM_API_KEY`
Kimi / Moonshot	`kimi-coding`	`KIMI_API_KEY`
MiniMax	`minimax`	`MINIMAX_API_KEY`
MiniMax（中國）	`minimax-cn`	`MINIMAX_CN_API_KEY`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`
OpenCode Zen	`opencode-zen`	`OPENCODE_ZEN_API_KEY`
OpenCode Go	`opencode-go`	`OPENCODE_GO_API_KEY`
Kilo Code	`kilocode`	`KILOCODE_API_KEY`
Alibaba / DashScope	`alibaba`	`DASHSCOPE_API_KEY`
Hugging Face	`huggingface`	`HF_TOKEN`
自定義端點	`custom`	`base_url` + `api_key_env`（見下文）

自定義端點備援

對於自定義的 OpenAI 兼容端點，需添加 base_url 並可選地添加 api_key_env：

fallback_model:
  provider: custom
  model: my-local-model
  base_url: http://localhost:8000/v1
  api_key_env: MY_LOCAL_KEY          # 包含 API 密鑰的環境變量名稱

備援觸發條件

當主模型因以下情況失敗時，備援將自動激活：

速率限制（HTTP 429）——在耗盡重試嘗試後
服務器錯誤（HTTP 500、502、503）——在耗盡重試嘗試後
認證失敗（HTTP 401、403）——立即觸發（重試無意義）
未找到（HTTP 404）——立即觸發
無效響應——當 API 反覆返回格式錯誤或空響應時

觸發後，Hermes 將：

解析備援提供者的憑證
構建新的 API 客戶端
就地替換模型、提供者和客戶端
重置重試計數器並繼續對話

切換過程無縫——您的對話歷史、工具調用和上下文均被保留。Agent 將從它中斷的位置繼續，僅使用不同的模型。

一次性

備援在每個會話中最多觸發一次。如果備援提供者也失敗，將啟用正常錯誤處理（重試，然後顯示錯誤信息）。此舉可防止級聯故障循環。

示例

以 OpenRouter 作為 Anthropic 原生模型的備援：

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

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

以 Nous Portal 作為 OpenRouter 的備援：

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

fallback_model:
  provider: nous
  model: nous-hermes-3

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

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

以 Codex OAuth 作為備援：

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

備援適用場景

上下文	是否支持備援
CLI 會話	✔
消息網關（Telegram、Discord 等）	✔
子 Agent 委派	✘（子 Agent 不繼承備援配置）
定時任務（cron jobs）	✘（使用固定提供者運行）
輔助任務（視覺、壓縮）	✘（使用其自身的提供者鏈——見下文）

提示

fallback_model 無環境變量配置——它僅通過 config.yaml 進行設置。這是有意為之：備援配置是一項明確選擇，不應由過時的 shell 導出變量覆蓋。

輔助任務備援

Hermes 使用獨立的輕量級模型處理輔助任務。每個任務都有自己的提供者解析鏈，構成內置的備援系統。

具有獨立提供者解析的任務

任務	功能	配置鍵
視覺	圖像分析、瀏覽器截圖	`auxiliary.vision`
網頁提取	網頁摘要	`auxiliary.web_extract`
壓縮	上下文壓縮摘要	`auxiliary.compression` 或 `compression.summary_provider`
會話搜索	歷史會話摘要	`auxiliary.session_search`
技能中心	技能搜索與發現	`auxiliary.skills_hub`
MCP	MCP 輔助操作	`auxiliary.mcp`
記憶刷新	內存整合	`auxiliary.flush_memories`

自動檢測鏈

當任務的提供者設置為 "auto"（默認值）時，Hermes 會按順序嘗試各個提供者，直到其中一個成功：

對於文本類任務（壓縮、網頁提取等）：

OpenRouter → Nous Portal → Custom endpoint → Codex OAuth →
API-key providers (z.ai, Kimi, MiniMax, Hugging Face, Anthropic) → give up

對於視覺類任務：

Main provider (if vision-capable) → OpenRouter → Nous Portal →
Codex OAuth → Anthropic → Custom endpoint → give up

如果在調用時解析出的提供者失敗，Hermes 還會進行內部重試：如果提供者不是 OpenRouter 且未顯式設置 base_url，則會將 OpenRouter 作為最後的備用方案嘗試。

配置輔助提供者

每個任務都可以在 config.yaml 中獨立配置：

auxiliary:
  vision:
    provider: "auto"              # 汽車 | openrouter |諾斯|法典|主要| anthropic
    model: ""                     # 例如"openai/gpt-4o"
    base_url: ""                  # 直接端點（優先於provider）
    api_key: ""                   # API 底座鑰匙_url

  web_extract:
    provider: "auto"
    model: ""

  compression:
    provider: "auto"
    model: ""

  session_search:
    provider: "auto"
    model: ""

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

  flush_memories:
    provider: "auto"
    model: ""

上述所有任務均遵循相同的 提供者 / 模型 / base_url 模式。上下文壓縮使用其自身的頂層配置塊：

compression:
  summary_provider: main                             # 與輔助任務相同的 provider 選項
  summary_model: google/gemini-3-flash-preview
  summary_base_url: null                             # 自定義 OpenAI 兼容端點

而備用模型使用：

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

這三者——輔助任務、壓縮、備用模型——工作方式相同：設置 provider 以選擇處理請求的提供者，model 以選擇具體模型，base_url 用於指向自定義端點（覆蓋提供者配置）。

輔助任務的提供者選項

這些選項僅適用於 auxiliary:、compression: 和 fallback_model: 配置——"main" 不是頂層 model.provider 的有效值。對於自定義端點，請在 model: 部分使用 provider: custom（參見 AI 提供者）。

提供者	描述	要求
`"auto"`	按順序嘗試提供者，直到成功（默認）	至少配置一個提供者
`"openrouter"`	強制使用 OpenRouter	`OPENROUTER_API_KEY`
`"nous"`	強制使用 Nous Portal	`hermes auth`
`"codex"`	強制使用 Codex OAuth	`hermes model` → Codex
`"main"`	使用主 Agent 所用的提供者（僅限輔助任務）	已配置主提供者
`"anthropic"`	強制使用 Anthropic 原生接口	`ANTHROPIC_API_KEY` 或 Claude Code 憑據

直接端點覆蓋

對於任何輔助任務，設置 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。

上下文壓縮備用機制

上下文壓縮除了輔助系統外，還保留了舊版配置路徑：

compression:
  summary_provider: "auto"                    # 汽車 | openrouter |我們|手
  summary_model: "google/gemini-3-flash-preview"

這等價於配置 auxiliary.compression.provider 和 auxiliary.compression.model。如果兩者都已設置，則 auxiliary.compression 的值具有優先權。

如果壓縮任務沒有可用的提供者，Hermes 會丟棄中間的對話回合而不生成摘要，而不是導致會話失敗。

委派提供者覆蓋

由 delegate_task 啟動的子 Agent不使用主備用模型。但它們可以被路由到不同的提供者:模型組合，以實現成本優化：

delegation:
  provider: "openrouter"                      # 覆蓋所有子代理的 provider
  model: "google/gemini-3-flash-preview"      # 覆蓋model
  # base_url: "http://localhost:1234/v1" # 或使用直接端點
  # api_鍵："local-key"

完整配置詳情請參見子 Agent 委派。

定時任務提供者

定時任務在執行時使用當時配置的提供者。它們不支持備用模型。若需為定時任務使用不同提供者，請在任務本身配置 provider 和 model 覆蓋：

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

完整配置詳情請參見計劃任務（Cron）。

總結

功能	備用機制	配置位置
主 Agent 模型	`config.yaml` 中的 `fallback_model` —— 錯誤時的一次性故障轉移	`fallback_model:`（頂層）
視覺任務	自動檢測鏈 + 內部 OpenRouter 重試	`auxiliary.vision`
網頁提取	自動檢測鏈 + 內部 OpenRouter 重試	`auxiliary.web_extract`
上下文壓縮	自動檢測鏈，不可用時降級為無摘要	`auxiliary.compression` 或 `compression.summary_provider`
會話搜索	自動檢測鏈	`auxiliary.session_search`
技能中心	自動檢測鏈	`auxiliary.skills_hub`
MCP 助手	自動檢測鏈	`auxiliary.mcp`
記憶清除	自動檢測鏈	`auxiliary.flush_memories`
委派	僅提供者覆蓋（無自動備用）	`delegation.provider` / `delegation.model`
定時任務	僅任務級提供者覆蓋（無自動備用）	任務級 `provider` / `model`

主模型備援​

配置​

支持的提供者​

自定義端點備援​

備援觸發條件​

示例​

備援適用場景​

輔助任務備援​

具有獨立提供者解析的任務​

自動檢測鏈​

配置輔助提供者​

輔助任務的提供者選項​

直接端點覆蓋​

上下文壓縮備用機制​

委派提供者覆蓋​

定時任務提供者​

總結​