文档
模型故障转移

模型故障转移

适用范围

在以下情况使用此页面：

  • 诊断身份验证配置文件轮换、冷却或模型回退行为
  • 更新身份验证配置文件或模型的故障转移规则

Moltbot 分两个阶段处理故障：

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

此文档解释了运行时规则和其背后的数据。

身份验证存储（密钥 + OAuth）

Moltbot 对 API 密钥和 OAuth 令牌都使用 身份验证配置文件。

  • 机密位于 ~/.moltbot/agents/<agentId>/agent/auth-profiles.json（传统：~/.moltbot/agent/auth-profiles.json）中。
  • 配置 auth.profiles / auth.order 是 仅元数据 + 路由（无机密）。
  • 传统导入仅限 OAuth 文件：~/.moltbot/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:[email protected]）。

配置文件位于 profiles 下的 ~/.moltbot/agents/<agentId>/agent/auth-profiles.json 中。

轮换顺序

当提供程序有多个配置文件时，Moltbot 按如下顺序选择：

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

如果没有配置显式顺序，Moltbot 使用循环顺序：

  • 主键：配置文件类型（OAuth 优先于 API 密钥）。
  • 次键：usageStats.lastUsed（最旧优先，在每个类型内）。
  • 冷却/禁用的配置文件移动到末尾，按最快过期排序。

会话粘性（缓存友好）

Moltbot 为每个会话固定所选的身份验证配置文件，以保持提供程序缓存预热。 它 不 在每个请求上轮换。固定的配置文件会被重用，直到：

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

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

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

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

如果您为同一提供程序同时拥有 OAuth 配置文件和 API 密钥配置文件，除非固定，否则循环顺序可以在消息之间切换。要强制单个配置文件：

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

冷却

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

冷却使用指数退避：

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

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

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

计费禁用

计费/信用失败（例如"积分不足"/“信用余额太低”）被视为可故障转移，但它们通常不是瞬态的。不是短暂的冷却，Moltbot 将配置文件标记为 禁用（具有更长的退避）并轮换到下一个配置文件/提供程序。

状态存储在 auth-profiles.json 中：

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

默认值：

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

模型回退

如果提供程序的所有配置文件都失败，Moltbot 将移动到 agents.defaults.model.fallbacks 中的下一个模型。这适用于身份验证失败、速率限制以及耗尽配置文件轮转的超时（其他错误不会推进回退）。

当使用模型覆盖（挂钩或 CLI）启动运行时，回退仍然在尝试任何配置的回退后结束于 agents.defaults.model.primary。

相关配置

有关以下内容，请参阅网关配置：

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

请参阅模型了解更广泛的模型选择和回退概述。

脚本模型提供程序