一个 24 小时在线的个人助理，随时可能遇到：模型限流（429）、某把 API key 额度用尽、OAuth token 过期、某 provider 宕机、请求过载。如果一遇错就放弃，助理三天两头"失联"。故障转移让它自动换下一个可用的模型/凭据继续。

// resolveFallbackCandidates（model-fallback.ts:252）：主模型 + agents.defaults.model.fallbacks
for (let i = 0; i < candidates.length; i++) {          // model-fallback.ts:531
  const candidate = candidates[i];
  // 先检查该 provider 的所有鉴权 profile 是否都在冷却（:539-560）
  //   全冷却 → 按策略 skip 或 probe
  // 否则调用内层 run（= runEmbeddedPiAgent）
}

// resolveAuthProfileOrder（run.ts:423 → order.ts:67）算出 profile 尝试顺序
const profileCandidates = ...;                 // run.ts:432-436
while (true) {                                  // run.ts:809 主重试循环
  // 上限 MAX_RUN_LOOP_ITERATIONS（run.ts:741，随 profile 数增长）
  await runEmbeddedAttempt(...);                // run.ts:851 一次完整对话尝试
  // 失败 → advanceAuthProfile（跳到下个可用 profile，跳过冷却中的）
  //        markAuthProfileFailure（记失败 + 设冷却）
  // 成功 → markAuthProfileGood / markAuthProfileUsed
}

像单步调试一样，看一次真实故障转移的"改道过程"（假设 Claude 有 2 个 profile 都限流、退到 GPT-4）：

profile 顺序由 orderProfilesByMode（order.ts:162-196）决定：

const typeScore = type === "oauth" ? 0 : type === "token" ? 1 : type === "api_key" ? 2 : 3;
const lastUsed = store.usageStats?.[profileId]?.lastUsed ?? 0;
// 先按类型分：oauth 优先于 token 优先于 api_key
// 同类型内：lastUsed 最旧的优先（round-robin 轮换，均摊负载）
// 冷却中的：排到最后（按冷却到期时间升序）

失败的 profile 会被设置冷却期（markAuthProfileFailure，run.ts:762），一段时间内不再尝试。过载错误（provider 说"我忙"）还有指数退避：

// OVERLOAD_FAILOVER_BACKOFF_POLICY（run.ts:89-94）
// maybeBackoffBeforeOverloadFailover（run.ts:781）：过载时先等一会儿再切，避免雪崩

不是所有错误都该"换 profile"。错误分类在 pi-embedded-helpers.ts（run.ts:40-57 导入）：

• isAuthAssistantError：鉴权错 → 换 profile。
• isRateLimitAssistantError：限流 → 冷却 + 换 profile。
• isBillingAssistantError：额度/账单 → 换。
• isLikelyContextOverflowError：上下文超长 → 触发压缩重试（Day 08）。

✋ 动手

cd /Users/bitmart/work/codes/github/openclaw
sed -n '500,560p' src/agents/model-fallback.ts          # 外层
sed -n '805,860p' src/agents/pi-embedded-runner/run.ts  # 内层 while
sed -n '160,196p' src/agents/auth-profiles/order.ts     # 排序打分