模型故障转移

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

​

运行时流程

​

选择来源策略

• 已配置默认值：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 将其视为用户覆盖，因此显式旧选择不会被静默转换为回退行为。
• Cron 载荷模型：cron 作业 payload.model / --model 是作业主模型，不是用户会话覆盖。除非作业提供 payload.fallbacks，否则它使用已配置回退；payload.fallbacks: [] 会让 cron 运行变为严格模式。

​

凭证失败跳过缓存

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

用户可见的回退通知

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

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

​

凭证存储（密钥 + 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 导入。

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（某些提供商还包括 projectId/enterpriseUrl）
• type: "token" → 静态 bearer 风格令牌，可选过期时间；OpenClaw 不会刷新它（用于 aws-sdk 和其他凭据链凭证模式）

​

配置 ID

• 默认：没有可用 email 时为 provider:default。
• 带 email 的 OAuth：provider:<email>（例如 google-antigravity:user@gmail.com）。

​

轮换顺序

• **主键：**配置类型（OAuth，然后静态令牌，然后 API 密钥）。
• 次键：usageStats.lastUsed（每种类型内最旧的优先）。
• 冷却/禁用配置会移到末尾，并按最早到期时间排序。

​

会话粘性（缓存友好）

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

​

OpenAI Codex 订阅加 API 密钥备份

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

​

冷却

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

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

​

账单禁用

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

​

模型回退

​

候选链规则

​

哪些错误会推进回退

​

冷却跳过与探测行为

​

会话覆盖和实时模型切换

• 只有显式的用户驱动模型变更才会标记待处理实时切换。这包括 /model、session_status(model=...) 和 sessions.patch。
• 系统驱动的模型变更，例如回退轮换、Heartbeat 覆盖或压缩，本身永远不会标记待处理实时切换。
• 用户驱动的模型覆盖会被视为回退策略的精确选择，因此不可达的已选提供商会暴露为失败，而不是被 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.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由