模型故障转移

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

​

运行流程

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

选择来源策略

• 已配置默认值：agents.defaults.model.primary 使用 agents.defaults.model.fallbacks。
• Agent 主项：agents.list[].model 默认是严格的，除非该 agent 的模型对象包含它自己的 fallbacks。使用 fallbacks: [] 可以明确表示严格行为，或者提供一个非空列表，让该 agent 启用模型回退。
• 自动回退覆盖：运行时回退会在重试前写入 providerOverride、modelOverride、modelOverrideSource: "auto" 以及所选的原始模型。该自动覆盖可以继续沿着已配置的回退链向下走，而不必在每条消息上都去探测主项，但 OpenClaw 会周期性地再次探测已配置的原始项，并在其恢复时清除自动覆盖。/new、/reset 和 sessions.reset 也会清除自动来源的覆盖。若未显式提供 heartbeat.model，心跳会在其原始项不再与当前已配置默认值匹配时清除直接的自动覆盖。
• 用户会话覆盖：/model、模型选择器、session_status(model=...) 和 sessions.patch 会写入 modelOverrideSource: "user"。这是一种精确的会话选择。如果所选提供方/模型在产生回复前失败，OpenClaw 会报告失败，而不是从无关的已配置回退中回答。
• 旧版会话覆盖：较旧的会话条目可能只有 modelOverride 而没有 modelOverrideSource。OpenClaw 会将这些视为用户覆盖，因此显式的旧选择不会被静默转换为回退行为。
• Cron 负载模型：cron 作业的 payload.model / --model 是作业主项，而不是用户会话覆盖。它会使用已配置回退，除非作业提供了 payload.fallbacks；payload.fallbacks: [] 会让 cron 运行保持严格。

​

Auth failure skip cache

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

面向用户的回退通知

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

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

​

认证存储（密钥 + OAuth）

• Secrets and runtime auth-routing state live in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Config auth.profiles / auth.order are metadata + routing only (no secrets).
• Legacy import-only OAuth file: ~/.openclaw/credentials/oauth.json (imported into the per-agent auth store on first use).
• Legacy auth-profiles.json, auth-state.json, and per-agent auth.json files are imported by openclaw doctor --fix.

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（某些提供方还会带有 projectId/enterpriseUrl）

​

配置文件 ID

• 默认：当没有可用邮箱时为 provider:default。
• 带邮箱的 OAuth：provider:<email>（例如 google-antigravity:[email protected]）。

​

轮换顺序

• 主键： 配置文件类型（OAuth 在 API 密钥之前）。
• 次键： usageStats.lastUsed（在每种类型内部，最早使用的优先）。
• 冷却/禁用的配置文件 会被移到末尾，并按最早到期时间排序。

​

会话粘性（缓存友好）

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

​

OpenAI Codex 订阅加 API 密钥备用

{
  auth: {
    order: {
      openai: ["openai:[email protected]", "openai:api-key-backup"],
    },
  },
}

​

冷却

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

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

​

Billing 禁用

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

• 计费退避从 5 小时 开始，每次计费失败翻倍，最高 24 小时。
• 如果配置文件在 24 小时 内没有失败，退避计数会重置（可配置）。
• 过载重试在进入模型回退前，允许 1 次同提供商配置文件轮换。
• 过载重试默认使用 0 ms 退避。

​

模型回退

​

候选链规则

​

哪些错误会推进回退

​

冷却跳过 vs 探测行为

​

会话覆盖与实时模型切换

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

​

可观测性与失败摘要

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

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

​

相关配置

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