title: Fallback Providers description: Configure automatic failover to backup LLM providers when your primary model is unavailable. sidebar_label: Fallback Providers sidebar_position: 8

备用提供者机制

Hermes Agent 具有三层容错机制，可在提供者出现故障时确保会话持续运行：

1. 凭证池 — 对同一提供者使用多个 API 密钥进行轮换（优先尝试）
2. 主模型备用 — 当主模型发生故障时，自动切换到不同的提供者与模型组合
3. 辅助任务备用 — 为视觉处理、压缩及网页提取等辅助任务提供独立的提供者解决方案

凭证池用于同一提供者内的密钥轮换（例如多个 OpenRouter 密钥）。本页面介绍跨提供者的备用机制。这两种机制均为可选功能，且可独立运行。

主模型备用机制

当您的主大语言模型提供者出现错误——如速率限制、服务器过载、认证失败或连接中断——Hermes 能在会话进行中自动切换到备用的提供者与模型组合，从而避免丢失对话内容。

配置方式

最简便的方法是通过交互式管理器进行配置：

hermes fallback

hermes fallback 功能会复用 hermes model 中的提供者选择器——即相同的提供者列表、相同的凭据输入提示以及相同的验证机制。您可以使用 add、list（别名 ls）、remove（别名 rm）和 clear 这些子命令来管理该提供者链。相关设置会存储在 config.yaml 文件顶层的 fallback_providers: 列表中。

如果您希望直接编辑 YAML 文件，可在 ~/.hermes/config.yaml 中添加一个顶级的 fallback_providers 列表：

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

每条配置项都必须同时包含 provider 和 model 字段。缺少任一字段的配置项将被忽略。

::note fallback_model 与 fallback_providers 的区别 fallback_providers（复数形式，以列表呈现）是当前的配置格式，支持按顺序尝试多个备用选项。而 fallback_model（单数形式）则是旧版的单一备用键——Hermes 为保持向后兼容仍会支持该键，但当使用 hermes fallback 命令写入配置时，系统会使用新的 fallback_providers 键，并在写入时迁移旧版配置。若同时设置了这两个键，则 fallback_providers 具有优先级。

::

支持的提供商

自定义端点回退机制

对于自定义的兼容 OpenAI 的端点，只需添加 base_url，如需额外配置则可补充 key_env 参数：

fallback_providers:
  - provider: custom
    model: my-local-model
    base_url: http://localhost:8000/v1
    key_env: MY_LOCAL_KEY            # env var name containing the API key

何时触发回退机制

当主模型出现以下故障时，回退机制会自动启动：

• 速率限制（HTTP 429）——在所有重试尝试均失败后
• 服务器错误（HTTP 500、502、503）——在所有重试尝试均失败后
• 认证失败（HTTP 401、403）——立即触发（无需再尝试重试）
• 资源未找到（HTTP 404）——立即触发
• 无效响应——当 API 持续返回格式错误或空响应时

触发回退机制后，Hermes 会执行以下操作：

1. 获取用于回退提供者的凭证
2. 构建新的 API 客户端
3. 直接替换模型、提供者和客户端
4. 重置重试计数器并继续对话

此切换过程无缝衔接——您的对话历史、工具调用及上下文都会被保留。智能体将从之前的中断点继续工作，只是使用了不同的模型。

::warning 回退机制会重置提示词缓存 提示词缓存是以处理请求的模型（在大多数提供者中还包括账户）为键进行管理的。当触发回退时，新的提供者/模型没有该对话的缓存前缀，因此后续请求需要以全额输入令牌费用重新读取整个历史记录，而无法享受约 75–90% 的折扣缓存费率。当回合结束并恢复使用主模型时也是如此——首次使用主模型处理的请求同样需要重新完整读取（除非主模型的缓存有效期尚未到期）。这是不可避免的——这是确保在故障期间仍能正常运行的代价——但这也解释了为何在多个提供者之间频繁切换的长时间对话，其成本会明显高于始终使用同一提供者的对话。

::

::info 每次回合独立处理，而非整个会话 回退机制是按回合生效的：每条新的用户消息都会以恢复主模型为起点。如果主模型在当前回合中发生故障，仅该回合会触发回退。收到下一条消息后，Hermes 会再次尝试使用主模型。在单个回合内，回退机制最多触发一次——如果回退也失败，则会进入常规错误处理流程（先尝试重试，再显示错误信息）。这样既能避免在单个回合内出现级联故障，又能让主模型在每个回合都有机会重新工作。

::

示例

以 OpenRouter 作为 Anthropic 原生模型的回退选项：

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

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

作为 OpenRouter 备用方案的 Nous Portal：

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

回退机制的适用场景

:::tip 主回退链没有对应的环境变量——必须通过 config.yaml 或 hermes fallback 进行配置。这是有意为之：回退配置属于关键设置，不应被过时的 shell 导出值覆盖。

::

辅助任务回退机制

Hermes 为各类辅助任务配备了独立的轻量级模型。每个任务都拥有专属的提供方解析链，该链即作为内置的回退系统。

具有独立提供方解析能力的任务

自动检测回退链

当任务的提供方被设置为 "auto"（默认值）时，Hermes 首先会尝试使用该辅助任务的主提供方及主模型。如果该路径不可用或随后出现资源不足类的错误，Hermes 会优先采用用户配置的回退策略，而非使用内置的发现链：

Main provider + main model → auxiliary.<task>.fallback_chain →
fallback_providers / fallback_model → built-in auxiliary discovery chain

当存在任务专用链时，其精度最高且表现最优。顶层的 fallback_providers 链与主智能体所使用的策略相同，因此针对 auto 模式下的辅助任务，同样适用仅免费资源或同提供商的回退规则。

内置文本提取链（压缩处理、网页提取、标题生成等功能）：

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

内置视觉检测链：

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

对于那些尚未定义特定任务或主备用策略的用户而言，这些内置的链便是一种便捷的备用方案。

配置辅助提供者

可以在 config.yaml 中为每个任务单独进行配置：

auxiliary:
  vision:
    provider: "auto"              # auto | openrouter | nous | codex | main | anthropic
    model: ""                     # e.g. "openai/gpt-4o"
    base_url: ""                  # direct endpoint (takes precedence over provider)
    api_key: ""                   # API key for base_url

  web_extract:
    provider: "auto"
    model: ""

  compression:
    provider: "auto"
    model: ""
    fallback_chain:              # optional, task-specific fallback policy
      - 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                                    # Same provider options as other auxiliary tasks
    model: google/gemini-3-flash-preview
    base_url: null                                    # Custom OpenAI-compatible endpoint

而主回退链所使用的是：

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
    # base_url: http://localhost:8000/v1             # Optional custom endpoint

辅助任务、压缩处理以及回退机制的运作方式完全相同：通过设置 provider 来指定负责处理请求的服务，通过设置 model 来选择对应的模型，而 base_url 用于指定自定义端点（该设置会覆盖 provider 的配置）。

辅助任务的提供者选项

这些选项仅适用于 auxiliary:、compression: 以及 fallback_providers: 这些配置项——对于顶层 model.provider 而言，"main" 并非有效值。若需使用自定义端点，可在 model: 部分中设置 provider: custom（详情请参阅AI 提供者）。

直接指定端点

对于任何辅助任务，只要设置 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。

辅助能力错误时的回退机制

当您明确指定辅助提供者（例如 auxiliary.vision.provider: glm）时，Hermes 会将其视为您的优先选择——但如果该提供者因能力限制错误（如 HTTP 402 需要支付、HTTP 429 每日额度耗尽、连接失败）而确实无法处理请求，Hermes 会通过分层回退机制来处理，而不会静默失败：

1. 主要辅助提供者——即您所配置的提供者（始终优先尝试）
2. auxiliary.<task>.fallback_chain——如果您自定义了该列表，则按此顺序尝试
3. 主代理提供者及模型——最后的安全保障措施（即使您未设置回退链，也会始终尝试）
4. 发出警告并重新抛出错误——如果所有层级都失败，Hermes 会以 WARNING 级别记录日志 Auxiliary <task>: ... 所有回退方式均已用尽，然后重新抛出原始错误

短暂的 HTTP 429 速率限制（带有 Retry-After: ... 头信息）被视为请求约束而非能力问题——它们会尊重您指定的提供者，不会触发回退机制。只有每日/每月额度耗尽、支付错误以及连接失败等情况才会绕过指定提供者的限制。

对于使用 provider: auto（未指定辅助提供者）的用户，系统会自动运行现有的自动检测流程来替代第 2–3 步。该流程的第一步即为主代理模型，因此这类用户无需任何配置即可获得相同的结果。

可选：按任务定制的回退链

如果您希望采用不同于“先尝试主代理模型”的回退顺序，可以明确配置 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 即可实现回退机制——主代理的安全防护机制依然会正常运行。仅当您明确希望采用不同于默认的顺序时，才使用该配置。

会触发回退的提供商配额错误

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 仍未触发回退机制，则属于缺陷——请附上完整的错误信息提交问题报告。

上下文压缩回退机制

上下文压缩功能通过 auxiliary.compression 配置块来指定由哪个模型及提供商负责执行摘要生成：

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

:::info 旧版本迁移 对于包含 compression.summary_model / compression.summary_provider / compression.summary_base_url 参数的旧配置，在首次加载时（配置版本为17）会自动迁移为 auxiliary.compression.* 格式。

::

如果无法找到用于压缩的提供者，Hermes 会直接跳过中间对话轮次而不会生成摘要，从而避免会话失败。

委派提供者覆盖机制

通过 delegate_task 生成的子代理会继承父代理的主备提供者链。您仍然可以将这些子代理路由到不同的主提供者与模型组合，以实现成本优化：

delegation:
  provider: "openrouter"                      # override provider for all subagents
  model: "google/gemini-3-flash-preview"      # override model
  # base_url: "http://localhost:1234/v1"      # or use a direct endpoint
  # api_key: "local-key"

如需完整的配置详情，请参阅子代理委托。

Cron作业提供者

当Cron作业创建代理时，它会继承您已配置的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）文档。