后备大模型提供商（provider）

Hermes Agent 提供三层韧性机制，帮助你的会话在 大模型提供商（provider） 出问题时仍能继续运行：

1. Credential pools — 在同一个 大模型提供商（provider） 内部轮换多个 API key（优先尝试）
2. 主模型 fallback — 当主模型失败时，自动切换到另一个 provider:model
3. 辅助任务 fallback — 对视觉、压缩、网页提取等辅助任务采用独立的大模型提供商（provider）解析链

Credential pools 解决的是同 大模型提供商（provider） 轮换；本页讲的是跨 大模型提供商（provider） fallback。两者互不依赖，也都不是必须配置。

主模型 fallback

当你的主 LLM 大模型提供商（provider） 遇到问题，例如限流、服务端过载、认证失败、连接中断时，Hermes 可以在不中断当前会话的情况下自动切换到备用 provider:model 组合。

配置

在 ~/.hermes/config.yaml 中加入 fallback_model：

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

provider 与 model 都必须填写，缺一则 fallback 不生效。

支持的 providers

支持范围包括 AI Gateway、OpenRouter、Nous Portal、OpenAI Codex、GitHub Copilot、Anthropic、z.ai / GLM、Kimi / Moonshot、MiniMax、DeepSeek、NVIDIA NIM、Ollama Cloud、Google Gemini、xAI、AWS Bedrock、Qwen Portal、OpenCode、Kilo Code、Xiaomi、Arcee、Alibaba、Hugging Face 以及 custom 自定义端点。

自定义端点 fallback

如果你要回退到自定义 OpenAI 兼容端点，可配置 base_url 以及可选的 key_env：

fallback_model:
  provider: custom
  model: my-local-model
  base_url: http://localhost:8000/v1
  key_env: MY_LOCAL_KEY

何时触发 fallback

以下情况会自动触发：

• 429 限流（重试耗尽后）
• 500 / 502 / 503 服务端错误（重试耗尽后）
• 401 / 403 认证失败（立即切换）
• 404 模型 / 端点不存在（立即切换）
• 无效响应（返回内容持续为空或结构损坏）

触发后，Hermes 会：

1. 解析 fallback 大模型提供商（provider） 的凭据
2. 构建新的 API client
3. 原地替换 model、provider 和 client
4. 重置重试计数并继续当前对话

整个切换过程对会话是透明的。已有对话历史、工具调用和上下文都会保留，只是底层模型变了。

Per-Turn, Not Per-Session

Fallback 是 按轮次生效 的。每条新用户消息都会先恢复使用主模型；如果主模型在该轮中失败，则仅在这一轮内切换到 fallback。到了下一轮，Hermes 仍会再次尝试主模型。单轮中最多只会触发一次 fallback；如果 fallback 自己也失败，就回到常规错误处理流程。

示例

Anthropic 原生 → OpenRouter fallback：

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

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

OpenRouter → Nous Portal fallback：

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

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

云模型 → 本地模型 fallback：

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

主 fallback 适用范围

场景	是否支持
CLI 会话	✔
消息网关（Telegram、Discord 等）	✔
子智能体 delegation	✘
Cron 任务	✘
辅助任务（视觉、压缩等）	✘（它们有独立链路）

提示

fallback_model 没有环境变量配置入口，只能通过 config.yaml 配置。这是有意设计，避免一个过期 shell export 不小心改变 fallback 行为。

---

辅助任务 fallback

Hermes 会为辅助任务使用独立的轻量模型。每类任务都有自己的大模型提供商（provider）解析链，可视为内建 fallback 机制。

具备独立 大模型提供商（provider） 解析的任务

任务	作用	配置键
Vision	图片分析、浏览器截图	auxiliary.vision
Web Extract	网页摘要	auxiliary.web_extract
Compression	上下文压缩摘要	auxiliary.compression
Session Search	历史会话摘要	auxiliary.session_search
Skills Hub	技能搜索与发现	auxiliary.skills_hub
MCP	MCP 辅助操作	auxiliary.mcp
Memory Flush	记忆归并	auxiliary.flush_memories
Approval	智能命令审批分类	auxiliary.approval
Title Generation	会话标题生成	auxiliary.title_generation

自动检测链

当某项任务的 大模型提供商（provider） 设置为 "auto"（默认）时，Hermes 会按顺序尝试不同 provider，直到有一个可用。

文本任务（压缩、网页提取等）的链路大致是：

OpenRouter → Nous Portal → Custom endpoint → Codex OAuth →
API-key 大模型提供商（provider） → give up

视觉任务的链路大致是：

Main 大模型提供商（provider） (if vision-capable) → OpenRouter → Nous Portal →
Codex OAuth → Anthropic → Custom endpoint → give up

如果解析出来的 大模型提供商（provider） 在调用时失败，Hermes 还会做一层内部重试：如果当前 大模型提供商（provider） 不是 OpenRouter，且没有显式设置 base_url，就会把 OpenRouter 作为最后兜底再试一次。

配置辅助 providers

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

auxiliary:
  vision:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""

  web_extract:
    provider: "auto"
    model: ""

  compression:
    provider: "auto"
    model: ""

三类配置逻辑一致：provider 决定谁来处理请求，model 选择具体模型，base_url 用于覆盖成自定义端点（优先级高于 provider）。

大模型提供商（provider） 可选值

这些值适用于 auxiliary:、compression: 与 fallback_model:，但 main 不能用于顶层 model.provider。

Provider	说明
"auto"	按顺序依次尝试（默认）
"openrouter"	强制使用 OpenRouter
"nous"	强制使用 Nous Portal
"codex"	强制使用 Codex OAuth
"main"	使用主智能体当前 provider（仅辅助任务可用）
"anthropic"	强制使用 Anthropic 原生

Direct Endpoint Override

若为某项辅助任务设置了 base_url，Hermes 就会跳过 大模型提供商（provider） 解析，直接把请求发送到该端点：

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url 的优先级高于 provider。若 api_key 未设置，则会回退到 OPENAI_API_KEY，但不会复用 OPENROUTER_API_KEY。

---

上下文压缩 fallback

上下文压缩由 auxiliary.compression 控制：

auxiliary:
  compression:
    provider: "auto"
    model: "google/gemini-3-flash-preview"

Legacy migration

旧配置中的 compression.summary_model / compression.summary_provider / compression.summary_base_url 会在首次加载时自动迁移到 auxiliary.compression.*。

如果压缩任务没有任何可用 provider，Hermes 会直接丢弃中间轮次而不生成摘要，而不会让整个会话失败。

---

Delegation 大模型提供商（provider）覆盖

由 delegate_task 启动的子智能体不会使用主 fallback model。不过你可以为全部子智能体单独指定 provider:model，以便优化成本：

delegation:
  provider: "openrouter"
  model: "google/gemini-3-flash-preview"

详见 Subagent Delegation。

---

Cron 任务的大模型提供商（provider）

Cron 任务会使用执行时的 大模型提供商（provider） 配置，不支持自动 fallback model。如需让某个 cron 任务使用特定 provider，可在任务本身设置：

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

详见 Scheduled Tasks (Cron)。

---

总结

功能	Fallback 机制	配置位置
主智能体模型	fallback_model；按轮次生效	顶层 fallback_model:
Vision	自动检测链 + OpenRouter 最后重试	auxiliary.vision
Web extraction	自动检测链 + OpenRouter 最后重试	auxiliary.web_extract
Context compression	自动检测链；无可用 大模型提供商（provider） 时退化为不做摘要	auxiliary.compression
Session search	自动检测链	auxiliary.session_search
Skills hub	自动检测链	auxiliary.skills_hub
MCP helpers	自动检测链	auxiliary.mcp
Memory flush	自动检测链	auxiliary.flush_memories
Approval classification	自动检测链	auxiliary.approval
Title generation	自动检测链	auxiliary.title_generation
Delegation	仅支持 大模型提供商（provider） override，无自动 fallback	delegation.provider / delegation.model
Cron jobs	仅支持任务级 大模型提供商（provider） override，无自动 fallback	per-job provider / model