回退提供商

Hermes Agent 有三层弹性机制，在提供商遇到问题时保持会话正常运行：

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

凭证池处理同一提供商的轮换（例如多个 OpenRouter 密钥）。本页介绍跨提供商回退。两者都是可选的，可以独立工作。

主模型回退

当主 LLM 提供商遇到错误——速率限制、服务器过载、认证失败、连接中断——Hermes 可以在会话中途自动切换到备用提供商:模型对，而不会丢失对话。

配置

最简便的方式是使用交互式管理器：

hermes fallback

hermes fallback 复用 hermes model 中的提供商选择器——相同的提供商列表、相同的凭证提示、相同的验证。按 a 添加回退，↑/↓ 重新排序，d 删除，q 保存并退出。更改持久保存在 config.yaml 的 model.fallback_providers 下。

如果你更想直接编辑 YAML，可在 ~/.hermes/config.yaml 中添加 fallback_model 部分：

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

provider 和 model 都是必填项。如果任一缺失，回退被禁用。

fallback_model 与 fallback_providers

fallback_model（单数）是旧版单回退键——Hermes 仍兼容它以向后兼容。fallback_providers（复数，列表）支持按顺序尝试多个回退；hermes fallback 写入此键。当两者都设置时，Hermes 合并它们，fallback_providers 优先。

支持的提供商

提供商	值	要求
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`
NVIDIA NIM	`nvidia`	`NVIDIA_API_KEY`（可选：`NVIDIA_BASE_URL`）
GMI Cloud	`gmi`	`GMI_API_KEY`（可选：`GMI_BASE_URL`）
StepFun	`stepfun`	`STEPFUN_API_KEY`（可选：`STEPFUN_BASE_URL`）
Ollama Cloud	`ollama-cloud`	`OLLAMA_API_KEY`
Google Gemini（OAuth）	`google-gemini-cli`	`hermes model`（Google OAuth；可选：`HERMES_GEMINI_PROJECT_ID`）
Google AI Studio	`gemini`	`GOOGLE_API_KEY`（别名：`GEMINI_API_KEY`）
xAI（Grok）	`xai`（别名 `grok`）	`XAI_API_KEY`（可选：`XAI_BASE_URL`）
AWS Bedrock	`bedrock`	标准 boto3 认证（`AWS_REGION` + `AWS_PROFILE` 或 `AWS_ACCESS_KEY_ID`）
Qwen Portal（OAuth）	`qwen-oauth`	`hermes model`（Qwen Portal OAuth；可选：`HERMES_QWEN_BASE_URL`）
MiniMax（OAuth）	`minimax-oauth`	`hermes model`（MiniMax 门户 OAuth）
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`
GMI Cloud	`gmi`	`GMI_API_KEY`
Alibaba / DashScope	`alibaba`	`DASHSCOPE_API_KEY`
Alibaba Coding Plan	`alibaba-coding-plan`	`ALIBABA_CODING_PLAN_API_KEY`（回退到 `DASHSCOPE_API_KEY`）
Kimi / Moonshot（中国）	`kimi-coding-cn`	`KIMI_CN_API_KEY`
StepFun	`stepfun`	`STEPFUN_API_KEY`
Tencent TokenHub	`tencent-tokenhub`	`TOKENHUB_API_KEY`
Azure AI Foundry	`azure-foundry`	`AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL`
LM Studio（本地）	`lmstudio`	`LM_API_KEY`（或本地无密钥） + `LM_BASE_URL`
Hugging Face	`huggingface`	`HF_TOKEN`
自定义端点	`custom`	`base_url` + `key_env`（见下方）

自定义端点回退

对于自定义 OpenAI 兼容端点，添加 base_url 和可选的 key_env：

fallback_model:
  provider: custom
  model: my-local-model
  base_url: http://localhost:8000/v1
  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 客户端
原地交换模型、提供商和客户端
重置重试计数器并继续对话

切换是无缝的——你的对话历史、工具调用和上下文都保留。Agent 从它停止的地方继续，只是使用不同的模型。

每轮次，而非每会话

回退是轮次范围的：每条新用户消息都从恢复的主模型开始。如果主模型在轮次中途失败，回退仅在该轮次激活。在下一条消息时，Hermes 再次尝试主模型。在单个轮次内，回退最多激活一次——如果回退也失败，正常的错误处理接管（重试，然后错误消息）。这防止了轮次内的级联故障转移，同时在每个轮次给主模型一个新的机会。

示例

以 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
  key_env: LOCAL_API_KEY

以 Codex OAuth 作为回退：

fallback_model:
  provider: openai-codex
  model: gpt-5.3-codex

回退支持的场景

场景	是否支持回退
CLI 会话	✔
消息网关（Telegram、Discord 等）	✔
子 Agent 委派	✘（子 Agent 不继承回退配置）
定时任务	✘（使用固定提供商运行）
辅助任务（视觉、压缩）	✘（使用自己的提供商链——见下方）

提示

fallback_model 没有对应的环境变量——它只能通过 config.yaml 配置。这是有意为之：回退配置是一个深思熟虑的选择，不应被过时的 shell 导出变量覆盖。

辅助任务回退

Hermes 为副任务使用独立的轻量级模型。每个任务都有自己的提供商解析链，充当内置回退系统。

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

任务	功能	配置键
视觉	图像分析、浏览器截图	`auxiliary.vision`
网页提取	网页摘要	`auxiliary.web_extract`
压缩	上下文压缩摘要	`auxiliary.compression`
会话搜索	过去会话摘要	`auxiliary.session_search`
技能中心	技能搜索和发现	`auxiliary.skills_hub`
MCP	MCP 辅助操作	`auxiliary.mcp`
审批	智能命令审批分类	`auxiliary.approval`
标题生成	会话标题摘要	`auxiliary.title_generation`
Triage 规格化	`hermes kanban specify` / 仪表板 ✨ 按钮 — 将 triage 一行描述扩展为完整规格	`auxiliary.triage_specifier`

自动检测链

当任务的提供商设置为 "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: ""
    timeout: 30
    max_concurrency: 3
    extra_body: {}

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

上面每个任务都遵循相同的 provider / 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

对于 auxiliary.session_search，Hermes 还支持：

max_concurrency 限制一次运行多少个会话摘要
extra_body 在摘要调用中传递特定于提供商的 OpenAI 兼容请求字段

示例：

auxiliary:
  session_search:
    provider: main
    model: glm-4.5-air
    max_concurrency: 2
    extra_body:
      enable_thinking: false

如果你的提供商不支持原生 OpenAI 兼容的推理控制字段，extra_body 对那部分不会有帮助；在这种情况下，max_concurrency 仍然有助于减少请求突发 429。

三者——辅助、压缩、回退——工作方式相同：设置 provider 选择处理请求的人，model 选择使用哪个模型，base_url 指向自定义端点（覆盖 provider）。

辅助任务的提供商选项

这些选项仅适用于 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"`	使用主 Agent 使用的任何提供商（仅辅助任务）	已配置活跃的主提供商
`"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 生成的子 Agent 不使用主回退模型。但是，它们可以被路由到不同的提供商:模型对以优化成本：

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"

完整配置详情参见子 Agent 委派。

定时任务提供商

定时任务使用执行时配置的任何提供商运行。它们不支持回退模型。要为定时任务使用不同的提供商，在定时任务本身上配置 provider 和 model 覆盖：

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

完整配置详情参见定时任务（Cron）。

总结

功能	回退机制	配置位置
主 Agent 模型	`fallback_model`（config.yaml）——出错时每轮次故障转移（每轮次恢复主模型）	`fallback_model:`（顶层）
视觉	自动检测链 + 内部 OpenRouter 重试	`auxiliary.vision`
网页提取	自动检测链 + 内部 OpenRouter 重试	`auxiliary.web_extract`
上下文压缩	自动检测链，不可用时降级为无摘要	`auxiliary.compression`
会话搜索	自动检测链	`auxiliary.session_search`
技能中心	自动检测链	`auxiliary.skills_hub`
MCP 辅助	自动检测链	`auxiliary.mcp`
审批分类	自动检测链	`auxiliary.approval`
标题生成	自动检测链	`auxiliary.title_generation`
Triage 规格化	自动检测链	`auxiliary.triage_specifier`
委派	仅提供商覆盖（无自动回退）	`delegation.provider` / `delegation.model`
定时任务	仅每任务提供商覆盖（无自动回退）	每任务 `provider` / `model`

主模型回退​

配置​

支持的提供商​

自定义端点回退​

回退触发条件​

示例​

回退支持的场景​

辅助任务回退​

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

自动检测链​

配置辅助提供商​

辅助任务的提供商选项​

直接端点覆盖​

上下文压缩回退​

委派提供商覆盖​

定时任务提供商​

总结​