Model failover

Moltbot 分两阶段处理失败：

在当前 provider 内进行 Auth profile rotation。
在 agents.defaults.model.fallbacks 中进行 Model fallback（切换到下一个模型）。

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

Auth 存储（keys + OAuth）

Moltbot 对 API keys 与 OAuth tokens 都使用 auth profiles。

Secrets 存放在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（legacy：~/.openclaw/agent/auth-profiles.json）。
配置中的 auth.profiles / auth.order 仅包含 元数据 + 路由（不包含 secrets）。
legacy 的 import-only OAuth 文件：~/.openclaw/credentials/oauth.json（首次使用时会导入到 auth-profiles.json）。

更多细节参见：/concepts/oauth

凭据类型：

type: "api_key" → { provider, key }
type: "oauth" → { provider, access, refresh, expires, email? }（部分 providers 还包含 projectId/enterpriseUrl）

Profile IDs

OAuth 登录会创建独立 profile，以便多个账号共存。

默认：当无法获得 email 时使用 provider:default。
带 email 的 OAuth：provider:<email>（例如 google-antigravity:user@gmail.com）。

profiles 存放在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 的 profiles 下。

轮换顺序（Rotation order）

当某个 provider 有多个 profiles 时，Moltbot 按以下顺序决定尝试顺序：

显式配置：auth.order[provider]（若设置）。
配置中的 profiles：auth.profiles 中按 provider 过滤。
存储中的 profiles：auth-profiles.json 中该 provider 的 entries。

如果没有显式 order，Moltbot 使用 round‑robin 顺序：

主排序键：profile 类型（OAuth 优先于 API keys）。
次排序键：usageStats.lastUsed（在每种类型内部，最久未用的优先）。
cooldown/disabled 的 profiles 会被移到末尾，并按“最早恢复时间”排序。

Session 黏性（cache 友好）

Moltbot 会 按 session 固定（pin）选中的 auth profile，以保持 provider caches 处于热状态。它不会每次请求都轮换。该 pinned profile 会持续复用，直到：

session 被重置（/new / /reset）
compaction 完成（compaction count 增加）
profile 处于 cooldown/disabled

通过 /model …@<profileId> 的手动选择会为该 session 设置一个 用户覆盖（override），并且在新 session 开始之前不会自动轮换。

自动 pin 的 profiles（由 session router 选择）被视为一种偏好：它们会被优先尝试，但在遇到限流/超时时 Moltbot 可能会轮换到另一个 profile。用户 pin 的 profiles 会锁定在该 profile；如果它失败且配置了模型 fallbacks，Moltbot 会切换到下一个模型，而不是在同一 provider 内切换 profiles。

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

如果同一 provider 同时存在 OAuth profile 与 API key profile，在未 pin 的情况下，round‑robin 可能会在不同消息之间切换它们。若希望强制使用单一 profile：

通过 auth.order[provider] = ["provider:profileId"] 固定顺序，或
在支持的 UI/聊天表面中，通过 /model … 携带 profile override 做 per-session 覆盖。

Cooldowns

当某个 profile 因鉴权/限流错误（或看起来像限流的超时）失败时，Moltbot 会将其标记为 cooldown，并切换到下一个 profile。格式错误/invalid-request 错误（例如 Cloud Code Assist 的 tool call ID 校验失败）也被视为值得 failover 的错误，并使用同样的 cooldown 机制。

cooldowns 使用指数退避：

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

状态存放在 auth-profiles.json 的 usageStats：

json

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

Billing disables

计费/余额失败（例如 “insufficient credits” / “credit balance too low”）也被视为值得 failover 的错误，但通常不是瞬时问题。此时 Moltbot 不会做短暂 cooldown，而会将 profile 标记为 disabled（更长的退避），并轮换到下一个 profile/provider。

状态同样存放在 auth-profiles.json：

json

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

默认值：

Billing backoff 从 5 小时开始，每次 billing failure 翻倍，并在 24 小时封顶。
如果该 profile 在 24 小时内没有再次失败，则退避计数会重置（可配置）。

Model fallback

如果某个 provider 的所有 profiles 都失败，Moltbot 会切换到 agents.defaults.model.fallbacks 中的下一个模型。这对鉴权失败、限流与“耗尽 profile rotation 的超时”生效（其他错误不会推进 fallback）。

当一次 run 以模型覆盖启动（hooks 或 CLI）时，在尝试任意已配置 fallbacks 后，fallbacks 仍会回到 agents.defaults.model.primary 结束。

Model failover ​

Auth 存储（keys + OAuth） ​

Profile IDs ​

轮换顺序（Rotation order） ​

Session 黏性（cache 友好） ​

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

Cooldowns ​

Billing disables ​

Model fallback ​

相关配置 ​