​

Model failover

1. 当前 provider 内的 Auth profile 轮换。
2. Model 后备 到 agents.defaults.model.fallbacks 中的下一个 model。

​

Auth 存储(keys + OAuth)

• Secrets 位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json(传统:~/.openclaw/agent/auth-profiles.json)。
• 配置 auth.profiles / auth.order 是 仅元数据 + 路由(无 secrets)。
• 传统的仅导入 OAuth 文件:~/.openclaw/credentials/oauth.json(首次使用时导入 auth-profiles.json)。

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ 某些 providers 的 projectId/enterpriseUrl)

​

Profile IDs

• 默认:当没有 email 可用时为 provider:default。
• 带 email 的 OAuth:provider:<email>(例如 google-antigravity:[email protected])。

​

轮换顺序

1. 显式配置:auth.order[provider](如果设置)。
2. 配置的 profiles:按 provider 过滤的 auth.profiles。
3. 存储的 profiles:auth-profiles.json 中该 provider 的条目。

• 主键: profile 类型(OAuth 优先于 API keys)。
• 次键: usageStats.lastUsed(最旧的优先,在每种类型内)。
• Cooldown/disabled profiles 移到末尾,按最快到期时间排序。

​

Session 粘性(缓存友好)

• session 被重置(/new / /reset)
• compaction 完成(compaction 计数增加)
• profile 处于 cooldown/disabled

​

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

• 使用 auth.order[provider] = ["provider:profileId"] 固定,或
• 通过 /model … 使用 profile 覆盖(在你的 UI/chat 表面支持时)进行每个 session 覆盖。

​

Cooldowns

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

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

​

账单禁用

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

• 账单退避从 5 小时 开始,每次账单失败加倍,上限为 24 小时。
• 如果 profile 在 24 小时 内没有失败(可配置),退避计数器重置。

​

Model 后备

​

相关配置

• 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 路由