hermes教程-回退提供商

回退提供商

Hermes Agent 具有三层弹性机制，可在提供商出现问题时保持会话运行：

1. 凭证池 — 在同一提供商的多个 API 密钥之间轮换（优先尝试）
2. 主模型回退 — 当主模型失败时，自动切换到不同的提供商:模型
3. 辅助任务回退 — 为视觉、压缩和网页提取等辅助任务提供独立的提供商解析

凭证池处理同一提供商的轮换（例如多个 OpenRouter 密钥）。本页介绍跨提供商回退。两者都是可选的，且独立工作。

主模型回退

当您的主 LLM 提供商遇到错误（速率限制、服务器过载、身份验证失败、连接断开）时，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。缺少任一字段的条目将被忽略。

注意 — 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            # 包含 API 密钥的环境变量名

回退触发时机

当主模型因以下原因失败时，回退会自动激活：

• 速率限制（HTTP 429）— 在耗尽重试尝试后
• 服务器错误（HTTP 500、502、503）— 在耗尽重试尝试后
• 身份验证失败（HTTP 401、403）— 立即（重试无意义）
• 未找到（HTTP 404）— 立即
• 无效响应— 当 API 重复返回格式错误或空响应时

触发时，Hermes 会：

1. 解析回退提供商的凭证
2. 构建新的 API 客户端
3. 原地替换模型、提供商和客户端
4. 重置重试计数器并继续对话

切换是无缝的 — 您的对话历史、工具调用和上下文都会保留。代理会从它离开的地方继续，只是使用不同的模型。

信息 — 按轮次，而非按会话

回退是轮次作用域的：每个新用户消息都会恢复主模型。如果主模型在轮次中失败，回退仅在该轮次激活。下一条消息时，Hermes 会再次尝试主模型。在单个轮次内，回退最多激活一次 — 如果回退也失败，则正常错误处理接管（重试，然后错误消息）。这防止了轮次内的级联故障转移循环，同时让主模型每轮都有新的机会。

示例

将 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

回退生效范围

提示

主回退链没有环境变量 — 只能通过 config.yaml 或 hermes fallback 配置。这是有意为之：回退配置是一个深思熟虑的选择，不应被过时的 shell 导出覆盖。

辅助任务回退

Hermes 为辅助任务使用独立的轻量级模型。每个任务都有自己的提供商解析链，作为内置回退系统。

具有独立提供商解析的任务

自动检测链

当任务的提供商设置为 "auto"（默认）时，Hermes 首先尝试使用主提供商 + 主模型来处理该辅助任务。如果该路径不可用或稍后因容量类错误而失败，Hermes 现在会在使用内置发现链之前，优先考虑用户配置的回退策略：

主提供商 + 主模型 → auxiliary.<task>.fallback_chain →
fallback_providers / fallback_model → 内置辅助发现链

任务特定的链最精确，存在时优先。顶级 fallback_providers 链与主代理使用的策略相同，因此仅免费或同提供商回退规则也适用于 auto 模式下的辅助任务。

内置文本发现链（压缩、网页提取、标题生成等）：

OpenRouter → Nous Portal → 自定义端点 → Codex OAuth →
API 密钥提供商（z.ai、Kimi、MiniMax、Xiaomi MiMo、Hugging Face、Anthropic）→ 放弃

内置视觉发现链：

主提供商（如果支持视觉）→ OpenRouter → Nous Portal →
Codex OAuth → Anthropic → 自定义端点 → 放弃

这些内置链是为尚未声明任务特定或主回退策略的用户提供的便利回退。

配置辅助提供商

每个任务可以在 config.yaml 中独立配置：

auxiliary:
  vision:
    provider: "auto"              # auto | openrouter | nous | codex | main | anthropic
    model: ""                     # 例如 "openai/gpt-4o"
    base_url: ""                  # 直接端点（优先于 provider）
    api_key: ""                   # base_url 的 API 密钥

  web_extract:
    provider: "auto"
    model: ""

  compression:
    provider: "auto"
    model: ""
    fallback_chain:              # 可选，任务特定的回退策略
      - 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_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
## base_url: http://localhost:8000/v1             # 可选的自定义端点

所有三个 — auxiliary、compression、fallback — 工作方式相同：设置 provider 选择谁处理请求，model 选择哪个模型，base_url 指向自定义端点（覆盖 provider）。

辅助任务的提供商选项

这些选项仅适用于 auxiliary:、compression: 和 fallback_providers: 条目 — "main" 不是顶级 model.provider 的有效值。对于自定义端点，请在 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>: ... all fallbacks exhausted 并重新抛出原始错误

瞬时的 HTTP 429 速率限制（Retry-After: ...）被视为请求约束，而非容量问题 — 它们会尊重您明确的提供商选择，并且不会触发回退阶梯。只有每日/每月配额耗尽、付款错误和连接失败会绕过明确提供商的门控。

对于使用 provider: auto（无明确辅助提供商）的用户，现有的自动检测链会代替步骤 2-3 运行。其第一步已经是主代理模型，因此 auto 用户无需任何配置即可获得相同的结果。

可选：每个任务的回退链

如果您希望使用不同于“主代理模型优先”的回退顺序，请显式配置 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 未触发回退，那是一个 bug — 请使用确切的错误字符串提交 issue。

上下文压缩回退

上下文压缩使用 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 会丢弃中间对话轮次而不生成摘要，而不是使会话失败。

委派提供商覆盖

由 delegate_task 生成的子代理会继承父代理的主回退链。您仍然可以将子代理路由到不同的主提供商:模型对，以进行成本优化：

delegation:
  provider: "openrouter"                      # 覆盖所有子代理的提供商
  model: "google/gemini-3-flash-preview"      # 覆盖模型
## base_url: "http://localhost:1234/v1"      # 或使用直接端点
## api_key: "local-key"

有关完整配置详情，请参见 子代理委派。

定时任务提供商

定时任务在创建代理时会继承您配置的 fallback_providers 链（或旧版 fallback_model）。要为定时任务使用不同的主提供商，请在定时任务本身上配置 provider 和 model 覆盖：

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

有关完整配置详情，请参见 定时任务（Cron）。

总结