备用提供者

Hermes Agent 具有三层容错机制，可在提供者出现故障时确保您的会话持续运行：

凭证池 — 在同一提供者的多个 API 密钥之间轮换（优先尝试）
主模型备援 — 当您的主模型失败时，自动切换到不同提供者:模型组合
辅助任务备援 — 独立的提供者解析机制，用于视觉、压缩和网页提取等辅助任务

凭证池处理同一提供者的轮换（例如多个 OpenRouter 密钥）。本页面介绍跨提供者的备援机制。两者均为可选，且可独立工作。

主模型备援

当您的主大语言模型提供者遇到错误时——如速率限制、服务器过载、认证失败、连接中断——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`
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 客户端
就地替换模型、提供者和客户端
重置重试计数器并继续对话

切换过程无缝——您的对话历史、工具调用和上下文均被保留。代理将从它中断的位置继续，仅使用不同的模型。

一次性

备援在每个会话中最多触发一次。如果备援提供者也失败，将启用正常错误处理（重试，然后显示错误信息）。此举可防止级联故障循环。

示例

以 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 jobs）	✘（使用固定提供者运行）
辅助任务（视觉、压缩）	✘（使用其自身的提供者链——见下文）

提示

fallback_model 无环境变量配置——它仅通过 config.yaml 进行设置。这是有意为之：备援配置是一项明确选择，不应由过时的 shell 导出变量覆盖。

辅助任务备援

Hermes 使用独立的轻量级模型处理辅助任务。每个任务都有自己的提供者解析链，构成内置的备援系统。

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

任务	功能	配置键
视觉	图像分析、浏览器截图	`auxiliary.vision`
网页提取	网页摘要	`auxiliary.web_extract`
压缩	上下文压缩摘要	`auxiliary.compression` 或 `compression.summary_provider`
会话搜索	历史会话摘要	`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, 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 模式。上下文压缩使用其自身的顶层配置块：

compression:
  summary_provider: main                             # Same provider options as auxiliary tasks
  summary_model: google/gemini-3-flash-preview
  summary_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。

上下文压缩备用机制

上下文压缩除了辅助系统外，还保留了旧版配置路径：

compression:
  summary_provider: "auto"                    # auto | openrouter | nous | main
  summary_model: "google/gemini-3-flash-preview"

这等价于配置 auxiliary.compression.provider 和 auxiliary.compression.model。如果两者都已设置，则 auxiliary.compression 的值具有优先权。

如果压缩任务没有可用的提供者，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"

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

定时任务提供者

定时任务在执行时使用当时配置的提供者。它们不支持备用模型。若需为定时任务使用不同提供者，请在任务本身配置 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` 或 `compression.summary_provider`
会话搜索	自动检测链	`auxiliary.session_search`
技能中心	自动检测链	`auxiliary.skills_hub`
MCP 助手	自动检测链	`auxiliary.mcp`
内存清除	自动检测链	`auxiliary.flush_memories`
委派	仅提供者覆盖（无自动备用）	`delegation.provider` / `delegation.model`
定时任务	仅任务级提供者覆盖（无自动备用）	任务级 `provider` / `model`

主模型备援​

配置​

支持的提供者​

自定义端点备援​

备援触发条件​

示例​

备援适用场景​

辅助任务备援​

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

自动检测链​

配置辅助提供者​

辅助任务的提供者选项​

直接端点覆盖​

上下文压缩备用机制​

委派提供者覆盖​

定时任务提供者​

总结​