备用提供者

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

tip

没有环境变量用于配置 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` 生成的子代理不会使用主备模型。然而，它们可以被路由到不同的提供商:model 组合以实现成本优化：

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`

主模型降级​

配置方法​

支持的提供者​

自定义端点降级​

降级触发条件​

示例​

降级适用范围​

辅助任务降级​

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

自动检测链​

配置辅助提供者​

辅助任务的提供者选项​

直接端点覆盖​

上下文压缩降级​

委派提供者覆盖由 delegate_task 生成的子代理 不会 使用主备模型。然而，它们可以被路由到不同的提供商:model 组合以实现成本优化：​

定时任务提供方​

总结​