模型回退

OpenClaw 以两个阶段处理故障：

当前提供�?认证配置轮换*�?
模型回退�?agents.defaults.model.fallbacks 中的下一个模型�?

本文档说明了运行时规则和支持这些规则的数据�?

认证存储（密�?+ OAuth�?

OpenClaw 使用认证配置来存�?API 密钥�?OAuth 令牌�?

密钥保存�?~/.openclaw/agents/<agentId>/agent/auth-profiles.json（旧版：~/.openclaw/agent/auth-profiles.json）�?
配置 auth.profiles / auth.order 仅用�?元数据和路由*（不包含密钥）�?
旧版仅导入的 OAuth 文件：~/.openclaw/credentials/oauth.json（首次使用时导入�?auth-profiles.json）�?

更多详情：/concepts/oauth

凭证类型�?

type: "api_key" �?{ provider, key }
type: "oauth" �?{ provider, access, refresh, expires, email? }（部分提供商还有 projectId/enterpriseUrl�?

配置 ID

OAuth 登录创建独立的配置，以便多个账户可以共存�?

默认值：无可用邮箱时�?provider:default�?
带邮箱的 OAuth：provider:<email>（例�?google-antigravity:[email protected]）�?

配置保存�?~/.openclaw/agents/<agentId>/agent/auth-profiles.json �?profiles 下�?

轮换顺序

当一个提供商有多个配置时，OpenClaw 按以下顺序选择�?

显式配置：auth.order[provider]（如果已设置）�?
已配置的配置：auth.profiles 按提供商过滤�?
已存储的配置：auth-profiles.json 中该提供商的条目�?

如果没有设置显式顺序，OpenClaw 使用轮询顺序�?

主要密钥�? 配置类型�?OAuth 优先�?API 密钥）�?
*次要密钥�? usageStats.lastUsed（每种类型中最早的）�?
*冷却/禁用的配�? 移到末尾，按最快过期时间排序�?

会话粘性（缓存友好�?

OpenClaw 为每个会话固定选定的认证配�?*，以保持提供商缓存温热。它不会在每次请求时轮换**。选定的配置会被重复使用，直到�?

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

通过 /model ...@<profileId> 手动选择会为该会话设�?用户覆盖*，在新会话开始之前不会自动轮换�?

自动固定的配置（由会话路由器选择）被视为偏好：它们会首先尝试，但 OpenClaw 可能在速率限制/超时时轮换到另一个配置。用户固定的配置保持锁定到该配置；如果它失败且配置了模型回退，OpenClaw 会转到下一个模型而不是切换配置�?

为什�?OAuth 看起来会”丢失”

如果同一个提供商同时�?OAuth 配置�?API 密钥配置，轮询可能会在消息之间切换它们（除非已固定）。要强制使用单一配置�?

使用 auth.order[provider] = ["provider:profileId"] 固定，或
通过 /model ... 使用每个会话的覆盖（当你�?UI/聊天界面支持时）�?

冷却�?

当配置因认证/速率限制错误（或看起来像速率限制的超时）而失败时，OpenClaw 会将其标记为冷却并转到下一个配置。格�?无效请求错误（例如云代码辅助工具调用 ID 验证失败）被视为值得回退的错误，并使用相同的冷却期�?

冷却期使用指数退避：

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

状态存储在 auth-profiles.json �?usageStats 下：

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

计费禁用

计费/积分故障（例�?积分不足”/“积分余额太低”）被视为值得回退的错误，但它们通常不是短暂的。OpenClaw 不会使用短期冷却，而是将配置标记为禁用（带有更长的退避期）并轮换到下一个配�?提供商�?

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

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

默认值：

计费退避从 5 小时开始，每次计费失败翻倍，上限�?24 小时�?
如果配置24 小时没有失败（可配置），退避计数器会重置�?

模型回退

如果提供商的所有配置都失败了，OpenClaw 会转�?agents.defaults.model.fallbacks 中的下一个模型。这适用于耗尽配置轮换后的认证失败、速率限制和超时（其他错误不会推进回退）�?

当运行以模型覆盖（hooks �?CLI）开始时，回退仍然会在尝试任何已配置的回退后结束于 agents.defaults.model.primary�?

模型回退

认证存储（密�?+ OAuth�?

配置 ID

轮换顺序

会话粘性（缓存友好�?

为什�?OAuth 看起来会”丢失”

冷却�?

计费禁用

模型回退

相关配置