模型故障转移

OpenClaw 的失败处理分两个阶段：

在当前 provider 内轮换 auth profile。
当所有 profile 均失效时，回退到 agents.defaults.model.fallbacks 中的下一个模型。

本文介绍运行时规则以及背后的数据结构。

Auth 存储（API Key 与 OAuth）

OpenClaw 对 API key 和 OAuth token 统一使用 auth profile 机制。

密钥保存在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（旧版路径：~/.openclaw/agent/auth-profiles.json）。
配置中的 auth.profiles / auth.order 仅作元数据与路由用途，不存储实际密钥。
旧版仅导入的 OAuth 文件：~/.openclaw/credentials/oauth.json（首次使用时会导入到 auth-profiles.json）。

更多细节参见 /openclaw/concepts/oauth。

凭据类型：

type: "api_key" → { provider, key }
type: "oauth" → { provider, access, refresh, expires, email? }（部分 provider 还有 projectId/enterpriseUrl）

Profile ID

OAuth 登录会创建独立的 profile，允许多个账号共存。

默认：无 email 时使用 provider:default。
有 email 的 OAuth：provider:<email>（例如 google-antigravity:user@gmail.com）。

Profile 存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 的 profiles 字段下。

轮换顺序

当一个 provider 有多个 profile 时，OpenClaw 按以下顺序选择：

显式配置：auth.order[provider]（若已设置）。
已配置的 profile：按 provider 过滤 auth.profiles。
存储的 profile：auth-profiles.json 中该 provider 的条目。

若未配置显式顺序，OpenClaw 使用轮询（round-robin）：

主排序键：profile 类型（OAuth 优先于 API key）。
次排序键：usageStats.lastUsed（同类型内最早使用的优先）。
cooldown/禁用的 profile 排到末尾，按最早到期时间排序。

Session 粘性（对缓存友好）

OpenClaw 在 session 内固定选中的 auth profile，以保持 provider 缓存热度。它不会对每个请求都轮换。固定的 profile 会被复用，直到：

session 重置（/new / /reset）
压缩完成（compaction count 递增）
该 profile 进入 cooldown 或被禁用

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

自动固定的 profile（由 session router 选出）被视为偏好：优先尝试，但在遇到限流/超时时 OpenClaw 可能轮换到其他 profile。用户手动固定的 profile 则锁定在该 profile；若失败且配置了模型回退，OpenClaw 会切换到下一个模型而非换 profile。

OAuth 为何会"看起来丢失"

如果同一 provider 同时有 OAuth profile 和 API key profile，在未固定的情况下 round-robin 可能在消息之间来回切换。要强制使用单一 profile：

在配置中固定：auth.order[provider] = ["provider:profileId"]，或
通过 /model … 做 per-session 覆盖（具体取决于你的 UI/chat 界面是否支持）。

Cooldown（冷却期）

当 profile 因认证/限流错误（或看起来像限流的超时）失败时，OpenClaw 将其标记为 cooldown 并切换到下一个 profile。格式/请求无效错误（例如 Cloud Code Assist tool call ID 校验失败）也视为需要故障转移并使用相同的 cooldown 机制。OpenAI 兼容的 stop-reason 错误（如 Unhandled stop reason: error、stop reason: error、reason: error）被归类为超时/故障转移信号。

Cooldown 采用指数退避：

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

状态存储在 auth-profiles.json 的 usageStats 中：

json

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

账单禁用

账单/余额不足错误（如"insufficient credits"/"credit balance too low"）会触发故障转移，但通常不是临时性问题。OpenClaw 不使用短 cooldown，而是将 profile 标记为禁用（较长的退避期）并轮换到下一个 profile/provider。

状态存储在 auth-profiles.json 中：

json

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

默认值：

账单退避从 5 小时开始，每次账单失败翻倍，上限 24 小时。
若 profile 在 24 小时内未再失败，退避计数器重置（可配置）。

模型回退

若某 provider 的所有 profile 均失败，OpenClaw 会切换到 agents.defaults.model.fallbacks 中的下一个模型。这适用于认证失败、限流和耗尽 profile 轮换的超时（其他错误不会触发回退）。

当某次运行以模型覆盖启动时（通过 hooks 或 CLI），回退仍会在尝试所有已配置的 fallback 后终止于 agents.defaults.model.primary。

小龙虾养久了，备胎模型链就是你的安全网——主力龙虾挂了，备用龙虾顶上。

模型故障转移 ​

Auth 存储（API Key 与 OAuth） ​

Profile ID ​

轮换顺序 ​

Session 粘性（对缓存友好） ​

OAuth 为何会"看起来丢失" ​

Cooldown（冷却期） ​

账单禁用 ​

模型回退 ​

相关配置 ​