备用提供商

Hermes Agent 有三层弹性机制，可以在提供商出现问题时保持你的会话继续运行：

1. 凭据池 —— 在同一提供商的多个 API key 之间轮换（最先尝试）
2. 主模型备用 —— 当主模型失败时，自动切换到另一个 provider:model
3. 辅助任务备用 —— 针对视觉、压缩和网页提取等旁路任务，进行独立的提供商解析

凭据池处理同一提供商内的轮换（例如多个 OpenRouter key）。本页介绍跨提供商备用机制。两者都是可选的，并且可以独立工作。

主模型备用

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

配置

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

hermes fallback

hermes fallback 会复用 hermes model 中的提供商选择器 —— 相同的提供商列表、相同的凭据提示、相同的验证。使用子命令 add、list（别名 ls）、remove（别名 rm）和 clear 来管理备用链。更改会持久化到 config.yaml 顶层的 fallback_providers: 列表中。

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

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

provider 和 model 都是必需的。如果缺少其中任何一个，备用机制将被禁用。

fallback_model vs fallback_providers

fallback_model（单数）是旧版的单一备用 key —— Hermes 仍然支持它以保持向后兼容。fallback_providers（复数，列表）支持按顺序尝试多个备用提供商；hermes fallback 会写入这个 key。当两者都设置时，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）
xAI Grok OAuth（SuperGrok）	xai-oauth（别名 grok-oauth）	hermes model → xAI Grok OAuth（浏览器登录；SuperGrok 订阅）
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 portal 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（或本地无 key）+ LM_BASE_URL
Hugging Face	huggingface	HF_TOKEN
Custom endpoint	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              # 包含 API key 的环境变量名称

备用何时触发

当主模型出现以下失败时，备用机制会自动激活：

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

触发后，Hermes 会：

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

切换是无缝的 —— 你的对话历史、工具调用和上下文都会被保留。Agent 会从刚才停止的位置继续，只是改用不同的模型。

按轮次，而不是按会话

Fallback 是按 turn 作用的：每条新的用户消息都会从主模型重新开始。如果主模型在某一轮中途失败，fallback 只会在该轮激活。下一条消息时，Hermes 会再次尝试主模型。在单个 turn 内，fallback 最多激活一次 —— 如果备用模型也失败，则接管的是正常错误处理流程（重试，然后返回错误消息）。这可以防止在单个 turn 中出现级联故障转移循环，同时让主模型在每一轮都有重新尝试的机会。

示例

将 OpenRouter 作为 Anthropic native 的备用：

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

Fallback 适用范围

上下文	是否支持 Fallback
CLI sessions	✔
Messaging gateway（Telegram、Discord 等）	✔
Subagent delegation	✘（subagents 不会继承 fallback 配置）
Cron jobs	✘（使用固定提供商运行）
Auxiliary tasks（视觉、压缩）	✘（使用自己的提供商链 —— 见下方）

提示

fallback_model 没有对应的环境变量 —— 它只能通过 config.yaml 配置。这是有意设计的：fallback 配置是一种明确选择，不应该被陈旧的 shell export 覆盖。

辅助任务备用

Hermes 会为旁路任务使用独立的轻量级模型。每个任务都有自己的提供商解析链，该链本身就是一种内置备用系统。

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

任务	作用	配置 Key
Vision	图片分析、浏览器截图	auxiliary.vision
Web Extract	网页摘要	auxiliary.web_extract
Compression	上下文压缩摘要	auxiliary.compression
Session Search	过去会话摘要	auxiliary.session_search
Skills Hub	Skill 搜索与发现	auxiliary.skills_hub
MCP	MCP 辅助操作	auxiliary.mcp
Approval	智能命令审批分类	auxiliary.approval
Title Generation	会话标题摘要	auxiliary.title_generation
Triage Specifier	hermes kanban specify / dashboard ✨ 按钮 —— 将一句话 triage 任务扩展成真正的 spec	auxiliary.triage_specifier

自动检测链

当某个任务的 provider 设置为 "auto"（默认）时，Hermes 会按顺序尝试提供商，直到某个提供商可用：

对于文本任务（compression、web extract 等）：

OpenRouter → Nous Portal → Custom endpoint → Codex OAuth →
API-key providers（z.ai、Kimi、MiniMax、Xiaomi MiMo、Hugging Face、Anthropic）→ 放弃

对于视觉任务：

Main provider（如果支持视觉）→ OpenRouter → Nous Portal →
Codex OAuth → Anthropic → Custom endpoint → 放弃

如果解析出来的 provider 在调用时失败，Hermes 还会有一个内部重试：如果该 provider 不是 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: ""                   # base_url 的 API key

  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                                    # 与其他辅助任务相同的 provider 选项
    model: google/gemini-3-flash-preview
    base_url: null                                    # 自定义 OpenAI 兼容端点

备用模型使用：

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

对于 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。

三者 —— auxiliary、compression、fallback —— 工作方式相同：设置 provider 来选择由谁处理请求，设置 model 来选择哪个模型，设置 base_url 来指向自定义端点（会覆盖 provider）。

辅助任务的 Provider 选项

这些选项仅适用于 auxiliary:、compression: 和 fallback_model: 配置 —— "main" 不是顶层 model.provider 的有效值。对于自定义端点，请在你的 model: 部分使用 provider: custom（参见 AI Providers）。

Provider	描述	要求
"auto"	按顺序尝试提供商，直到某个可用（默认）	至少配置了一个提供商
"openrouter"	强制使用 OpenRouter	OPENROUTER_API_KEY
"nous"	强制使用 Nous Portal	hermes auth
"codex"	强制使用 Codex OAuth	hermes model → Codex
"main"	使用主 agent 当前使用的 provider（仅辅助任务）	已配置可用的主 provider
"anthropic"	强制使用 Anthropic native	ANTHROPIC_API_KEY 或 Claude Code 凭据

直接端点覆盖

对于任何辅助任务，设置 base_url 会完全绕过 provider 解析，并将请求直接发送到该端点：

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 不使用主备用模型。不过，可以将它们路由到不同的 provider:model 组合，以优化成本：

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

完整配置详情请参阅 Subagent Delegation。

Cron Job 提供商

Cron jobs 会使用执行时配置的任何提供商运行。它们不支持备用模型。要为 cron jobs 使用不同的提供商，请在 cron job 本身配置 provider 和 model 覆盖：

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

完整配置详情请参阅 Scheduled Tasks（Cron）。

总结

功能	备用机制	配置位置
主 Agent 模型	config.yaml 中的 fallback_model —— 出错时按轮次故障转移（每轮都会恢复主模型）	fallback_model:（顶层）
Vision	自动检测链 + 内部 OpenRouter 重试	auxiliary.vision
Web extraction	自动检测链 + 内部 OpenRouter 重试	auxiliary.web_extract
Context compression	自动检测链；不可用时降级为无摘要	auxiliary.compression
Session search	自动检测链	auxiliary.session_search
Skills hub	自动检测链	auxiliary.skills_hub
MCP helpers	自动检测链	auxiliary.mcp
Approval classification	自动检测链	auxiliary.approval
Title generation	自动检测链	auxiliary.title_generation
Triage specifier	自动检测链	auxiliary.triage_specifier
Delegation	仅提供商覆盖（无自动备用）	delegation.provider / delegation.model
Cron jobs	仅按 job 提供商覆盖（无自动备用）	每个 job 的 provider / model