模型故障转移

OpenClaw 分两个阶段处理失败：

1. 在当前提供方内进行认证配置文件轮换。
2. 模型回退到 agents.defaults.model.fallbacks 中的下一个模型。

在轮换配置文件或更改模型之前，运行器会对临时速率限制和提供方故障尝试有界的同模型恢复。它会继续现有对话记录，保留部分输出和已完成的工作。代理会被指示先检查被中断的操作，再决定是否重做这些操作。重试状态显示等待时间和尝试次数。取消仍然可用。无需额外配置。

思考级恢复仅在提供方识别到推理（reasoning）或思考（thinking）参数时适用。模型/账户限制以及无关的不受支持选项保留其原始失败分类，并遵循配置的回退策略。OpenClaw 不会在禁用思考的情况下重试这些失败。

运行时流程¶

1. 解析会话状态

解析活动会话模型和认证配置文件偏好。

2. 构建候选链

根据当前模型选择以及该选择来源的回退策略构建模型候选链。配置的默认值、cron 作业主模型以及自动选择的回退模型可以使用已配置的回退。显式的用户会话选择是严格的。

3. 尝试当前提供方

按照认证配置文件轮换/冷却规则尝试当前提供方。在轮换配置文件或推进模型回退之前，运行器会对符合条件的瞬时失败应用有界恢复。

4. 遇到值得故障转移的错误时推进

如果该提供方因值得故障转移的错误而耗尽，则移动到下一个模型候选。

5. 在当前回合使用回退

运行胜出的回退候选，而不更改会话已选择的提供方/模型。

6. 耗尽时报告失败

如果每个候选都失败，则呈现最终失败。抛出的耗尽摘要包含结构化的逐尝试详细信息，以及在已知时给出最近的冷却到期时间。

回退执行是回合局部的。回复运行器仅持久化回退通知状态，以便 /status 和转换通知能够区分已选择的模型与实际应答的模型。它不会将回退持久化为下一回合的模型选择。

当自动模型选择推进到回退时，放置在 OpenClaw 云端工作器上的会话会保留 OpenClaw 运行时。已配置的提供方、模型和认证配置文件回退规则仍然适用。显式的会话或已配置的运行时选择保持严格：不兼容的运行时报告放置错误，并且需要先有兼容的目标才能重试。

当配置的回退因代理运行达到最终超时，或因空闲超时成本失控熔断器返回最终错误而停止时，model-fallback/decision 记录器会记录 model_fallback_chain_stopped，原因为 agent_run_terminal_timeout 或 idle_timeout_circuit_breaker。这些是最终停止，不是提供方故障，也不是请求尝试另一个模型。现有的运行截止时间和成本限制仍然适用。

自动网络策略升级¶

嵌入式 OpenClaw 运行时会在 Daybreak Blue 上重试一次重放安全的 OpenAI 网络策略拒绝。这包括使用 ChatGPT 认证的 OpenAI Responses 传输的正常嵌入式回合，而不仅仅是 Codex 插件会话。该传输会将 OpenAI 的结构化网络策略错误投影到此策略使用的拒绝元数据中，涵盖其可能到达的所有终止路径：非 OK HTTP 响应体、流式 error 事件以及 response.failed 事件。没有结构化网络类别的一般拒绝文本仍然是终止性的。

此策略路径是回合局部的：它不会更改已选择的会话模型，也不会将普通的提供方故障发送到 Daybreak。Codex 支持的会话保留其独立的插件自有策略，该策略在 Codex harness 运行时行为 中描述。

默认目标是 openai/gpt-daybreak-blue-latest。仅当以下所有条件都为真时，重试才会运行：

• 所选的嵌入式尝试报告 provider_refusal，提供方为 openai，类别为 cyber；
• 该尝试的重放元数据证明不会重复任何工具或投递副作用；
• 目标与遭拒绝的模型不同；
• 选择不是严格的；并且
• 该功能已启用。

严格的选择保持严格。锁定的模型选择会以显式的空回退列表形式到达运行器，此策略与普通回退一样遵循这一点：在操作员解锁选择之前，拒绝保持终止性。

如果 Daybreak 尝试在未提交工作的情况下失败，OpenClaw 会保留原始提供方拒绝，而不是尝试无关的已配置回退。如果重试在失败前已执行了工具或已投递输出，则保留其自身的结果，因为其重放判定、投递证据和终止回执描述了实际运行的内容。如果重试抛出普通故障转移类错误以外的任何异常，该异常将原样传播：已记录的最终停止禁止重放，而未分类的抛出则是回退运行器报告已提交工作的尝试的方式。授权失败会在当前会话中冷却该目标，之后另一个网络策略拒绝才会再次探测它。

{
  agents: {
    defaults: {
      embeddedAgent: {
        cyberFailover: {
          mode: "auto", // or "off"
          model: "openai/gpt-daybreak-blue-latest",
          cooloffMs: 600000,
        },
      },
    },
  },
}

通用模型回退顺序不变。非网络策略拒绝、Codex/原生 harness 结果或任何重放不安全的尝试在现有拒绝策略下保持终止性。

选择来源策略¶

选择来源控制是否允许回退链：

• 配置的默认值：agents.defaults.model.primary 使用 agents.defaults.model.fallbacks。
• 原生代理主模型：agents.entries.*.model 是严格的，除非该代理的模型对象包含自己的 fallbacks。使用 fallbacks: [] 使严格行为显式化，或使用非空列表让该代理选择加入模型回退。
• ACP 代理主模型：对于 runtime.type: "acp"，代理主模型选择其外部 harness 模型。原生 OpenClaw 调用从 agents.defaults.model 继承主模型和回退；显式的代理 model.fallbacks 会替换原生回退列表，包括用 [] 禁用它。显式的原生会话和子代理选择保留其正常的优先级和严格性。这不会为诸如 /btw 这类仅运行其选中模型的命令添加回退。
• 运行时回退：回退候选仅适用于当前回合。下一回合从选中的主模型重新开始。OpenClaw 仍然识别由 v2026.4.26 至 v2026.6.0 存储的 modelOverrideSource: "auto" 条目。它每 5 分钟探测其配置的来源，一旦来源恢复就清除这些条目。自动清除功能在 v2026.6.1 中发布。/new、/reset 和 sessions.reset 也会清除这些条目。
• 用户会话覆盖：使用 /model、模型选择器、session_status(model=...) 或 sessions.patch 选择特定模型会写入 modelOverrideSource: "user"。这是精确的会话选择。如果选中的提供方/模型在产生回复之前失败，OpenClaw 会报告失败，而不是从无关的已配置回退中应答。
• 显式配置的默认值：通过相同的界面选择默认会写入 modelOverrideSource: "default"，而不存储提供方/模型覆盖。这可以防止子会话继承父会话的模型固定，同时保留配置默认值的正常回退策略。
• 旧版会话覆盖：在 v2026.4.26 之前写入的会话条目可能包含 modelOverride 而没有 modelOverrideSource。OpenClaw 将这些条目视为用户覆盖，因此旧的显式选择不会被静默转换为回退行为。
• Cron 载荷模型：cron 作业的 payload.model / --model 是作业主模型，而不是用户会话覆盖。除非作业提供 payload.fallbacks，否则它使用已配置的回退。payload.fallbacks: [] 使 cron 运行变得严格。

Agent 只能通过 model: { fallbacks: [...] } 覆盖其回退链，同时继续继承共享的主模型。显式设置 fallbacks: [] 会禁用回退，而不会固定该主模型。在 Settings → Agents → Overview 中，编辑回退标签会保留主模型继承。删除所有标签会保存一个空链，而不是恢复共享回退。

认证存储（密钥 + OAuth）¶

OpenClaw 使用 auth profiles（认证配置文件） 来管理 API 密钥和 OAuth 令牌。

• 机密和运行时认证路由状态存储在 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 中。
• 配置项 auth.profiles / auth.order 仅用于元数据和路由（不含机密）。
• 旧版 credentials/oauth.json、auth-profiles.json、auth-state.json 以及每 agent 的 auth.json 文件仅由 openclaw doctor --fix 导入。在包含凭据的旧版文件迁移完成之前，受影响 agent 的运行时将默认拒绝（fail closed）。OpenClaw 绝不会静默导入或回退到这些文件。

更多详情：OAuth

凭据类型：

• type: "api_key" → { provider, key }：API 密钥类型
• type: "oauth" → { provider, access, refresh, expires, email? }（某些 provider 还包含 projectId/enterpriseUrl）
• type: "token" → 静态 bearer 风格令牌，可选择设置过期时间。OpenClaw 不会刷新它（用于 aws-sdk 和其他凭据链认证模式）。

配置文件 ID¶

OAuth 登录会创建不同的配置文件，从而让多个账户可以共存。

• 默认：没有可用邮箱时使用 provider:default。
• 带邮箱的 OAuth：provider:<email>（例如 openai:user@example.com）。

这些配置文件存储在每个 agent 的 openclaw-agent.sqlite 认证配置存储中。

轮换顺序¶

当某个 provider 有多个配置文件时，OpenClaw 会按以下顺序选择：

1. 已存储的顺序覆盖

通过 openclaw models auth order set --provider <id> <profileIds...> 设置的每 agent 顺序。

2. 显式配置

auth.order[provider]（如果已设置）。

3. 配置里声明的配置文件

按 provider 过滤的 auth.profiles。

4. 已存储的配置文件

该 provider 在每个 agent 的 SQLite 认证配置存储中的条目。

如果未配置显式顺序，OpenClaw 会使用循环轮换（round-robin）顺序：

• 主要排序键： 配置文件类型（OAuth，然后是静态令牌，最后是 API 密钥）。
• OAuth 的次要排序键： 当前访问令牌可用的配置文件排在访问令牌已过期的配置文件之前。已过期的 OAuth 配置文件仍然符合条件，这样当没有可用的同类配置文件时，运行时可以刷新它们。
• 下一个排序键： usageStats.lastUsed（在每个类型/状态层级内，最早使用的排在前面）。
• 冷却/禁用的配置文件会被移到末尾，按到期时间由近到远排序。

会话粘性（缓存友好）¶

清除或轮换认证固定只会影响所选 agent 的会话，包括自定义会话存储以及保留的 global 和 unknown 会话键。

OpenClaw 会在每个会话中固定自动选择的认证配置文件，以保持 provider 缓存热度。它不会在每个请求时进行轮换。在以下情况下，自动固定可能会轮换或清除：

• 会话被重置（/new / /reset）
• 配置文件处于冷却/禁用状态

上下文压缩不会改变已选的认证配置文件。健康的配置文件在压缩后仍保持固定；认证失败和不可用的配置文件仍使用正常的回退顺序。

通过 /model …@<profileId> -s 进行的手动选择会设置用户覆盖。有效的用户固定会跨 /new、/reset、会话滚动（session rollover）、上下文压缩和冷却窗口持久保留。在符合条件时，它仍然是首选。当该特定配置文件处于冷却或禁用状态时，OpenClaw 会尝试下一个符合条件的同 provider 配置文件，而不会替换已存储的固定。显式删除已保存的凭据会清除受其影响的 agent 模型和会话账户选择，同时保留已选模型。其他账户（包括由另一个 agent 拥有的独立凭据）会保留其选择。暂时缺失或过期的凭据不会清除用户固定；刷新可以恢复访问。如果旧配置仍指定已删除的账户，请在 Models 中选择一个可用账户。当所选 provider 更改时，OpenClaw 也会清除不兼容的固定；当用户选择另一个账户时，则会替换该固定。/model default -s 会清除模型覆盖，同时保留兼容的认证固定并清除不兼容的认证固定。

OpenAI Codex 订阅与 API 密钥备份¶

对于 OpenAI agent 模型，认证和运行时是分开的。openai/gpt-* 继续留在 Codex harness 上，而认证可以在 Codex 订阅配置文件与 OpenAI API 密钥备份之间轮换。

使用 auth.order.openai 作为面向用户的顺序：

{
  auth: {
    order: {
      openai: ["openai:user@example.com", "openai:api-key-backup"],
    },
  },
}

ChatGPT/Codex OAuth 配置文件和 OpenAI API 密钥配置文件都使用 openai:* 前缀。当订阅达到 Codex 使用限制时，如果 Codex 提供了重置时间，OpenClaw 会记录该精确的重置时间。随后它会按顺序尝试下一个认证配置文件，并将运行保持在 Codex harness 内。一旦重置时间过去，订阅配置文件将再次符合条件，下一次自动选择便可回到该配置文件。

使用用户固定的配置文件，可以让某个账户/密钥成为该会话的持久首选。如果该配置文件不可用，OpenClaw 会临时轮换剩余的符合条件的 auth.order.openai 配置文件，并在恢复后回到固定的配置文件。

冷却期¶

当配置因认证或速率限制错误而失败时，OpenClaw 会将其标记为冷却期，并切换到下一个配置。看起来像速率限制的超时也算作此类失败。

CLI 支持的运行时只有在恢复、分叉和新会话恢复尝试完成后，才会确定配置健康状态。终结性凭据失败会在模型回退之前冷却精确选中的配置。成功运行会清除过期的失败状态。没有选中配置时的转录、格式、上下文、提供商前超时以及环境 CLI 失败不会更改共享配置健康状态。

常规（非计费、非永久认证）冷却期会根据配置的最近错误计数递增：

• 第 1 次失败：30 秒
• 第 2 次失败：1 分钟
• 第 3 次及以后失败：5 分钟（上限）

一旦配置的内置失败窗口过去，计数器就会重置。

状态存储在按代理划分的 SQLite 认证状态下的 usageStats 中：

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

认证失败跳过缓存¶

默认情况下，每个新回合都会保留现有的回退重试行为。OpenClaw 会再次重试每个已配置的回退候选项。这包括最近以 auth 或 auth_permanent 失败的非主要候选项。

选择加入以抑制重复认证失败：

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

启用后，OpenClaw 会在认证类失败后，为非主要回退候选项记录一个内存中、会话范围的跳过标记。该键包含会话、提供商、模型以及选中的自动或显式配置 ID。切换配置不会继承另一个配置的失败标记。主要候选项永远不会被跳过，因此显式的用户模型选择仍会呈现真实的认证错误。该缓存是进程本地的，并在 Gateway 重启时清除。

该值是以毫秒为单位的 TTL。0 或未设置会禁用缓存。正值会被限制在 1 秒到 10 分钟之间。

计费禁用¶

计费/信用失败（例如“余额不足”/“信用余额过低”）被视为可触发故障转移。OpenClaw 最初将凭据标记为 禁用 十分钟，并轮换到下一个符合条件的配置/提供商。

已配置的内联 API 密钥在激活的禁用窗口期间无法重试。窗口过期后，它们会重新符合条件。另一次计费失败会开始一个新的十分钟窗口。存储的认证配置也可以在禁用窗口期间通过有界的主要提供商探测恢复。充值本身不会清除持久化状态，升级会使已激活的窗口保持其现有截止时间。

高置信度的永久身份验证失败（已吊销/已停用的密钥、已停用的工作区）使用相同的十分钟初始禁用窗口，因为某些提供商会在事件期间临时呈现看似身份验证的负载。

状态存储在按代理划分的 SQLite 身份验证状态中：

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

过载和速率限制错误默认允许一次同一提供商的身份验证配置文件轮换，然后才推进到下一个已配置的模型回退。活动运行时首先使用其符合条件的同模型恢复预算。身份验证配置文件轮换和模型回退仍需要证据表明重放原始尝试是安全的。

模型回退¶

如果某个提供商的所有配置文件都失败，并且失败匹配下列故障转移原因之一，OpenClaw 会移动到 agents.defaults.model.fallbacks 中的下一个模型。这包括 HTTP 404 响应中的 model_not_found。它不包括响应体标识了更具体条件的 404，例如上下文溢出、会话过期、计费、身份验证或请求格式。未暴露足够细节的提供商错误仍会在回退状态中被精确标记。empty_response 表示提供商未返回可用的消息或状态。no_error_details 表示提供商明确返回了 Unknown error (no error details in response)。unclassified 表示 OpenClaw 保留了原始预览，但尚无分类器匹配它。

诸如 ModelNotReadyException 之类的提供商繁忙信号会落入过载桶，并遵循与速率限制相同的“一次轮换然后回退”策略。

故障转移控制器管理 OpenClaw 的临时恢复预算。速率限制在身份验证配置文件轮换或模型回退之前最多获得 10 次总尝试。带抖动的指数等待上限为 30 秒，而提供商的 retry-after 和 retry-after-ms 提示即使超过该上限仍作为最小等待时间。其他临时故障保留八次重试和连续故障的 90 秒窗口。一次完成的成功模型响应会清除该窗口，但不会重置总重试计数；仅部分输出和工具活动不会清除。一旦该预算或窗口耗尽，恢复将推进到符合条件的身份验证配置文件轮换、已配置的模型回退或可见错误。续接会保留转录，而不是重放原始用户请求。恢复和任何回退胜出者都保持轮次局部。

嵌入式运行时的现有会话设置 retry.provider.maxRetries 会覆盖其恢复重试预算。0 禁用重试，速率限制仍限制为最多 10 次总尝试。它不是 openclaw.json 键，也不会更改原生测试框架的内部请求重试。原生测试框架可能在 OpenClaw 开始续接恢复之前完成其自身的请求重试。回复运行器不会添加另一个整轮重放循环。有关节奏和排除项，请参阅重试策略。

等待期间，Control UI 会为速率限制显示一个临时的 正在重试… n/10 指示器。重试的失败不会成为持久化的助手消息。终止失败保留一个错误。历史记录会隐藏已恢复的空错误或仅推理错误，而不会重写已存储的转录。

可见的失败消息会独立于重试分类保留提供商的 HTTP 状态。提供商 HTTP 500 在最终回复中仍然是服务器错误，恢复会将其分类为 server_error，而不是将其与超时类失败归为一组。原始提供商响应详情不会出现在该回复中。

网关转录验证失败是本地格式错误。它们不会轮换或冷却健康的凭据，并且助手错误和抛出的运行失败都会标识被拒绝的会话转录条目，并提供恢复指导。真正的提供商会话过期会保持其现有的凭据健康行为。

提供商过载和 HTTP 5xx 失败使用临时恢复指导。仅说明模型“不可用”的消息并不能证明该模型已退役或你的配置需要更改。配置指导需要缺失模型响应或明确的账户/模型限制。即使 Codex 停止重试该轮次，Codex 轮次错误也会保留其过载和 HTTP 状态信息。

当运行从已配置的默认主模型、定时任务主模型、具有显式回退的代理主模型或自动选择的回退覆盖启动时，OpenClaw 可以遍历匹配的已配置回退链。没有显式回退的代理主模型是严格的。显式用户选择也是严格的：/model ollama/qwen3.5:27b、模型选择器、sessions.patch 以及一次性 CLI 提供商/模型覆盖。如果该提供商或模型不可达，或在产生回复之前失败，OpenClaw 会报告失败，而不是从不相关的回退中回答。

候选链规则¶

OpenClaw 根据当前请求的 provider/model 加上已配置的回退来构建候选列表。

哪些错误会推进回退¶

最终提供商拒绝会结束当前回合。OpenClaw 会显示它，而不会进行自动恢复回合、压缩重试或切换到无关模型。除了错位预防措施外，排队或后续用户消息仍会开始其自己的回合。

错位预防措施¶

OpenAI 的 misalignment_policy_violation 会停止受影响对话中的进一步工作。它表示代理对任务的解释需要审查；它并不证明用户违反了政策。OpenClaw 会保留可用的提供商发现，并保留排队消息，而不是重试对话。已接受的结果仍可以完成记录。

在控制 UI 中，选择 审查发现。当受支持的 Codex 或 ChatGPT Responses 运行时提供继续项时，对话框会先显示其确切消息，然后提供 确认发现并继续。确认仅适用于显示的会话和发现。它会保留运行时、模型、沙箱和审批设置；更改的审查需要再次决定。预防措施仅在提供商接受继续项后清除。之前排队的消息仍会保留，以便单独审查和重试。

继续项会将已确认的消息恰好作为下一个用户回合发送一次。运行时上下文保持独立，现有转录消息保持不变。

普通 API 密钥 Responses 和隐身对话不提供继续项。缺失或不完整的发现也无法授权继续项。已停止的对话不会撤销已完成的操作。参见 OpenAI 的错位监控指南。

冷却跳过与探测行为¶

当提供商的所有身份验证配置文件都已处于冷却状态时，OpenClaw 不会永远自动跳过该提供商。它会按候选做出决定：

会话覆盖与实时模型切换¶

会话模型更改是共享状态。活动运行器、/model 命令、压缩/会话更新以及实时会话协调都会读取或写入同一会话条目的部分。回退执行不会写入模型选择字段，因此在重试时不会替换较新的手动选择。

实时模型切换遵循以下规则：

• 只有显式的用户驱动模型更改才会标记待处理的实时切换。这包括 /model、session_status(model=...) 和 sessions.patch。
• 系统驱动的模型更改（例如回退轮换、心跳覆盖或压缩）本身永远不会标记待处理的实时切换。
• 用户驱动的模型覆盖在回退策略中被视为精确选择。因此，不可达的已选提供商会表现为失败，而不是被 agents.defaults.model.fallbacks 掩盖。
• 运行时回退候选保持回合局部。下一回合从当前已选模型开始，包括在前一次运行期间到达的手动选择。
• 之前存储的自动回退覆盖仍受支持：OpenClaw 会定期探测其配置的来源，并在其恢复时清除覆盖。/new、/reset 和 sessions.reset 会立即清除自动来源的覆盖。
• 在群聊和频道对话之外，用户回复会在每次状态更改时通知回退转换和回退清除恢复一次。具有相同已选/活动对的重复回合不会重复通知。群聊和频道对话保留相同的回退状态和生命周期事件，但不发布它。
• /status 显示已选模型，并在回退状态不同时显示活动回退模型和原因。
• 实时会话协调优先使用持久化的会话覆盖，而不是过期的运行时模型字段。
• 如果实时切换错误指向活动回退链中更晚的候选，OpenClaw 会直接跳转到该已选模型。它不会先遍历无关候选。
• 实时切换可以选择活动回退链之外的模型。然后 OpenClaw 会将原始切换返回给代理、回复或隔离 cron 重试所有者。已选模型可以完成同一回合。

The active run carries its chosen candidate directly. Live reconciliation changes that candidate only for an explicit pending user switch, so no temporary fallback override or rollback is needed.

When a recorded fallback notice belongs to a different selected model, status and session lists skip its optional transcript lookup. That stale-notice path no longer surfaces transcript-only errors or starts projection reconciliation. Matching notices use a read-only transcript lookup that neither creates storage nor starts projection reconciliation. If optional storage or projections are unavailable, the lookup omits transcript-derived details. Unexpected read errors still propagate.

用户可见的回退通知¶

在群聊和频道对话之外，当会话切换到自动选择的回退模型时，OpenClaw 会在同一回复界面发送状态通知：

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

当后续探测成功且会话返回到已选主模型时，OpenClaw 会发送：

↪️ Model Fallback cleared: <primary> (was <fallback>)

这些通知是运维消息，不是助手内容。在群聊和频道对话之外，它们每次状态变更只投递一次，在可行时包括仅产生副作用的轮次，但重复的轮次本地回退转换不会重复发送它们。群聊和频道对话会抑制可见通知，同时保留相同的回退状态和生命周期事件。投递会绕过常规源回复抑制，不会占用线程频道的第一个助手回复槽位，并且不包含在文本转语音中。

持久化的通知状态可防止在连续轮次使用相同的已选/活动对时重复通知，同时模型选择本身保持不变。

当回退模型给出回答时，Control UI 只显示一次成功回答，并从同一运行中移除空的失败尝试占位符。原始转录保留失败尝试以便排查问题。产生部分可见输出的失败轮次和尝试仍会显示。

可观测性与失败摘要¶

runWithModelFallback(...) 记录每次尝试的详细信息，用于日志和用户可见的冷却消息：

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

结构化的 model_fallback_decision 日志还会在候选失败、被跳过或后续回退成功时包含扁平的 fallbackStep* 字段。这些字段使尝试的转换显式化：fallbackStepFromModel、fallbackStepToModel、fallbackStepFromFailureReason、fallbackStepFromFailureDetail 和 fallbackStepFinalOutcome。日志和诊断导出器可以在最终回退也失败时重建主失败。

对于缺失模型的回退，查找 reason 或 fallbackStepFromFailureReason 为 model_not_found 的 model_fallback_decision 事件。

耗尽摘要会保留结构化尝试记录。回退运行器可以返回分类的耗尽结果，或抛出 FailoverError。外层回复运行器可以使用这些详细信息构建更具体的消息，例如“所有模型暂时受到速率限制”。如果已知，它可以包含最早的冷却到期时间。

该冷却摘要是模型感知的：

• 与尝试的提供商/模型链无关的模型范围速率限制会被忽略
• 如果剩余阻塞是匹配的模型范围速率限制，OpenClaw 会报告仍然阻塞该模型的最后一个匹配到期时间

相关配置¶

参见 Gateway 配置：

• auth.profiles / auth.order
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由
• openclaw models — 检查已解析的默认值和回退值

参见 模型 了解更广泛的模型选择和回退概述。

参见 模型提供商 了解提供商设置、凭据和每个提供商的模型目录。