Model Failover Doctor

Diagnose and fix OpenClaw "All models failed" errors by detecting invalid model IDs, provider mismatches, and session fallback issues with optional auto-repair.

Security Scan

The skill's code and instructions are consistent with its stated purpose: it only inspects and (optionally) edits OpenClaw failover-related files under your home directory and can restart the gateway; it does not request external credentials or attempt network exfiltration.

Purpose & Capability

The name/description match what the code and SKILL.md do: detect and repair failover issues by reading/writing OpenClaw config files (message-injector, pools.json, session_model_state.json) and creating backups. No unrelated credentials or binaries are requested.

Instruction Scope

SKILL.md and the script instruct reading and modifying files under ~/.openclaw (openclaw.json, .lib/pools.json, .lib/session_model_state.json and a message-injector index.ts). It also supports --dry-run, --fix, and --restart. These actions are in-scope for a failover repair tool, but note the script will read potentially sensitive configuration files and will write changes to these files when --fix is used (it creates timestamped backups first).

Install Mechanism

No install spec; the skill is instruction+script only. Nothing is downloaded from external URLs and no new binaries are installed.

Credentials

The skill requests no environment variables or external credentials. It operates on config files within ~/.openclaw, which is appropriate for a tool that repairs gateway/session configuration. Access to those files is necessary for its stated purpose.

Persistence & Privilege

The skill is not always-on and does not request elevated platform privileges. It modifies OpenClaw config/extension files (message-injector, pools/session state) and writes backups in its workspace area; this is expected for a repair tool. Autonomous invocation is allowed by default, but that is the platform norm and not a unique concern here.

Assessment

This tool appears to do what it says: diagnose and optionally auto-fix failover config problems by reading/writing OpenClaw config files and restarting the gateway. Before running with --fix (or --restart): 1) run the script with --dry-run first to preview changes; 2) inspect the generated backups under ~/.openclaw/workspace/.lib/.mfd_backups/ so you can restore if needed; 3) manually review the proposed edits to message-injector/index.ts and pools/session files to ensure they match your intended routing/overrides; 4) run fixes during a maintenance window since the gateway restart will affect availability. If you have concerns, you can open the script (model_failover_doctor.py) and the referenced files to verify behavior—there are no network calls or credential exfiltration signs in the provided code.

诊断和修复 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

诊断命令

# 仅诊断，不修改任何文件
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 无条件返回：

return { modelOverride, providerOverride, ... }

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

修复：包装在 lockModel 条件中，正常路由只依赖 sessions.patch：

return { ...(lockModel ? { modelOverride, providerOverride } : {}), ... }

备份说明

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