备用提供商

Hermes Agent 内置了三层容错机制，用来在提供商出现故障时尽量保证会话继续运行：

凭证池 — 在同一提供商的多个 API 密钥之间轮换（优先尝试）
主模型降级 — 当主模型失败时，自动切换到另一个“提供商:模型”组合，会话不中断
辅助任务降级 — 视觉、压缩、网页提取等辅助任务使用独立的提供商解析链

凭证池负责处理同一提供商内部的密钥轮换，例如多个 OpenRouter 密钥；而本页介绍的是跨提供商的降级机制。两者都是可选配置，而且彼此独立。

主模型降级

当你的主 LLM 提供商出现错误，例如限流、服务器过载、认证失败或连接中断时，Hermes 可以在当前会话里自动切换到备用“提供商:模型”组合，而不会丢失对话内容。

配置方法

在 ~/.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          # env var name containing the API key

降级触发条件

当主模型因以下情况失败时，降级将自动激活：

限流（HTTP 429）——在耗尽重试次数后
服务器错误（HTTP 500、502、503）——在耗尽重试次数后
认证失败（HTTP 401、403）——立即触发（无需重试）
未找到资源（HTTP 404）——立即触发
无效响应——当 API 反复返回格式错误或空响应时

触发后，Hermes 将执行以下操作：

解析备用提供商的凭证
构建新的 API 客户端
就地替换模型、提供商和客户端
重置重试计数器，并继续对话

切换过程是无缝的，你的对话历史、工具调用和上下文都会完整保留。代理只是在断点处继续执行，但背后换成了另一套模型。

一次性

降级在单个会话中最多只会触发一次。如果备用提供商也失败，系统就会回到常规错误处理流程（重试后展示错误信息），以避免级联失败循环。

示例

Anthropic 原生模型的 OpenRouter 降级：

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

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

OpenRouter 的 Nous Portal 降级：

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）	✘（以固定提供商运行）
辅助任务（视觉、压缩等）	✘（使用它们自己的提供商链，见下文）

tip

fallback_model 无对应环境变量——它仅通过 config.yaml 配置。这是有意设计：降级配置是明确选择，不应被旧的 shell 环境变量覆盖。

辅助任务降级

Hermes 会使用独立的轻量级模型来处理辅助任务。每类任务都有自己的提供商解析链，这本身就构成了一套内置降级系统。

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

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

自动检测链

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

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

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

如果最终解析出来的提供商在调用时失败，Hermes 还会做一次内部重试：只要当前提供商不是 OpenRouter，且你没有显式设置 base_url，它就会把 OpenRouter 当成最后一道兜底方案。

配置辅助任务提供商

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

  session_search:
    provider: "auto"
    model: ""

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

  flush_memories:
    provider: "auto"
    model: ""

上面这些任务都遵循同一套 提供商 / 模型 / base_url 配置模式。上下文压缩的配置位于 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_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4
  # base_url: http://localhost:8000/v1               # Optional custom endpoint

这三类配置，也就是辅助任务、压缩和主模型降级，工作方式其实是一致的：provider 用来选提供商，model 用来选具体模型，base_url 则用于覆盖到自定义端点。

辅助任务提供商选项

这些选项只适用于 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 创建的子代理不会使用主模型的备用链。但你仍然可以通过单独指定提供商:模型组合来优化成本：

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 jobs）执行时使用任务自身配置的提供商，不支持主模型备用链。如果你希望某个定时任务单独使用不同的提供商，可以在任务定义里覆盖 provider 和 model：

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

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

总结

功能	备用机制	配置位置
主代理模型	`config.yaml` 中的 `fallback_model` — 错误时单次故障转移	`fallback_model:`（顶层）
视觉处理	自动检测链 + 内部 OpenRouter 重试	`auxiliary.vision`
网页提取	自动检测链 + 内部 OpenRouter 重试	`auxiliary.web_extract`
上下文压缩	自动检测链，若不可用则降级为无摘要	`auxiliary.compression`
会话搜索	自动检测链	`auxiliary.session_search`
技能中心	自动检测链	`auxiliary.skills_hub`
MCP 辅助工具	自动检测链	`auxiliary.mcp`
内存清理	自动检测链	`auxiliary.flush_memories`
委派	仅支持提供商覆盖（无自动备用）	`delegation.provider` / `delegation.model`
定时任务	仅支持任务级提供商覆盖（无自动备用）	任务级别的 `provider` / `model`

主模型降级​

配置方法​

支持的提供商​

自定义端点降级​

降级触发条件​

示例​

降级适用场景​

辅助任务降级​

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

自动检测链​

配置辅助任务提供商​

辅助任务提供商选项​

直接端点覆盖​

上下文压缩​

委派提供商覆盖​

定时任务提供商​

总结​