Hermes Agent 模型回退（Fallback）配置教程

一、什么是 Fallback Providers？

Hermes Agent 内置了一套完整的模型容灾机制——Fallback Providers（回退提供者）。当你正在使用的AI模型API遇到问题时，它会自动、无缝地切换到预先配置好的备选模型，整个过程你几乎感知不到。

这套机制解决了几个常见痛点：

• API额度用尽——免费API总有次数限制，用完即停？Fallback自动切到另一家
• 服务中断/过载——某个模型服务器返回HTTP 5xx或超时，自动换一个
• 认证失败——API Key过期或被封，不卡死，换备选
• 网络问题——某些模型在国内访问不稳定，fallback到稳定模型

二、三層容灾体系

Hermes Agent 实际上有三層容灾保护，Fallback Providers只是其中一層：

本文重点介绍第二层（Fallback Providers）的配置方法。

三、Fallback 触发条件

当主模型遇到以下错误时，Hermes会自动尝试fallback链中的下一个provider:model：

• HTTP 429 — 速率限制/配额用尽（最常见的情况）
• HTTP 402 — 付款需要（额度耗尽）
• HTTP 401/403 — 认证失败（API Key无效）
• HTTP 5xx — 服务端错误（过载或故障）
• HTTP 404 — 模型不存在或已下架
• 连接超时/断开 — 网络不可达
• 空响应或乱码 — API返回了不可用的内容

四、支持的 Provider 类型

以下提供商可以作为fallback备选：

五、配置方法（两种方式）

方式一：交互式命令（推荐）

在终端中运行以下命令：

# 交互式管理fallback链
hermes fallback

# 或直接添加一个备选（按提示选择provider和model）
hermes fallback add

# 查看当前fallback链
hermes fallback list

# 移除某个备选
hermes fallback remove

hermes fallback 命令会复用 hermes model 的provider选择器界面——同一个交互式菜单，按方向键选provider、选model即可。支持多个备选按顺序添加。

方式二：直接编辑 config.yaml

打开 ~/.hermes/config.yaml，在文件末尾或任意位置添加 fallback_providers 列表：

# 示例1：OpenRouter作为SenseNova的备选
model:
  provider: custom
  default: deepseek-v4-flash
  base_url: https://token.sensenova.cn/v1
  api_key: sk-xxx

fallback_providers:
  - provider: openrouter
    model: google/gemini-2.0-flash-001

# 示例2：多个备选链（顺序执行）
fallback_providers:
  - provider: openrouter
    model: google/gemini-2.0-flash-001
  - provider: deepseek
    model: deepseek-chat
  - provider: custom
    model: qwen2.5-14b
    base_url: http://localhost:8000/v1
    key_env: LOCAL_API_KEY

六、实际配置示例

场景：SenseNova Token Plan + OpenRouter 备选

这是我们在本服务器上的真实配置思路——主模型使用SenseNova Token Plan的免费API，如果额度耗尽或服务超时，自动切换到OpenRouter的免费额度模型：

场景：本地模型作为最后的兜底

如果你在本地跑了Ollama或vLLM，可以作为最后的兜底：

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: custom
    model: llama-3.1-70b
    base_url: http://localhost:8000/v1
    key_env: LOCAL_API_KEY

七、辅助任务（Auxiliary Tasks）的独立回退

Hermes的辅助任务——如视觉分析、上下文压缩、网页提取、技能搜索——各自有独立的provider回退链，与主模型互不干扰。

每种辅助任务的provider默认是 "auto"，自动按顺序尝试：

1. OpenRouter（如果有配置）
2. Nous Portal
3. 自定义端点
4. Codex OAuth
5. 其他API Key提供商（DeepSeek、Kimi、MiniMax等）

你也可以单独指定某个辅助任务使用特定provider：

# config.yaml 中单独配置辅助任务
auxiliary:
  vision:
    provider: auto        # auto | openrouter | nous | codex | main | 特定provider
    model: ""
    base_url: ""
    api_key: ""

  compression:
    provider: main        # 使用主模型（同一provider:model）

  web_extract:
    provider: openrouter
    model: google/gemini-2.0-flash-001

如果设置了 base_url，则完全绕过provider解析，直接发送请求到指定端点——适用于本地部署的视觉/文本模型。

八、后台任务与Cron的回退

通过 cronjob 工具创建的计划任务，也会继承主配置中的 fallback_providers 链。如果需要给某个cron任务使用不同的模型，可以在创建时单独指定：

# 创建cron任务时指定provider和model覆盖
cronjob(
    action="create",
    schedule="0 9 * * *",
    prompt="每日新闻摘要",
    model="google/gemini-2.0-flash-001",
    provider="openrouter"
)

九、排查与验证

配置完成后，如何确认fallback生效了？

1. 查看当前fallback链：终端运行 hermes fallback list
2. 直接测试：在终端运行 hermes chat -q "你好"，观察是否正常
3. 模拟故障：临时在主模型的 config.yaml 中填一个错误的API Key，然后发送一条消息——如果看到模型名称变为备选模型（例如从SenseNova变为OpenRouter），说明fallback生效了
4. 查看日志：grep -i "fallback" ~/.hermes/logs/errors.log

十、常见问题

❓ Fallback切换后对话历史会丢失吗？
不会。Fallback只切换模型和provider，你的对话历史、工具调用状态、上下文完整保留，切换是无缝的。

❓ 配置多个fallback，是按顺序尝试吗？
是的。列表中的第一个备选会最先尝试，如果它也失败了，继续尝试下一个，直到有一个成功。

❓ 会不会一直卡在fallback模型上？
不会。每一轮对话（每个用户消息）都会先尝试主模型，只有主模型失败才走fallback链。下一轮又给主模型一次机会。

❓ 同一轮对话中会多次fallback吗？
不会。在一轮对话内，Hermes只尝试fallback链一次。如果fallback也失败了，该轮会报错。下轮对话重新尝试主模型。这防止了"fallback循环风暴"。

❓ fallback_model（单数）和 fallback_providers（复数）有什么区别？
fallback_model 是旧版配置，只支持一个备选。新版统一用 fallback_providers（列表）支持多个备选。两者同时存在时，fallback_providers 优先。

❓ 使用SenseNova自定义provider，fallback支持吗？
支持。只要你的自定义provider在 model: 段中正确配置了 base_url 和 api_key，fallback链可以正常使用其他标准provider（如OpenRouter、DeepSeek）。