模型回退

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:user@gmail.com）。

配置文件存在于 ~/.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 将其标记为冷却并移动到下一个配置文件。格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID 验证失败）被视为值得回退，并使用相同的冷却。 OpenAI 兼容的停止原因错误，如 Unhandled stop reason: error、stop reason: error 和 reason: error 被分类为超时/回退信号。

冷却使用指数退避：

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 中的下一个模型。这适用于认证失败、速率限制和耗尽配置文件轮换的超时（其他错误不推进回退）。

当运行使用模型覆盖（钩子或 CLI）启动时，回退在尝试任何配置的回退后仍然在 agents.defaults.model.primary 结束。

模型回退

模型回退

认证存储（密钥 + OAuth）

配置文件 ID

轮换顺序

会话粘性（缓存友好）

为什么 OAuth 可能"看起来丢失"

冷却

计费禁用

模型回退

相关配置