跳转至

模型故障转移

OpenClaw 在以下两个阶段处理失败:

  1. 在当前提供者内部进行 Auth-profile 轮换。
  2. 模型回退 到 agents.defaults.model.fallbacks 中的下一个模型。

在轮换 profile 或更换模型之前,运行器会针对临时速率限制和提供者故障尝试有界限的 same-model 恢复。它会继续使用现有 transcript,保留部分输出和已完成的工作。智能体会被指示先检查被中断的操作,再决定是否重复执行。重试状态会显示等待时间和尝试次数。取消功能仍然可用。无需额外配置。

ChatGPT Responses WebSocket 连接过期也遵循此恢复策略,即使流式传输已经开始。失败的 socket 会被弃用;恢复会继续使用已保存的 transcript,而不是在传输层内重新播放请求。

Anthropic 流式错误会保留其结构化错误类型,因此即使提供者的消息是通用文本,速率限制、过载和身份验证失败也遵循相同的恢复策略。

本地 transcript 写入冲突不会重试模型、轮换账号或触发模型回退。Transcript 所有者会重新读取当前修订版本,并重试一次符合条件的追加操作。重复冲突会作为本地错误报告;较旧的回复无法覆盖或绕过较新的用户轮次。

Thinking 级恢复仅在提供者标识了 reasoning 或 thinking 参数时适用。模型/账号限制以及无关的不支持选项会保持其原始失败分类,并遵循已配置的回退策略。OpenClaw 不会在禁用 thinking 的情况下重试这些错误。

运行时流程

1. 解析会话状态

解析当前会话的模型和 auth-profile 偏好。

2. 构建候选链

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

3. 尝试当前提供者

按照 auth-profile 轮换/冷却规则尝试当前提供者。运行器会在轮换 profile 或推进模型回退之前,对符合条件的瞬时故障进行有界限的恢复。

4. 在出现值得故障转移的错误时推进

如果当前提供者因值得故障转移的错误而耗尽,则移至下一个模型候选。

5. 对当前轮次使用回退

运行获胜的回退候选,而不更改会话当前选定的提供者/模型。

6. 如果全部耗尽则报告失败

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

回退执行仅限于当前轮次。回复运行器仅持久化回退通知状态,以便 /status 和转换通知能够区分所选模型与实际回答的模型。它不会将回退持久化为下一轮次的模型选择。

放置在 OpenClaw 云端 worker 上的会话在自动模型选择推进到回退时仍保留 OpenClaw 运行时。已配置的提供者、模型和 auth-profile 回退规则仍然适用。显式的会话或已配置的运行时选择保持严格:不兼容的运行时报告放置错误,并在重试前要求使用兼容的目标。

当已配置的回退因智能体运行达到最终超时,或 idle-timeout 成本失控断路器返回终止错误而停止时,model-fallback/decision 日志会记录 model_fallback_chain_stopped,并附上原因 agent_run_terminal_timeout 或 idle_timeout_circuit_breaker。这些是终止性停止,而非提供者失败或请求尝试另一个模型。现有的运行截止时间和成本限制仍然适用。

自动 cyber 策略升级

嵌入式 OpenClaw 运行器会在 Daybreak Blue 上重试一次可安全 replay 的 OpenAI cyber 策略拒绝。这包括使用 ChatGPT 认证的 OpenAI Responses 传输层的普通嵌入式轮次,而不仅限于 Codex 插件会话。该传输层将 OpenAI 结构化的 cyber 策略错误投射到此策略所使用的拒绝元数据中,且覆盖其可能到达的每个终止路径:非 OK 的 HTTP body、流式 error 事件,以及 response.failed 事件。没有结构化 cyber 类别的通用拒绝文本仍然是终止性的。

此策略路由仅限当前轮次:它不会更改选定的会话模型,也不会将普通提供者失败发送到 Daybreak。Codex 支持的会话保留其独立的、插件所属的策略,相关说明见 Codex harness runtime behavior。

默认目标是 openai/gpt-daybreak-blue-latest。仅当以下所有条件均满足时才执行重试:

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

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

如果 Daybreak 尝试在未提交工作的情况下失败,OpenClaw 会保留原始的提供者拒绝,而不会尝试无关的已配置回退。如果重试在失败前已执行了工具或交付了输出,则保留其自身结果,因为其回放判定、交付证据和终止收据描述了实际运行的内容。如果重试抛出普通 failover 类错误以外的任何异常,该异常将原样传播:已记录的终止性停止禁止重放,而未分类的抛出正是回退运行器报告已提交工作的尝试的方式。授权失败会使该目标在当前会话中进入冷却状态,之后另一个 cyber 拒绝才会再次检查它。

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

通用模型回退顺序保持不变。非 cyber 拒绝、Codex/原生 harness 结果, 或任何不可重放的尝试,在现有拒绝策略下仍为终止状态。

选择来源策略

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

  • 已配置默认值:agents.defaults.model.primary 使用 agents.defaults.model.fallbacks。
  • 原生 agent 主模型:agents.entries.*.model 是严格的,除非该 agent 的 model 对象包含自己的 fallbacks。使用 fallbacks: [] 可显式表示严格行为,或使用非空列表让该 agent 加入模型回退。
  • ACP agent 主模型:对于 runtime.type: "acp",agent 主模型选择其外部 harness 模型。原生 OpenClaw 调用从 agents.defaults.model 继承主模型和回退;显式的 agent model.fallbacks 会替换原生回退列表,包括使用 [] 禁用它。显式的原生 session 和 subagent 选择保留其正常优先级和严格性。这不会为仅运行其所选模型的命令(例如 /btw)添加回退。
  • 运行时回退:回退候选仅适用于当前轮次。下一轮再次从所选主模型开始。OpenClaw 仍会识别由 v2026.4.26 到 v2026.6.0 存储的 modelOverrideSource: "auto" 条目。它会每 5 分钟检查其已配置的来源,并在来源恢复后清除它们。自动清除功能已在 v2026.6.1 中发布。/new、/reset 和 sessions.reset 也会清除这些条目。
  • 用户 session 覆盖:通过 /model、模型选择器、session_status(model=...) 或 sessions.patch 选择特定模型时,会写入 modelOverrideSource: "user"。这是精确的 session 选择。如果所选 provider/model 在生成回复前失败,OpenClaw 会报告失败,而不是从不相关的已配置回退中回答。
  • 显式已配置默认值:通过相同界面选择 Default 时,会写入 modelOverrideSource: "default",而不存储 provider/model 覆盖。这可防止子 session 继承父级模型固定,同时保留已配置默认值的正常回退策略。
  • 旧版 session 覆盖:在 v2026.4.26 之前写入的 session 条目可能具有 modelOverride 但没有 modelOverrideSource。OpenClaw 将这些视为用户覆盖,以免显式的旧选择被静默转换为回退行为。
  • Cron payload 模型:cron 任务的 payload.model / --model 是任务主模型,而不是用户 session 覆盖。除非任务提供 payload.fallbacks,否则它使用已配置的回退。payload.fallbacks: [] 会使 cron 运行变为严格模式。

agent 只能使用 model: { fallbacks: [...] } 覆盖其回退链,并继续继承共享主模型。显式设置 fallbacks: [] 会禁用 回退,而不会固定该主模型。在 Settings → Agents → Overview 中,编辑 回退 chips 会保留主模型继承。移除所有 chips 会保存空链,而不是恢复共享回退。

身份验证存储(密钥 + OAuth)

OpenClaw 对 API 密钥和 OAuth token 均使用 auth profiles。

  • 密钥和运行时 auth 路由状态位于 ~/.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 采用失败关闭策略。 它绝不会静默导入或回退到这些文件。

更多详情:OAuth

凭据类型:

  • type: "api_key" → { provider, key }
  • type: "oauth" → { provider, access, refresh, expires, email? }(某些 provider 还包括 projectId/enterpriseUrl)
  • type: "token" → 静态 bearer 风格 token,可选过期。OpenClaw 不会刷新它(用于 aws-sdk 和其他凭据链 auth 模式)

Profile ID

OAuth 登录会创建不同的 profile,以便多个账户可以共存。

  • 默认:在没有 email 可用时为 provider:default。
  • 带 email 的 OAuth:provider:<email>(例如 openai:user@example.com)。

Profile 位于每个 agent 的 openclaw-agent.sqlite auth profile 存储中。

轮换顺序

当某个 provider 有多个 profile 时,OpenClaw 会按类似以下顺序选择:

1. 已存储的顺序覆盖

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

2. 显式配置

auth.order[provider](如果已设置)。

3. 已配置的 profile

按 provider 过滤的 auth.profiles。

4. 已存储的 profile

该 provider 的每个 agent SQLite auth profile 条目。

如果未配置显式顺序,OpenClaw 会使用轮询顺序:

  • 主键:profile 类型(OAuth,然后是静态 token,然后是 API key)。
  • OAuth 的次键:当前具有可用 access token 的 profile 优先于 access token 已过期的 profile。已过期的 OAuth profile 仍保持可用,以便 运行时在没有可用同级 profile 时可以刷新它们。
  • 下一键:usageStats.lastUsed(在每个类型/状态层级内,最旧的优先)。
  • 冷却/禁用 profile 会被移到末尾,并按最早过期时间排序。

Session 粘性(对缓存友好)

清除或轮换 auth pin 仅影响所选 agent 的 session,包括自定义 session 存储以及保留的 global 和 unknown session 键。

OpenClaw 按 session 固定自动选择的 auth profile,以保持 provider 缓存处于热状态。它不会在每次请求时轮换。自动 pin 可能在以下情况下轮换或清除:

  • session 被重置(/new / /reset)
  • profile 处于冷却/禁用状态

上下文压缩不会更改已选择的认证配置。健康的配置会在压缩过程中保持固定;认证失败和不可用的配置仍会使用正常的回退顺序。

通过 /model …@<profileId> -s 进行的手动选择会设置一个用户覆盖。有效的用户固定项可以跨越 /new、/reset、会话滚动、压缩和冷却窗口而保留。只要符合条件,它仍会保持为首选。当该确切配置处于冷却或被禁用时,OpenClaw 会尝试下一个符合条件的同一提供商配置,而不会替换已存储的固定项。显式删除已保存的凭据会清除其受影响的智能体模型和会话账户选择,同时保留已选择的模型。其他账户(包括由另一个智能体拥有的独立凭据)会保留其选择。暂时缺失或过期的凭据不会清除用户固定项;刷新可以恢复访问。如果旧配置仍引用一个已删除的账户,请在 Models 中选择一个可用账户。当所选提供商发生变化时,OpenClaw 还会清除不兼容的固定项;当用户选择另一个账户时,则会替换该固定项。/model default -s 会清除模型覆盖,同时保留兼容的认证固定项并清除不兼容的固定项。

Note

自动固定和用户固定的认证配置都是重试偏好。只要所选配置符合条件,OpenClaw 会优先尝试该配置。随后,在认证失败、速率限制、计费限制或超时的情况下,它可能会轮换到另一个同一提供商的配置。用户固定项会在该临时轮换期间保持持久化。在其冷却期结束后,新的运行会再次优先使用它,而不会更改已选择的模型或运行时。这种认证轮换不会放宽模型选择:显式的用户提供商/模型选择仍保持严格,并在其同一提供商认证配置耗尽后报告失败。

OpenAI Codex 订阅与 API 密钥备份

对于 OpenAI 智能体模型,认证和运行时相互独立。openai/gpt-* 会保持在 Codex 运行框架上,而认证可以在 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 运行框架内。一旦重置时间过去,订阅配置再次符合条件,下一次自动选择可以返回该配置。

使用用户固定的配置,可将某个账户/密钥设为该会话中持久的首选。如果它变得不可用,OpenClaw 会临时轮换剩余的符合条件的 auth.order.openai 配置,并在恢复后返回到固定配置。

冷却

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

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

哪些内容会落入速率限制 / 超时桶

该速率限制桶比单纯的 429 更宽泛:它还包括提供商消息,例如 Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded、throttled、resource exhausted,以及周期性用量窗口限制,例如 weekly limit reached 或 monthly limit exhausted。

格式/无效请求错误通常是终结性的,因为重试相同负载会以相同方式失败,因此 OpenClaw 会直接呈现它们,而不是轮换认证配置。已知的重试修复路径可以显式选择加入:例如,Cloud Code Assist 工具调用 ID 验证失败会被清理,并通过 allowFormatRetry 策略重试一次。

OpenAI 兼容的由提供商完成的停止/结束原因,例如 Unhandled stop reason: error、stop reason: error、reason: error 和 Provider finish_reason: error,会被归类为 server_error(类似 HTTP 状态 500),而不是超时。它们仍然值得进行模型或认证配置轮换的故障转移,但诊断信息会保留提供商结束原因文本,而不是将用户文案改写为“LLM 请求超时。”。传输类结束原因,例如 Provider finish_reason: abort、network_error 和 malformed_response,仍保留在超时/故障转移桶中(状态 408)。

HTTP 状态映射对未归类的非计时 5xx 失败使用 server_error,包括 502 和 503。HTTP 529 保留 overloaded。计时状态保留 timeout:请求超时 408、网关超时 504、522 和 524,以及 nginx 客户端中止 499。更具体的提供商错误和上下文分类保留其现有优先级。

当来源匹配已知的瞬时模式时,通用服务器文本也可能落入该超时桶。例如,裸模型运行时流包装器消息 An unknown error occurred 会被视为对所有提供商都值得故障转移。当提供商流以 stopReason: "aborted" 或 stopReason: "error" 结束且没有具体细节时,共享模型运行时会发出该消息。带有瞬时服务器文本的 JSON api_error 负载,例如 internal server error、unknown error, 520、upstream error 或 backend error,也会被处理为值得故障转移的超时。

OpenRouter 特有的通用上游文本,例如裸 Provider returned error,只有在提供商上下文确实是 OpenRouter 时才会被视为超时。通用内部回退文本,例如 LLM request failed with an unknown error.,保持保守,本身不会触发故障转移。

SDK retry-after 上限

否则,某些提供商 SDK 可能会在较长的 Retry-After 窗口内休眠,然后才将控制权交还给 OpenClaw。对于基于 Stainless 的 SDK,例如 Anthropic 和 OpenAI,OpenClaw 默认将 SDK 内部的 retry-after-ms 和 retry-after 等待时间限制在 60 秒。它会立即呈现更长的可重试响应,以便该故障转移路径可以运行。使用 OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS 调整或禁用该上限。参见重试行为。

模型作用域冷却期

速率限制冷却期也可以是模型作用域的:

  • 当已知失败模型 ID 时,OpenClaw 会为速率限制失败记录 cooldownModel。
  • 当冷却期作用域限定为另一个模型时,同一提供商上的同级模型仍可以尝试。
  • 计费/禁用窗口仍会跨模型阻止整个配置文件。

普通(非计费、非永久认证)冷却期会根据配置文件的近期错误次数递增:

  • 第 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 密钥在激活的禁用窗口期间无法重试。窗口过期后,它们会再次符合条件。另一次计费失败会开启一个新的十分钟窗口。存储的认证配置文件也可以在禁用窗口期间通过有界的主要提供商检查恢复。充值本身不会清除持久化状态,升级也不会改变已激活窗口的现有截止时间。

Note

并非所有计费类响应都是 402,也并非所有 HTTP 402 都会归入此处。即使提供商返回的是 401 或 403,OpenClaw 也会将明确的计费文本保留在计费类别中。提供商特定的匹配器仍限定于拥有它们的提供商,例如 OpenRouter 的 403 Key limit exceeded。

同时,临时的 402 使用窗口以及组织/工作区支出限制错误,在消息看起来可重试时会被归类为 rate_limit(例如 weekly usage limit exhausted、daily limit reached, resets tomorrow 或 organization spending limit exceeded)。这些会留在短冷却/故障转移路径上,而不是长计费禁用路径。

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

状态存储在每个代理的 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 秒窗口。一次完成的成功模型响应会清除该窗口,而不会重置总重试次数;仅部分输出和工具活动不会清除。一旦该预算或窗口耗尽,恢复会推进到符合条件的认证配置文件轮换、已配置的模型回退或可见错误。续接会保留转录,而不是重放原始用户请求。恢复和任何回退胜出者都保持轮次本地。

The embedded runtime's existing session setting retry.provider.maxRetries overrides its recovery retry budget. 0 disables retries, and rate limits remain capped at 10 total attempts. It is not an openclaw.json key and does not change a native harness's internal request retries. Native harnesses may finish their own request retries before OpenClaw starts continuation recovery. The reply runner does not add another whole-turn replay loop. See 重试策略 for pacing and exclusions.

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

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

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

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

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

候选链规则

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

Rules
  • 请求的模型始终排在第一位。
  • 显式配置的回退会去重,但不会按模型允许列表过滤。它们被视为显式操作员意图。
  • 如果当前运行已经位于同一提供商系列中的某个已配置回退上,OpenClaw 会继续使用完整的已配置链。
  • 当未提供显式回退覆盖时,即使请求的模型使用不同的提供商,也会先尝试已配置的回退,然后再尝试已配置的主模型。
  • 当未向回退运行器提供显式回退覆盖时,已配置的主模型会被追加到末尾。一旦前面的候选项耗尽,链随后可以回落到正常默认值。
  • 当调用方提供 fallbacksOverride 时,运行器会精确使用请求的模型加上该覆盖列表。空列表会禁用模型回退,并防止已配置的主模型作为隐藏重试目标被追加。

哪些错误会推进回退

  • 身份验证失败
  • 速率限制和冷却耗尽
  • 过载/提供商繁忙错误
  • 超时类故障转移错误
  • 计费禁用
  • model_not_found,包括符合条件的 HTTP 404 响应
  • 针对过期当前候选项或更早候选项的 LiveSessionModelSwitchError。后续配置的目标会直接重定向,而链外的目标会返回给有界的会话模型重试所有者
  • 提供商请求大小上限达到回退边界,这种情况发生在拥有传输的插件 harness 绕过嵌入式恢复时。该上限属于拒绝提供商的配额,而不是任何模型的上下文窗口,因此配置不同的候选项可能仍会接受该请求
  • 当仍有剩余候选项时的其他未识别错误
  • 非超时/故障转移类的显式中止
  • 应保留在压缩/重试逻辑内的上下文溢出错误(例如 request_too_large、input token count exceeds the maximum number of input tokens、input exceeds the maximum number of tokens、input too long for the model 或 ollama error: context length exceeded)
  • 在已声明为终止的嵌入式运行中发生的上下文溢出,包括提供商请求大小上限(例如 Groq 的 413 ... on tokens per minute (TPM): Limit 8000, Requested 8098),运行器会在此停止,而不是进行压缩
  • 没有剩余候选项时的最终未知错误
  • 最终提供商拒绝。符合条件的 Anthropic 直接 API 密钥请求会在提供商请求内处理拒绝回退(参见 Anthropic)

最终提供商拒绝会结束当前轮次。OpenClaw 会将其呈现出来,而不会进行自动恢复轮次、压缩重试或切换到不相关的模型。除了错位预防措施外,排队或后续用户消息仍会启动其自己的轮次。

错位预防措施

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

保留政策代码的较旧已保存错误也会显示安全预防措施,即使没有较新的拒绝诊断。显示该历史错误不会创建审查发现或授权继续。

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

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

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

冷却跳过与检查行为

当某个提供方的所有身份验证配置文件都已处于冷却期时,OpenClaw 不会永久自动跳过该提供方。它会按候选项做出决策:

按候选项决策
  • 持久性身份验证失败会立即跳过整个提供方。
  • 计费禁用通常会跳过,但主要候选项仍可在节流下检查,因此无需重启即可恢复。
  • 主要候选项可在冷却期临近结束时检查,并带有按提供方设置的节流。
  • 当失败看起来是暂时性的(rate_limit、overloaded 或未知)时,即使处于冷却期,也可以尝试同一提供方的回退同级项。当速率限制是模型范围且同级模型可能立即恢复时,这一点尤其相关。
  • 暂时性冷却检查每个提供方每次回退运行限制为一次,以免单个提供方阻塞跨提供方回退。

会话覆盖与实时模型切换

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

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

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

活动运行直接携带其选定的候选项。实时协调仅针对明确的待处理用户切换更改该候选项,因此无需临时回退覆盖或回滚。

当记录的回退通知属于不同的已选模型时,状态和会话列表会跳过其可选转录查找。该过时通知路径不再显示仅转录错误,也不会启动投影协调。匹配的通知使用只读转录查找,既不创建存储,也不启动投影协调。如果可选存储或投影不可用,查找会省略转录派生的详细信息。意外的读取错误仍会传播。

用户可见的回退通知

在群聊和频道会话之外,当会话切换到自动选择的回退时,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 — 检查已解析的默认值和回退

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

参见 模型提供商 了解提供商设置、凭据以及各提供商的模型目录。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw