模型故障转移

OpenClaw 分两个阶段处理故障：

1. 当前提供商内的身份验证配置文件轮换。

2. ''模型回退''到 ''agents.defaults.model.fallbacks'' 中的下一个模型。

本文档解释了运行时规则以及支持它们的数据。

OpenClaw 对 API 密钥和 OAuth 令牌使用身份验证配置文件。

- Secrets live in ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json'' (legacy: ''~/.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''）

OAuth 登录创建不同的配置文件，以便多个帐户可以共存。

- 默认值：''provider:default''（当没有可用电子邮件时）。

- OAuth with email: ''provider:<email>'' (e.g., ''google-antigravity:[email protected]'').

Profiles live under ''profiles'' in ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json''.

当提供者有多个配置文件时，OpenClaw 选择如下顺序：

1. ''显式配置''：''auth.order[provider]''（如果设置）。

2. ''配置的配置文件''：''auth.profiles'' 由提供商过滤。

3. ''存储的配置文件''：提供商的 ''auth-profiles.json'' 中的条目。

如果没有配置明确的顺序，OpenClaw 将使用循环顺序：

- 主键：配置文件类型（API 密钥之前的 OAuth）。

- ''辅助键：'' ''usageStats.lastUsed''（每种类型中，最旧的在前）。

- 冷却/禁用配置文件移至末尾，按最早到期时间排序。

#

OpenClaw 固定每个会话所选的身份验证配置文件，以保持提供程序缓存的温暖。

它不会根据每个请求轮换。固定的配置文件将被重复使用，直到：

- 会话重置 (''/new'' / ''/reset'')

- 压缩完成（压缩计数增量）

- 个人资料处于冷却/禁用状态

Manual selection via ''/model …@<profileId>'' sets a ''user override'' for that session

并且在新会话开始之前不会自动轮换。

自动固定的配置文件（由会话路由器选择）被视为首选项：

首先尝试它们，但 OpenClaw 可能会在速率限制/超时方面轮换到另一个配置文件。

用户固定的配置文件保持锁定到该配置文件；如果失败和模型回退

配置完成后，OpenClaw 会移动到下一个模型，而不是切换配置文件。

如果您同时拥有同一提供商的 OAuth 配置文件和 API 密钥配置文件，则循环可以跨消息在它们之间进行切换，除非已固定。强制使用单个配置文件：

- 用 ''auth.order[provider] = ["provider:profileId"]'' 固定，或

- 通过 ''/model …'' 使用每会话覆盖和配置文件覆盖（当您的 UI/聊天界面支持时）。

当配置文件由于身份验证/速率限制错误（或看起来像超时）而失败时

就像速率限制一样），OpenClaw 将其标记为冷却并移至下一个配置文件。

格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID

验证失败）被视为值得进行故障转移并使用相同的冷却时间。

冷却时间使用指数退避：

- 1 分钟

- 5分钟

- 25 分钟

- 1 小时（上限）

{
  "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'' 尝试任何配置的后备后。

请参阅''网关配置'' 了解：

- ''auth.profiles'' / ''auth.order''

- ''auth.cooldowns.billingBackoffHours'' / ''auth.cooldowns.billingBackoffHoursByProvider''

- ''auth.cooldowns.billingMaxHours'' / ''auth.cooldowns.failureWindowHours''

- ''agents.defaults.model.primary'' / ''agents.defaults.model.fallbacks''

- ''agents.defaults.imageModel'' 路由

有关更广泛的模型选择和后备概述，请参阅''模型''。