Model Failover Doctor

# model-failover-doctor

诊断和修复 OpenClaw "All models failed" 错误的专用工具。

## 触发条件

遇到以下任何一种情况时，调用此工具：

1. **日志或用户报告** `All models failed (N)`，且 N 个 provider 的错误信息中 model ID 全部相同
   - 例：`kimi-coding/k2p5: No available channel for model openai/gpt-5.3-codex` ← provider 和 model 对不上
2. **agent 重启后第一条消息必然失败**，但后续消息正常（冷启动 session 无 fallbackChain）
3. **pools.json 或 session_model_state.json 手动编辑后** agent 开始报 503 model_not_found

## 诊断命令

```bash
# 仅诊断，不修改任何文件
python3 ~/.openclaw/workspace/skills/model-failover-doctor/model_failover_doctor.py

# 诊断 + 自动修复 + 重启 gateway
python3 ~/.openclaw/workspace/skills/model-failover-doctor/model_failover_doctor.py --fix --restart

# 预览将要修改的内容（不实际写入）
python3 ~/.openclaw/workspace/skills/model-failover-doctor/model_failover_doctor.py --dry-run
```

## 根因速查表

| 症状 | 代码 | 严重 | 自动修复 |
|------|------|------|----------|
| 所有 fallback 的 model ID 相同（provider 已切换但 model 没变） | MI-1 | 🔴 | ✅ |
| 同一死亡模型被不同 session/子代理反复踩坑 | MI-2 | 🟡 | ❌ 需手动 |
| pools.json 中引用了不存在的 provider | P-1 | 🔴 | ✅ |
| session 无 fallbackChain，runtime fallback 永远无法推进 | S-1 | 🔴 | ✅ |
| session fallbackChain 含无效 provider 前缀 | S-2 | 🔴 | ✅ |

## 根因 MI-1 详解（最常见）

**问题**：`message-injector` 的 `before_agent_start` 无条件返回：
```typescript
return { modelOverride, providerOverride, ... }
```

**后果**：Gateway 尝试每个 fallback 时都携带相同的 `modelOverride`，
导致 `kimi-coding`、`zai`、`minimax` 等收到了错误的 model ID。

**修复**：包装在 `lockModel` 条件中，正常路由只依赖 `sessions.patch`：
```typescript
return { ...(lockModel ? { modelOverride, providerOverride } : {}), ... }
```

## 备份说明

所有自动修复操作会在 `~/.openclaw/workspace/.lib/.mfd_backups/` 创建时间戳备份，
可随时手动恢复。

# 🩺 Model Failover Doctor

> *当 AI 说"所有模型都失败了"——它其实是在请求一位医生。*

---

## 你是否遇到过这种情况？

某天，你的 OpenClaw 突然开始报错：

```
All models failed (6): kimi-coding/k2p5: No available channel for model openai/gpt-5.3-codex
```

你看了三遍，感觉哪里不对——`kimi-coding` 明明是个编程模型的 provider，为什么它会去找 `openai/gpt-5.3-codex`？这两个压根就不是一回事。

于是你重启 gateway，重启又重启，甚至清空了 session 状态。有时好了，有时没好，你完全不知道根因在哪里。

**Model Failover Doctor 就是为这种时刻而生的。**

---

## 它能做什么？

这是一个为 OpenClaw 设计的 **模型 Failover 诊断 & 修复工具**。它能在几秒钟内帮你找到 "All models failed" 错误背后真正的根因，并在大多数情况下自动修复它们。

### 五种根因，一网打尽

| 代码 | 病因 | 严重程度 | 能否自动修复 |
|------|------|:--------:|:------------:|
| **MI-1** | `before_agent_start` 无条件返回 `modelOverride`，毒化所有 fallback | 🔴 致命 | ✅ 自动 |
| **MI-2** | 缺少全局死亡模型注册表，不同 session 反复踩同一个坑 | 🟡 警告 | 🖐 手动 |
| **P-1** | `pools.json` 引用了不存在的 provider 前缀 | 🔴 致命 | ✅ 自动 |
| **S-1** | session 没有 `fallbackChain`，runtime fallback 永远无法推进 | 🔴 致命 | ✅ 自动 |
| **S-2** | `fallbackChain` 里含有无效 provider，gateway 路由必然 503 | 🔴 致命 | ✅ 自动 |

---

## 快速上手

### 三条命令，从入门到修复

```bash
# 1. 只看诊断报告，不动任何文件
python3 ~/.openclaw/workspace/skills/model-failover-doctor/model_failover_doctor.py

# 2. 发现问题？预览将要做的修改（安全，不写入）
python3 ~/.openclaw/workspace/skills/model-failover-doctor/model_failover_doctor.py --dry-run

# 3. 确认没问题？一键修复 + 重启 gateway
python3 ~/.openclaw/workspace/skills/model-failover-doctor/model_failover_doctor.py --fix --restart
```

### 健康的输出长什么样？

```
🩺 OpenClaw Model Failover Doctor — 2026-03-05 23:30
────────────────────────────────────────────────
✅ 未发现问题，模型 Failover 配置正常。
   覆盖: MI-1 / MI-2 / P-1 / S-1 / S-2
```

### 有问题时的输出

```
🩺 OpenClaw Model F...