Fallback Providers

Hermes Agent 具有三层弹性机制，确保当提供商出现问题时会话仍能继续运行：

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

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

主模型回退

当您的主 LLM 提供商遇到错误时——速率限制、服务器过载、认证失败、连接中断——Hermes 可以在会话中途自动切换到备用 provider:model 对，而不会丢失您的对话。

配置

在 ~/.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
Xiaomi MiMo	xiaomi	XIAOMI_API_KEY
Arcee AI	arcee	ARCEEAI_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：

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

切换是无缝的——您的对话历史、工具调用和上下文都被保留。智能体从中断处继续，只是使用不同的模型。

One-Shot

回退每个会话最多激活一次。如果回退提供商也失败，则正常的错误处理接管（重试，然后错误消息）。这可以防止级联故障转移循环。

示例

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 等） | ✔ | | | 子代理委托 | ✘（子代理不继承回退配置） | | | Cron 作业 | ✘（使用固定提供商运行） | | | 辅助任务（视觉、压缩） | ✘（使用自己的提供商链——见下文） | |

提示

fallback_model 没有环境变量——它只能通过 config.yaml 配置。这是刻意的：回退配置是一个深思熟虑的选择，不应该被过时的 shell 导出覆盖。

---

辅助任务回退

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

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

任务	功能	配置键
视觉	图像分析、浏览器截图	auxiliary.vision
网页提取	网页摘要	auxiliary.web_extract
压缩	上下文压缩摘要	auxiliary.compression
会话搜索	过去会话摘要	auxiliary.session_search
Skills Hub	技能搜索和发现	auxiliary.skills_hub
MCP	MCP 辅助操作	auxiliary.mcp
内存刷新	内存整合	auxiliary.flush_memories

自动检测链

当任务的提供商设置为 "auto"（默认值）时，Hermes 按顺序尝试提供商直到成功：

对于文本任务（压缩、网页提取等）：

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

对于视觉任务：

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

如果解析的提供商的调用失败，Hermes 也有内部重试：如果提供商不是 OpenRouter 且未设置显式 base_url，它会尝试 OpenRouter 作为最后手段的回退。

配置辅助提供商

每个任务都可以在 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: ""

  session_search:
    provider: "auto"
    model: ""

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

  flush_memories:
    provider: "auto"
    model: ""

上述每个任务都遵循相同的 provider / model / base_url 模式。上下文压缩在 auxiliary.compression 下配置：

auxiliary:
  compression:
    provider: main                                    # 与其他辅助任务相同的提供商选项
    model: google/gemini-3-flash-preview
    base_url: null                                    # 自定义 OpenAI 兼容端点

回退模型使用：

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4
  # base_url: http://localhost:8000/v1               # 可选自定义端点

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

辅助任务的提供商选项

这些选项仅适用于 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"	使用主智能体使用的任何提供商（仅限辅助任务）	配置了活动的主提供商
"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。

---

上下文压缩回退

上下文压缩使用 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 生成的子代理不使用主回退模型。但是，它们可以被路由到不同的 provider:model 对以优化成本：

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

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

---

Cron 作业提供商

Cron 作业使用执行时配置的提供商运行。它们不支持回退模型。要为 cron 作业使用不同的提供商，请在 cron 作业本身上配置 provider 和 model 覆盖：

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

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

---

总结

功能	回退机制	配置位置
主智能体模型	fallback_model in config.yaml — 错误时一次性故障转移	fallback_model:（顶级）
视觉	自动检测链 + 内部 OpenRouter 重试	auxiliary.vision
网页提取	自动检测链 + 内部 OpenRouter 重试	auxiliary.web_extract
上下文压缩	自动检测链，不可用了降级为无摘要	auxiliary.compression
会话搜索	自动检测链	auxiliary.session_search
Skills hub	自动检测链	auxiliary.skills_hub
MCP 辅助	自动检测链	auxiliary.mcp
内存刷新	自动检测链	auxiliary.flush_memories
委托	仅提供商覆盖（无自动回退）	delegation.provider / delegation.model
Cron 作业	仅每个作业的提供商覆盖（无自动回退）	每个作业的 provider / model