Hermes备用提供

概述

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

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

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

主模型备援

当主大语言模型提供者遇到错误时——如速率限制、服务器过载、认证失败、连接中断——Hermes Agent 可在会话中自动切换至备用提供者:模型组合，而不会丢失对话。

配置

在 ~/.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   # 包含 API 密钥的环境变量名称

备援触发条件

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

• 速率限制（HTTP 429）——在耗尽重试尝试后
• 服务器错误（HTTP 500、502、503）——在耗尽重试尝试后
• 认证失败（HTTP 401、403）——立即触发（重试无意义）
• 未找到（HTTP 404）——立即触发
• 无效响应——当 API 反复返回格式错误或空响应时

触发后，Hermes 将：

1. 解析备援提供者的凭证
2. 构建新的 API 客户端
3. 就地替换模型、提供者和客户端
4. 重置重试计数器并继续对话

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

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

配置示例

以 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 等）	✔
子 Agent 委派	✘（子 Agent 不继承备援配置）
定时任务（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: ""                      # 例如 "openai/gpt-4o"
    base_url: ""                   # 直接端点（优先于provider）
    api_key: ""                    # 自定义端点的 API 密钥
  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: ""

上下文压缩使用其自身的顶层配置块：

compression:
  summary_provider: main                    # 与辅助任务相同的 provider 选项
  summary_model: google/gemini-3-flash-preview
  summary_base_url: null                    # 自定义 OpenAI 兼容端点

备用模型使用：

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4
  # base_url: http://localhost:8000/v1      # 可选的自定义端点

辅助任务的提供者选项

提供者	描述	要求
"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。

上下文压缩备用机制

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

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

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

如果压缩任务没有可用的提供者，Hermes 会丢弃中间的对话回合而不生成摘要，而不是导致会话失败。

委派提供者覆盖

由 delegate_task 启动的子 Agent 不使用主备用模型。但它们可以被路由到不同的提供者:模型组合，以实现成本优化：

delegation:
  provider: "openrouter"                      # 覆盖所有子代理的 provider
  model: "google/gemini-3-flash-preview"      # 覆盖 model
  # base_url: "http://localhost:1234/v1"      # 或使用直接端点
  # api_key: "local-key"

定时任务提供者

定时任务在执行时使用当时配置的提供者。它们不支持备用模型。若需为定时任务使用不同提供者，请在任务本身配置 provider 和 model 覆盖：

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

总结

功能	备用机制	配置位置
主 Agent 模型	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