模型故障转移 (Model Failover)

Clawdbot 分两个阶段处理故障：

1. 身份验证配置文件轮换：在当前提供商内部进行。
2. 模型回退：回退到 agents.defaults.model.fallbacks 中的下一个模型。

本篇文档解释了运行时规则及其背后的数据。

身份验证存储 (密钥 + OAuth)

Clawdbot 为 API 密钥和 OAuth 令牌使用 身份验证配置文件 (Auth Profiles)。

• 密钥存储在 ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json（旧路径：~/.clawdbot/agent/auth-profiles.json）。
• 配置中的 auth.profiles / auth.order 仅用于 元数据 + 路由（不包含密钥）。
• 仅用于导入的旧版 OAuth 文件：~/.clawdbot/credentials/oauth.json（首次使用时导入到 auth-profiles.json）。

更多详情：/concepts/oauth

凭据类型：

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（某些提供商还包括 projectId/enterpriseUrl）

配置文件 ID (Profile IDs)

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

• 默认值：没有可用电子邮件时为 provider:default。
• 带电子邮件的 OAuth：provider:<email>（例如 google-antigravity:user@gmail.com）。

配置文件存储在 auth-profiles.json 的 profiles 字段下。

轮换顺序

当一个提供商拥有多个配置文件时，Clawdbot 按如下顺序选择：

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

如果未配置显式顺序，Clawdbot 使用轮询 (round‑robin) 顺序：

• 主要关键字：配置文件类型（OAuth 优先于 API 密钥）。
• 次要关键字：usageStats.lastUsed（每种类型内，最早使用的优先）。
• 冷却中/禁用的配置文件：移动到最后，按过期时间最早的排序。

会话粘性 (缓存友好)

Clawdbot 会 为每个会话锁定所选的身份验证配置文件，以保持提供商缓存的热度。 它 不会 在每次请求时轮换。锁定的配置文件将一直重用，直到：

• 会话被重置 (/new / /reset)
• 压缩完成（压缩计数增加）
• 配置文件进入冷却/被禁用

通过 /model …@<profileId> 进行手动选择会为该会话设置 用户覆盖 (user override)，并且在开启新会话之前不会自动轮换。

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

为什么 OAuth 看起来会“丢失”

如果您为同一个提供商同时拥有 OAuth 配置文件和 API 密钥配置文件，除非锁定，否则轮询机制可能会在消息之间切换。要强制使用单个配置文件：

• 使用 auth.order[provider] = ["provider:profileId"] 进行锁定，或者
• 通过 /model … 使用配置文件覆盖（如果您的 UI/聊天界面支持）来进行按会话的覆盖。

冷却时间 (Cooldowns)

当配置文件由于身份验证/速率限制错误（或看起来像速率限制的超时）而失败时，Clawdbot 会将其标记为冷却中并移动到下一个配置文件。 格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID 验证失败）被视为值得故障转移的情况，并使用相同的冷却时间。

冷却时间使用指数退避：

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

状态存储在 auth-profiles.json 的 usageStats 字段下：

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

计费禁用 (Billing disables)

Billing/credit failures (for example “insufficient credits” / “credit balance too low”) are treated as failover‑worthy, but they’re usually not transient. Instead of a short cooldown, Clawdbot marks the profile as disabled (with a longer backoff) and rotates to the next profile/provider.

State is stored in auth-profiles.json:

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

Defaults:

• Billing backoff starts at 5 hours, doubles per billing failure, and caps at 24 hours.
• Backoff counters reset if the profile hasn’t failed for 24 hours (configurable).

Model fallback

If all profiles for a provider fail, Clawdbot moves to the next model in agents.defaults.model.fallbacks. This applies to auth failures, rate limits, and timeouts that exhausted profile rotation (other errors do not advance fallback).

When a run starts with a model override (hooks or CLI), fallbacks still end at agents.defaults.model.primary after trying any configured fallbacks.

Related config

See Gateway configuration for:

• 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 routing

See Models for the broader model selection and fallback overview.