​

模型故障转移

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

​

认证存储（密钥 + 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）。

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

​

配置文件 ID

• 默认值：当没有可用邮箱时为 provider:default。
• 带邮箱的 OAuth：provider:<email>（例如 google-antigravity:[email protected]）。

​

轮换顺序

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

• 主排序键： 配置文件类型（OAuth 优先于 API 密钥）。
• 次排序键： usageStats.lastUsed（同类型内最旧的优先）。
• 冷却中/已禁用的配置文件被移到末尾，按最早到期时间排序。

​

会话粘性（缓存友好）

• 会话被重置（/new / /reset）
• 压缩完成（压缩计数递增）
• 配置文件处于冷却中/已禁用状态

​

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

• 通过 auth.order[provider] = ["provider:profileId"] 固定，或
• 通过 /model … 使用按会话覆盖并指定配置文件（当你的 UI/聊天界面支持时）。

​

冷却期

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

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

​

计费禁用

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

• 计费退避从 5 小时开始，每次计费失败加倍，上限为 24 小时。
• 如果配置文件在 24 小时内未失败，退避计数器将重置（可配置）。

​

模型回退

​

相关配置

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