英文 Model failover

2026年4月5日约 11 分钟

原始链接：https://docs.openclaw.ai/concepts/model-failover
来源章节：4. 官方文档：核心概念、模型与安全
来源小节：无
抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/concepts/model-failover
抓取时间：2026-04-05 13:47:10
状态：ok

中文内容

模型故障转移 - OpenClaw

跳到主要内容

[OpenClaw主页！图片1：深色徽标！图片2：深色徽标](http://docs.openclaw.ai/)

图3：美国

英语

搜索...

⌘K

搜索...

导航

概念和配置

模型故障转移

开始安装频道代理工具和插件模型平台网关和操作参考帮助

概述

概念和配置

提供商

nAI](http://docs.openclaw.ai/providers/openai)

在此页面上

s.openclaw.ai/concepts/model-failover#cooldown-skip-vs-probe-behavior)

概念和配置

模型故障转移

OpenClaw 分两个阶段处理故障：

当前提供商内的身份验证配置文件轮换。
模型回退到 agents.defaults.model.fallbacks 中的下一个模型。

本文档解释了运行时规则以及支持它们的数据。

运行时流程

对于正常的文本运行，OpenClaw 按以下顺序评估候选者：

当前选择的会话模型。
按顺序配置agents.defaults.model.fallbacks。
从覆盖开始运行时最后配置的主要模型。

在每个候选模型中，OpenClaw 都会在前进到下一个候选模型之前尝试身份验证配置文件故障转移。高级序列：

解析活动会话模型和身份验证配置文件首选项。
构建模型候选链。
尝试使用当前提供程序的身份验证配置文件轮换/冷却规则。
如果该提供程序因发生值得故障转移的错误而疲惫不堪，则转向下一个候选模型。
在重试开始之前保留所选的回退覆盖，以便其他会话读者看到运行程序将要使用的相同提供程序/模型。
如果回退候选者失败，则仅在回退拥有的会话覆盖字段仍与失败的候选者匹配时回滚它们。
如果每个候选人都失败了，请抛出一个“FallbackSummaryError”，其中包含每次尝试的详细信息以及已知的最快冷却到期时间。

这故意比“保存并恢复整个会话”更窄。回复运行器仅保留其拥有的模型选择字段以供后备：

providerOverride
模型覆盖
authProfileOverride
authProfileOverrideSource
authProfileOverrideCompactionCount

这可以防止失败的回退重试覆盖较新的不相关会话突变，例如尝试运行时发生的手动“/model”更改或会话轮换更新。

身份验证存储（密钥 + OAuth）

OpenClaw 对 API 密钥和 OAuth 令牌使用身份验证配置文件。

秘密位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json （旧版本：~/.openclaw/agent/auth-profiles.json）。
配置auth.profiles/auth.order是元数据+路由（没有秘密）。
旧版仅导入 OAuth 文件：“~/.openclaw/credentials/oauth.json”（首次使用时导入到“auth-profiles.json”）。

更多详细信息：/concepts/oauth凭证类型：

类型："api_key" → { 提供者，密钥 }
type: "oauth" → { 提供商、访问、刷新、过期、电子邮件？ }（对于某些提供商，+ projectId/enterpriseUrl）

配置文件 ID

OAuth 登录创建不同的配置文件，以便多个帐户可以共存。

默认值：当没有可用电子邮件时，provider:default。
带有电子邮件的 OAuth：provider:<email>（例如 google-antigravity:user@gmail.com）。

配置文件位于“profiles”下的“~/.openclaw/agents//agent/auth-profiles.json”中。

轮换顺序

当提供者有多个配置文件时，OpenClaw 选择如下顺序：

显式配置：auth.order[provider]（如果设置）。
配置的配置文件：由提供商过滤的auth.profiles。
存储的配置文件：提供者的“auth-profiles.json”中的条目。

如果没有配置明确的顺序，OpenClaw 将使用循环顺序：

主密钥： 配置文件类型（** API 密钥之前的 OAuth **）。
次要键：usageStats.lastUsed（每种类型中最旧的第一个）。
冷却/禁用配置文件移至末尾，按最早到期时间排序。

会话粘性（缓存友好）

OpenClaw 固定每个会话所选的身份验证配置文件，以保持提供程序缓存的温暖。它不会根据每个请求轮换。固定的配置文件将被重复使用，直到：

会话被重置 (/new / /reset)
一次压缩完成（压缩计数增量）
该配置文件处于冷却/禁用状态

通过“/model ...@”手动选择会为该会话设置用户覆盖，并且在新会话开始之前不会自动轮换。自动固定配置文件（由会话路由器选择）被视为首选项：首先尝试它们，但 OpenClaw 可能会在速率限制/超时时轮换到另一个配置文件。用户固定的配置文件保持锁定到该配置文件；如果失败并且配置了模型回退，OpenClaw 会移至下一个模型而不是切换配置文件。

为什么 OAuth 会“看起来迷失”

如果您同时拥有同一提供商的 OAuth 配置文件和 API 密钥配置文件，则循环可以跨消息在它们之间进行切换，除非已固定。强制使用单个配置文件：

使用 auth.order[provider] = ["provider:profileId"] 固定，或者
通过“/model ...”使用每会话覆盖和配置文件覆盖（当您的 UI/聊天界面支持时）。

冷却时间

当配置文件由于身份验证/速率限制错误（或看起来像速率限制的超时）而失败时，OpenClaw 会将其标记为冷却并移至下一个配置文件。该速率限制桶比普通的“429”更广泛：它还包括提供者消息，例如“并发请求太多”、“ThrotdlingException”、“达到并发限制”、“workers_ai ...超出配额限制”、“节流”、“资源耗尽”以及定期使用窗口限制，例如“达到每周/每月限制”。格式/无效请求错误（例如 Cloud Code Assist 工具呼叫 ID 验证失败）被视为值得进行故障转移并使用相同的冷却时间。 OpenAI 兼容的停止原因错误（例如“未处理的停止原因：错误”、“停止原因：错误”和“原因：错误”）被归类为超时/故障转移信号。当源与已知的瞬态模式匹配时，提供者范围的通用服务器文本也可以落在该超时桶中。例如，Anthropic 裸“发生未知错误”和带有瞬态服务器文本（例如“内部服务器错误”、“未知错误、520”、“上游错误”或“后端错误”）的 JSON“api_error”负载被视为值得故障转移的超时。 OpenRouter特定的通用u

仅当提供者上下文实际上是 OpenRouter 时，pstream 文本（例如裸露的“Provider returned error”）也被视为超时。通用内部后备文本（例如“LLM 请求因未知错误而失败。”）保持保守，不会自行触发故障转移。速率限制冷却时间也可以是模型范围内的：

当失败的模型 ID 已知时，OpenClaw 会记录速率限制失败的“cooldownModel”。
当冷却时间范围为不同模型时，仍然可以尝试同一提供者上的同级模型。
计费/禁用窗口仍然会阻止跨型号的整个配置文件。

冷却时间使用指数退避：

1 分钟
5分钟
25分钟
1 小时（上限）

状态存储在 usageStats 下的 auth-profiles.json 中：

{
  “使用情况统计”：{
    “提供商：个人资料”：{
      “最后使用”：1736160000000，
      “冷却直到”：1736160600000，
      “错误计数”：2
    }
  }
}

计费禁用

计费/信用失败（例如“信用不足”/“信用余额太低”）被视为值得进行故障转移，但它们通常不是暂时的。 OpenClaw 不是短暂的冷却时间，而是将配置文件标记为禁用（具有较长的退避时间）并轮换到下一个配置文件/提供商。并非每个计费形状响应都是“402”，也不是每个 HTTP“402”都会到达此处。即使提供商返回“401”或“403”，OpenClaw 也会在计费通道中保留显式计费文本，但特定于提供商的匹配器的范围仍限于拥有它们的提供商（例如 OpenRouter“超过 403 密钥限制”）。同时，当消息看起来可重试时，临时“402”使用窗口和组织/工作空间支出限制错误被归类为“rate_limit”（例如“已用尽每周使用限制”、“达到每日限制、明天重置”或“超出组织支出限制”）。它们停留在短冷却/故障转移路径上，而不是长计费禁用路径上。状态存储在“auth-profiles.json”中：

{
  “使用情况统计”：{
    “提供商：个人资料”：{
      “禁用直到”：1736178000000，
      “disabledReason”：“计费”
    }
  }
}

默认值：

计费退还从5 小时开始，每次计费失败加倍，上限为24 小时。
如果配置文件在 24 小时 内没有失败（可配置），则退避计数器会重置。
重载重试允许在模型回退之前1 次相同提供商配置文件轮换。
重载重试默认使用 0 毫秒退避。

模型后备

如果提供程序的所有配置文件均失败，OpenClaw 会移至“agents.defaults.model.fallbacks”中的下一个模型。这适用于身份验证失败、速率限制和耗尽配置文件轮换的超时（其他错误不会提前回退）。过载和速率限制错误的处理比计费冷却更积极。默认情况下，OpenClaw 允许同一提供商的身份验证配置文件重试，然后切换到下一个配置的模型后备，无需等待。诸如“ModelNotReadyException”之类的提供商繁忙信号会出现在该超载的存储桶中。使用“auth.cooldowns.overloadedProfileRotations”、“auth.cooldowns.overloadedBackoffMs”和“auth.cooldowns.rateLimitedProfileRotations”进行调整。当以模型覆盖（挂钩或 CLI）开始运行时，在尝试任何配置的回退后，回退仍以“agents.defaults.model.primary”结束。

候选链规则

OpenClaw 从当前请求的“provider/model”加上配置的后备规则构建候选列表：

请求的型号始终是第一位的。
显式配置的后备会进行重复数据删除，但不会被模型白名单过滤。它们被视为明确的操作员意图。
如果当前运行已经在同一提供程序系列中配置的后备上，则 OpenClaw 会继续使用完整配置的链。
如果当前运行在与配置不同的提供程序上，并且当前模型还不是配置的后备链的一部分，则 OpenClaw 不会附加来自另一个提供程序的不相关的配置后备。
当运行从覆盖开始时，配置的主要会附加在末尾，以便一旦较早的候选者耗尽，链就可以恢复到正常默认值。

哪些错误会提前回退

模型回退继续：

验证失败 *速率限制和冷却耗尽
过载/提供商繁忙错误
超时形状的故障转移错误
计费禁用
LiveSessionModelSwitchError，它被标准化为故障转移路径，因此过时的持久模型不会创建外部重试循环
仍有剩余候选人时的其他无法识别的错误

模型回退不会继续：

不是超时/故障转移形状的显式中止
应该保留在压缩/重试逻辑中的上下文溢出错误（例如“request_too_large”、“INVALID_ARGUMENT：输入超出最大标记数”、“输入标记计数超出最大输入标记数”、“输入对于模型来说太长”或“ollama 错误：超出上下文长度”）
当没有候选人留下时，最后的未知错误

冷却跳过与探测行为

当提供程序的每个身份验证配置文件都已处于冷却状态时，OpenClaw 不会自动永远跳过该提供程序。它针对每个候选人做出决定：

持续的身份验证失败会立即跳过整个提供程序。
计费禁用通常会跳过，但仍然可以在节流阀上探测主要候选者，因此无需重新启动即可恢复。
主要候选者可能会在冷却时间即将到期时被探测，并按提供商进行限制。
当故障看起来是暂时的（“rate_limit”、“overloaded”或未知）时，尽管有冷却时间，仍可以尝试相同提供商的后备同级。当速率限制是模型范围内的并且同级模型仍可能立即恢复时，这一点尤其重要。
瞬态冷却探针仅限于每个提供商每次回退运行一个，因此单个提供商不会阻止跨提供商回退。

会话覆盖和实时模型切换

会话模型的更改是共享状态。活动运行器、“/model”命令、压缩/会话更新和实时会话协调都读取或写入同一会话条目的部分。这意味着回退重试必须与实时模型切换协调：

只有明确的用户驱动的模型更改才会标记待定的实时切换。其中包括“/model”、“session_status(model=...)”和“sessions.patch”。
系统驱动的模型更改（例如回退旋转、心跳覆盖或压缩）永远不会自行标记待处理的实时切换。
在回退重试开始之前，回复运行程序会将选定的回退覆盖字段保留到会话条目中。
实时会话协调更喜欢持久会话覆盖过时的运行时模型字段。
如果回退尝试失败，则运行程序仅回滚其写入的覆盖字段，并且仅当它们仍然与失败的候选者匹配时才回滚。

这可以防止经典的竞赛：

主节点失败。
在内存中选择后备候选者。
会话存储仍然显示旧的主数据库。
实时会话协调读取过时的会话状态。
在回退尝试开始之前，重试会快速恢复到旧模型。

持久回退覆盖会关闭该窗口，而窄回滚会保持较新的手动或运行时会话更改完好无损。

可观察性和故障总结

runWithModelFallback(...) 记录每次尝试的详细信息，以提供日志和面向用户的冷却消息：

尝试提供者/模型
原因（rate_limit、overloaded、billing、auth、model_not_found 和类似的故障转移原因）
可选状态/代码
人类可读的错误摘要

当每个候选人都失败时，OpenClaw 会抛出“FallbackSummaryError”。外部回复运行器可以使用它来构建更具体的消息，例如“所有模型都暂时受到速率限制”，并包括已知的最快冷却到期时间。该冷却摘要是模型感知的：

对于尝试的提供商/模型链，忽略不相关的模型范围的速率限制
如果剩余的块是匹配的模型范围的速率限制，OpenClaw 会报告仍阻止该模型的最后一个匹配到期时间

英文 Model failover

中文内容

模型故障转移 - OpenClaw

概述

概念和配置

提供商

模型故障转移

On this page

英文 Model failover

中文内容

模型故障转移 - OpenClaw

概述

概念和配置

提供商

模型故障转移

On this page