模型故障转移

OpenClaw 分两个阶段处理故障：

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

运行时流程

这有意比“保存并恢复整个会话”更严格地限定范围。回复运行器只持久化其为回退所拥有的模型选择字段：providerOverride、modelOverride、modelOverrideSource、authProfileOverride、authProfileOverrideSource、authProfileOverrideCompactionCount。这样可以防止失败的回退重试覆盖较新的无关会话变更，例如手动执行 /model 的更改，或尝试运行期间发生的会话轮换更新。

选择来源策略

选择来源决定是否允许使用回退链：

• 配置的默认模型：agents.defaults.model.primary 使用 agents.defaults.model.fallbacks。
• 智能体主模型：agents.list[].model 默认严格遵循该模型，除非该智能体的模型对象包含自己的 fallbacks。使用 fallbacks: [] 可显式指定严格行为，使用非空列表则让该智能体启用模型回退。
• 自动回退覆盖：运行时回退会在重试前写入 providerOverride、modelOverride、modelOverrideSource: "auto" 以及所选的来源模型。此覆盖会继续沿已配置的回退链向后尝试，而不会在每条消息上都探测主模型；但 OpenClaw 每 5 分钟探测一次配置的来源模型（不可配置），并在其恢复后清除覆盖。/new、/reset 和 sessions.reset 也会清除自动来源的覆盖。未显式设置 heartbeat.model 的 Heartbeat 运行会在其来源不再与当前配置的默认模型匹配时清除直接自动覆盖。
• 用户会话覆盖：/model、模型选择器、session_status(model=...) 和 sessions.patch 会写入 modelOverrideSource: "user"。这是精确的会话模型选择。如果所选提供商或模型在生成回复前失败，OpenClaw 会报告该故障，而不会使用无关的已配置回退来作答。
• 旧版会话覆盖：较旧的会话条目可能包含 modelOverride，但没有 modelOverrideSource。OpenClaw 会将其视为用户覆盖，以免显式的旧选择被静默转换为回退行为。
• 定时任务载荷模型：定时任务的 payload.model / --model 是任务主模型，而不是用户会话覆盖。除非任务提供 payload.fallbacks，否则它会使用已配置的回退；payload.fallbacks: [] 会让定时任务严格遵循主模型。

OpenClaw 会按会话和主模型记住最近的主模型探测，因此不会在每轮交互中反复重试失败的主模型。当会话转到回退模型时，它会发送一条可见通知；当会话返回所选主模型时，还会发送另一条通知。对于持续使用回退模型的每轮交互，它不会重复发送通知。

身份验证故障跳过缓存

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

要选择启用重复身份验证故障抑制，请设置：

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

启用后，当非主回退候选项发生身份验证类故障时，OpenClaw 会记录一个位于内存中且限定于会话范围的跳过标记，其键由会话 ID、提供商和模型组成。主候选项绝不会被跳过，因此显式的用户模型选择仍会显示真实的身份验证错误。该缓存仅限当前进程，并会在 Gateway 网关重启时清除。

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

用户可见的回退通知

当会话转到自动选择的回退模型时，OpenClaw 会在同一回复界面中发送状态通知：

↪️ 模型回退：<fallback>（已选择 <primary>；<reason>）

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

↪️ 模型回退已清除：<primary>（之前为 <fallback>）

这些通知是运行状态消息，而不是助手内容。每次状态变化时仅发送一次，包括在可行情况下仅产生副作用的轮次，但持续使用回退模型的轮次不会重复发送。通知投递会绕过常规的来源回复抑制机制，不会占用线程式渠道的第一个助手回复位置，并且不会用于文本转语音和跟进承诺提取。

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

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

• 机密信息和运行时身份验证路由状态存储在 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 中。
• 配置中的 auth.profiles / auth.order 仅包含元数据和路由信息，不含机密信息。
• 仅用于旧版导入的 OAuth 文件：~/.openclaw/credentials/oauth.json（首次使用时导入每个智能体的身份验证存储）。
• 旧版 auth-profiles.json、auth-state.json 和每个智能体的 auth.json 文件由 openclaw doctor --fix 导入。

更多详情：OAuth

凭据类型：

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（部分提供商还包含 projectId/enterpriseUrl）
• type: "token" → 静态承载令牌，可以选择设置过期时间；OpenClaw 不会刷新它（用于 aws-sdk 和其他凭据链身份验证模式）

配置文件 ID

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

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

配置文件位于每个智能体的 openclaw-agent.sqlite 身份验证配置文件存储中。

轮换顺序

当一个提供商有多个配置文件时，OpenClaw 按以下顺序选择：

如果未配置显式顺序，OpenClaw 会使用轮询顺序：

• **主排序键：**配置文件类型（依次为 OAuth、静态令牌、API 密钥）。
• 次排序键：usageStats.lastUsed（每种类型内最早使用的优先）。
• 处于冷却或禁用状态的配置文件会移到末尾，并按最早到期时间排序。

会话粘性（有利于缓存）

OpenClaw 会为每个会话固定所选的身份验证配置文件，以保持提供商缓存处于热状态。它不会在每次请求时轮换。固定的配置文件会持续复用，直到：

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

通过 /model …@<profileId> 手动选择会为该会话设置用户覆盖，在新会话开始前不会自动轮换。

OpenAI Codex 订阅与 API 密钥备用方案

对于 OpenAI 智能体模型，身份验证与运行时相互独立。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 会将其标记为冷却状态，并转到下一个配置文件。

常规冷却（非计费、非永久身份验证失败）会根据配置文件近期的错误次数递增：

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

配置文件的失败时间窗口过去后，计数器会重置（auth.cooldowns.failureWindowHours，默认为 24）。

状态存储在每个 Agent 的 SQLite 身份验证状态中的 usageStats 下：

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

计费禁用

计费/额度失败（例如“额度不足”/“额度余额过低”）会被视为需要故障转移，但通常并非暂时性故障。OpenClaw 不会设置短暂冷却，而是将该配置文件标记为已禁用（采用更长的退避时间），并轮换到下一个配置文件/提供商。

高置信度的永久身份验证失败（密钥被撤销/停用、工作区被停用）会进入类似的禁用处理路径，但由于某些提供商在事故期间可能暂时返回看似身份验证失败的载荷，其恢复等待时间远短于计费失败。

状态存储在每个 Agent 的 SQLite 身份验证状态中：

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

默认值（auth.cooldowns.*）：

过载和速率限制错误的处理比计费冷却更积极：默认情况下，OpenClaw 允许重试一次同提供商的身份验证配置文件，然后无需等待便切换到下一个已配置的回退模型。

模型回退

如果某个提供商的所有配置文件都失败，OpenClaw 会转到 agents.defaults.model.fallbacks 中的下一个模型。这适用于身份验证失败、速率限制，以及配置文件轮换耗尽后的超时（其他错误不会推进回退）。对于未提供足够详细信息的提供商错误，回退状态仍会使用精确标签：empty_response 表示提供商未返回可用的消息或状态，no_error_details 表示提供商明确返回了 Unknown error (no error details in response)，而 unclassified 表示 OpenClaw 保留了原始预览，但尚无分类器与之匹配。

ModelNotReadyException 等提供商繁忙信号会归入过载类别，并采用与速率限制相同的“轮换一次后回退”策略（请参阅上方的默认值表）。

当一次运行从已配置的默认主模型、cron 作业主模型、具有显式回退项的 Agent 主模型，或自动选择的回退覆盖项开始时，OpenClaw 可以遍历匹配的已配置回退链。没有显式回退项的 Agent 主模型和用户显式选择（例如 /model ollama/qwen3.5:27b、模型选择器、sessions.patch 或一次性 CLI 提供商/模型覆盖项）采用严格策略：如果该提供商/模型不可达，或在生成回复前失败，OpenClaw 会报告失败，而不会使用无关的回退模型作答。

候选链规则

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

哪些错误会推进回退

跳过冷却与探测行为

当某个提供商的所有身份验证配置文件均已处于冷却状态时，OpenClaw 不会自动永久跳过该提供商，而是针对每个候选项作出判断：

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

会话模型变更属于共享状态。活动运行器、/model 命令、压缩/会话更新和实时会话协调都会读取或写入同一会话条目的不同部分。

因此，回退重试必须与实时模型切换协调：

• 只有由用户显式触发的模型变更才会标记待处理的实时切换。这包括 /model、session_status(model=...) 和 sessions.patch。
• 由系统驱动的模型变更（例如回退轮换、Heartbeat 覆盖或压缩）绝不会自行标记待处理的实时切换。
• 在回退策略中，用户驱动的模型覆盖项会被视为精确选择，因此不可达的选定提供商会直接显示为失败，而不会被 agents.defaults.model.fallbacks 掩盖。
• 在回退重试开始前，回复运行器会将选定的回退覆盖字段持久化到会话条目。
• 自动回退覆盖项会在后续轮次中保持选中，避免 OpenClaw 在每条消息上都探测已知存在问题的主模型。OpenClaw 会定期重新探测已配置的原始模型，并在其恢复后清除自动覆盖项；/new、/reset 和 sessions.reset 会立即清除自动生成的覆盖项。
• 每次状态变更时，用户回复会通知一次回退转换以及回退清除后的恢复。持续使用回退模型的轮次不会重复该通知。
• /status 会显示选定的模型；当回退状态不同时，还会显示当前回退模型及原因。
• 实时会话协调优先采用已持久化的会话覆盖项，而不是过期的运行时模型字段。
• 如果实时切换错误指向当前回退链中靠后的候选项，OpenClaw 会直接跳转到该选定模型，而不是先遍历无关候选项。
• 如果回退尝试失败，运行器只会回滚由其写入的覆盖字段，并且仅当这些字段仍与失败的候选项匹配时才会回滚。

这可以防止以下典型竞态：

持久化的回退覆盖项消除了这一时间窗口，而精确范围的回滚可确保较新的手动或运行时会话变更保持不变。

可观测性与失败摘要

runWithModelFallback(...) 会记录每次尝试的详细信息，用于生成日志和面向用户的冷却提示：

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

当候选项失败、被跳过或后续故障转移成功时，结构化的 model_fallback_decision 日志还会包含扁平的 fallbackStep* 字段。这些字段明确记录尝试过的转换（fallbackStepFromModel、fallbackStepToModel、fallbackStepFromFailureReason、fallbackStepFromFailureDetail、fallbackStepFinalOutcome），使日志和诊断导出器即使在最终故障转移也失败时，仍能还原主要故障。

当所有候选项都失败时，OpenClaw 会抛出 FallbackSummaryError。外层回复运行器可以据此构建更具体的消息，例如“所有模型目前都受到速率限制”，并在已知时包含最早的冷却到期时间。

该冷却摘要会感知模型：

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

相关配置

有关以下配置，请参阅 Gateway 配置：

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由

有关更全面的模型选择和故障转移概览，请参阅 Models。