模型故障转移

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 验证失败)被视为值得故障转移,并使用相同的冷却机制。

冷却使用指数退避:

1 分钟
5 分钟
25 分钟
1 小时(上限)

状态存储在 auth-profiles.json 的 usageStats 下:

json

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

计费禁用

计费/额度故障(例如"额度不足"/"额度余额过低")被视为值得故障转移,但它们通常不是瞬时的。OpenClaw 不会使用短期冷却,而是将配置文件标记为禁用(使用更长的退避时间)并轮换到下一个配置文件/提供商。

状态存储在 auth-profiles.json:

json

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

默认值:

计费退避从 5 小时开始,每次计费失败加倍,上限为 24 小时。
如果配置文件 24 小时内未失败(可配置),退避计数器会重置。

模型回退

如果提供商的所有配置文件都失败,OpenClaw 会转移到 agents.defaults.model.fallbacks 中的下一个模型。这适用于认证失败、速率限制和耗尽配置文件轮换的超时(其他错误不会推进回退)。

当运行以模型覆盖(钩子或 CLI)开始时,回退仍会在尝试任何已配置的回退后结束于 agents.defaults.model.primary。

模型故障转移 ​

认证存储(密钥 + OAuth) ​

配置文件 ID ​

轮换顺序 ​

会话粘性(缓存友好) ​

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

冷却 ​

计费禁用 ​

模型回退 ​

相关配置 ​