openclaw-model-failover-guard

OpenClaw Model Failover Guard

English | 中文

flowchart LR
  A[Primary Model Healthy] -->|Check Interval| B{Primary Failures >= Threshold?}
  B -->|No| A
  B -->|Yes| C[Build Candidate Pool]
  C --> D[Filter: allowlist / excluded / cooldown / compatibility]
  D --> E[Probe Candidates]
  E -->|Any Healthy| F[Switch + Restart Gateway]
  E -->|None Healthy| A
  F --> G{Fallback Stable >= Recover Threshold?}
  G -->|No| F
  G -->|Yes| H[Probe Primary + Failback]
  H -->|Success| A
  H -->|Fail| F

---

English

Skill name: model-failover-guard

Keywords: openclaw skill, model failover, automatic failback, model routing, reliability, high availability

Automatic model failover + failback guard for OpenClaw.

This guard performs model failover and failback. It does not adapt request payloads across heterogeneous providers. Use only pre-validated compatible fallback candidates.

When your primary model becomes unstable, this guard can switch to an available fallback model automatically, then switch back to the primary after stability is restored.

Overview

• Monitor model health on an interval
• If primary fails N times consecutively → failover
• Build a candidate pool (prefer allowedFallbacks if set)
• Filter by excluded providers, cooldown, and compatibility rules
• Probe candidates before switching (optional)
• After fallback is stable for N checks → probe primary and try failback
• If failback test fails → revert to fallback and apply primary cooldown

Install

npx skills add BovmantH/openclaw-model-failover-guard --skill model-failover-guard

Files

Path	Purpose
skills/model-failover-guard/SKILL.md	Skill definition
skills/model-failover-guard/config.example.json	Config template
skills/model-failover-guard/scripts/failover.py	Runtime guard script

Config

Copy config.example.json to config.json.

Key	Description
primaryModel	Optional. Empty = use OpenClaw current default model
preferredFallbackProvider	Optional preferred fallback provider
excludedProviders	Providers excluded from fallback candidates
allowedFallbacks	Optional allowlist of fallback models
compatibility	Optional compatibility rules (API / reasoning / tools / streaming)
candidateProbe	Probe candidates before switching
failbackProbe	Probe primary before failback
candidateCooldown	Cooldown durations for failed candidates
primaryCooldownSec	Cooldown after failed failback
failoverOnErrors	Error types that can trigger failover
ignoreErrors	Error types that should never trigger failover
failThreshold	Consecutive failures before failover
recoverThreshold	Stable checks before failback
checkIntervalSec	Health check interval (seconds)
testTimeoutSec	Single test timeout (seconds)

Run

python3 skills/model-failover-guard/scripts/failover.py once
python3 skills/model-failover-guard/scripts/failover.py loop

State & Logs

• State: ~/.openclaw/failover-state.json
• Log: ~/.openclaw/failover.log

Run as Systemd Service (Linux)

Install service

mkdir -p ~/.config/systemd/user
cp skills/model-failover-guard/openclaw-model-failover.service ~/.config/systemd/user/
systemctl --user daemon-reload

Enable & Start

systemctl --user enable --now openclaw-model-failover

Logs

journalctl --user -u openclaw-model-failover -f

FAQ

Q: Failback to primary is not happening. What should I do?
A: Check ~/.openclaw/failover.log. You can also run python3 skills/model-failover-guard/scripts/failover.py once manually.

Q: Log file is too large.
A: Rotate/clean periodically. Example: echo "" > ~/.openclaw/failover.log

Q: How to stop the guard completely?
A: systemctl --user stop openclaw-model-failover (if using systemd), or kill the process.

Q: Can I run multiple instances?
A: Not recommended. Run only one instance per machine.

---

中文

flowchart LR
  A[主模型健康] -->|按间隔检查| B{连续失败达到阈值?}
  B -->|否| A
  B -->|是| C[构建候选池]
  C --> D[过滤：白名单/排除/冷却/兼容性]
  D --> E[探测候选]
  E -->|有健康候选| F[切换并重启 Gateway]
  E -->|无健康候选| A
  F --> G{兜底稳定达到切回阈值?}
  G -->|否| F
  G -->|是| H[探测主模型并切回]
  H -->|成功| A
  H -->|失败| F

这是一个 OpenClaw 模型自动故障切换 + 自动切回守护技能。

该守护器只负责 failover / failback，不会自动适配不同 provider 的请求协议。请只使用已验证兼容的兜底候选。

当主模型不稳定时，守护进程会自动切换到可用的兜底模型，并在稳定后自动尝试切回主模型。

概览

• 按固定间隔检测模型健康
• 主模型连续失败 N 次后触发故障切换
• 构建候选池（优先使用 allowedFallbacks）
• 过滤：排除 provider / 冷却 / 兼容性规则
• 切换前可探测候选
• 兜底稳定 N 次后探测主模型并尝试切回
• 切回失败会回退兜底并进入主模型冷却

安装

npx skills add BovmantH/openclaw-model-failover-guard --skill model-failover-guard

文件

路径	用途
skills/model-failover-guard/SKILL.md	技能定义
skills/model-failover-guard/config.example.json	配置模板
skills/model-failover-guard/scripts/failover.py	运行脚本

配置

复制 config.example.json 为 config.json。

键	说明
primaryModel	可选；空则使用 OpenClaw 当前默认主模型
preferredFallbackProvider	可选的优先兜底 provider
excludedProviders	不参与兜底的 provider 列表
allowedFallbacks	可选；兜底模型白名单
compatibility	可选；兼容性规则（API/推理/工具/流式）
candidateProbe	切换前候选探测
failbackProbe	切回前主模型探测
candidateCooldown	候选失败后的冷却时间
primaryCooldownSec	切回失败后的主模型冷却
failoverOnErrors	允许触发 failover 的错误类型
ignoreErrors	明确不触发 failover 的错误类型
failThreshold	触发故障切换的连续失败阈值
recoverThreshold	触发切回主模型的稳定检查阈值
checkIntervalSec	健康检查间隔（秒）
testTimeoutSec	单次测试超时（秒）

运行

python3 skills/model-failover-guard/scripts/failover.py once
python3 skills/model-failover-guard/scripts/failover.py loop

状态与日志

• 状态：~/.openclaw/failover-state.json
• 日志：~/.openclaw/failover.log

作为 Systemd 服务运行（Linux）

安装服务

mkdir -p ~/.config/systemd/user
cp skills/model-failover-guard/openclaw-model-failover.service ~/.config/systemd/user/
systemctl --user daemon-reload

启用并启动

systemctl --user enable --now openclaw-model-failover

查看日志

journalctl --user -u openclaw-model-failover -f

常见问题

问：切不回主模型怎么办？
答：检查 ~/.openclaw/failover.log，也可以手动运行 python3 skills/model-failover-guard/scripts/failover.py once。

问：日志文件太大怎么办？
答：定期清理或用 logrotate。例如：echo "" > ~/.openclaw/failover.log

问：如何完全停止守护？
答：如果用了 systemd，执行 systemctl --user stop openclaw-model-failover，或直接 kill 进程。

问：可以同时跑多个实例吗？
答：不建议，同一台机器只跑一个实例。

---

License

MIT License · Copyright © 2026 BovmantH

See LICENSE for full text.