模型故障转移

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

​

运行流程

​

选择来源策略

• 已配置默认值: agents.defaults.model.primary 使用 agents.defaults.model.fallbacks。
• Agent 主模型: agents.entries.*.model 默认是严格模式，除非该 agent 的 model 对象包含自己的 fallbacks。使用 fallbacks: [] 可显式启用严格行为，或提供一个非空列表让该 agent 使用模型回退。
• 运行时回退: 回退候选项仅适用于当前轮次。下一轮会再次从所选主模型开始。OpenClaw 仍会识别之前保存的 modelOverrideSource: "auto" 条目，每 5 分钟探测其配置来源一次，并在来源恢复后将其清除。/new、/reset 和 sessions.reset 也会清除这些条目。
• 用户会话覆盖: /model、模型选择器、session_status(model=...) 和 sessions.patch 会写入 modelOverrideSource: "user"。这是一个精确的会话选择。如果所选 provider/model 在生成回复前失败，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 仅用于元数据和路由（不包含密钥）。
• 旧版的 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

• 默认：provider:default（无可用电子邮件地址时）。
• 带电子邮件地址的 OAuth：provider:<email>（例如 openai:[email protected]）。

​

轮换顺序

• 主键： 配置文件类型（OAuth，然后是静态 token，最后是 API key）。
• OAuth 的次键： 当前可用访问令牌的配置文件优先于 访问令牌已过期的配置文件。已过期的 OAuth 配置文件仍保留资格， 这样当没有可用的同类配置文件时，运行时可以刷新它们。
• 下一个键： usageStats.lastUsed（在每个类型/状态层级内按最久未使用优先）。
• 冷却/已禁用配置文件 会被移动到末尾，并按最早过期时间排序。

​

会话粘性（缓存友好）

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

​

OpenAI Codex 订阅加 API 密钥备用

{
  auth: {
    order: {
      openai: ["openai:[email protected]", "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"
    }
  }
}

​

模型回退

​

候选链规则

​

哪些错误会推进回退

​

冷却跳过 vs 探测行为

​

会话覆盖与实时模型切换

• 只有用户显式驱动的模型变更才会标记待处理的实时切换。其中包括 /model、session_status(model=...) 和 sessions.patch。
• 由系统驱动的模型变更，例如回退轮换、心跳覆盖或压缩，绝不会自行标记待处理的实时切换。
• 用户驱动的模型覆盖会被视为回退策略的精确选择，因此不可达的已选提供方会直接表现为失败，而不会被 agents.defaults.model.fallbacks 掩盖。
• 运行时回退候选仍然局限于当前轮次。下一轮会从当前所选模型开始，包括上一轮运行期间到达的手动选择。
• 先前存储的自动回退覆盖仍受支持：OpenClaw 会定期探测其配置的来源，并在恢复后清除该覆盖；/new、/reset 和 sessions.reset 会立即清除自动来源的覆盖。
• 用户回复会在每次状态变更时通报回退转换和回退清除后的恢复。同一已选/活动配对的重复轮次不会重复该通知。
• /status 会显示所选模型，以及在回退状态不同时，显示活动的回退模型和原因。
• 实时会话协调优先使用持久化的会话覆盖，而不是过时的运行时模型字段。
• 如果实时切换错误指向当前回退链中的更后一个候选，OpenClaw 会直接跳转到该所选模型，而不是先遍历无关候选。

​

可观测性与失败摘要

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

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

​

相关配置

• auth.profiles / auth.order
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由