{"id":"c225a48f-f091-43ed-81e3-1f43eb64de41","slug":"openclaw-model-failover-guard","kind":"skill","name":"openclaw-model-failover-guard","summary":"","owner":"BovmantH","repoUrl":"https://github.com/BovmantH/openclaw-model-failover-guard","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-03-01T04:00:37.000Z","addedAt":"2026-10-21T12:47:55.088Z","logoUrl":"https://avatars.githubusercontent.com/u/48009289?u=861db1059ff1ebab694b61b7f24e0361728e7d16&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":["failover","llm-ops","openclaw","model-failover"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T05:23:09.481Z","sample":false,"url":"https://conduits.dev/tools/openclaw-model-failover-guard","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# OpenClaw Model Failover Guard\n\n[English](#english) | [中文](#中文)\n\n<a id=\"english\"></a>\n\n```mermaid\nflowchart LR\n  A[Primary Model Healthy] -->|Check Interval| B{Primary Failures >= Threshold?}\n  B -->|No| A\n  B -->|Yes| C[Build Candidate Pool]\n  C --> D[Filter: allowlist / excluded / cooldown / compatibility]\n  D --> E[Probe Candidates]\n  E -->|Any Healthy| F[Switch + Restart Gateway]\n  E -->|None Healthy| A\n  F --> G{Fallback Stable >= Recover Threshold?}\n  G -->|No| F\n  G -->|Yes| H[Probe Primary + Failback]\n  H -->|Success| A\n  H -->|Fail| F\n```\n\n---\n\n## English\n\nSkill name: `model-failover-guard`\n\n\nKeywords: openclaw skill, model failover, automatic failback, model routing, reliability, high availability\n\nAutomatic model failover + failback guard for OpenClaw.\n\n> This guard performs model failover and failback. It does **not** adapt request payloads across heterogeneous providers. Use only pre-validated compatible fallback candidates.\n\nWhen 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.\n\n### Overview\n\n- Monitor model health on an interval\n- If primary fails N times consecutively → failover\n- Build a candidate pool (prefer `allowedFallbacks` if set)\n- Filter by excluded providers, cooldown, and compatibility rules\n- Probe candidates before switching (optional)\n- After fallback is stable for N checks → probe primary and try failback\n- If failback test fails → revert to fallback and apply primary cooldown\n\n### Install\n\n```bash\nnpx skills add BovmantH/openclaw-model-failover-guard --skill model-failover-guard\n```\n\n### Files\n\n| Path | Purpose |\n|---|---|\n| `skills/model-failover-guard/SKILL.md` | Skill definition |\n| `skills/model-failover-guard/config.example.json` | Config template |\n| `skills/model-failover-guard/scripts/failover.py` | Runtime guard script |\n\n### Config\n\nCopy `config.example.json` to `config.json`.\n\n| Key | Description |\n|---|---|\n| `primaryModel` | Optional. Empty = use OpenClaw current default model |\n| `preferredFallbackProvider` | Optional preferred fallback provider |\n| `excludedProviders` | Providers excluded from fallback candidates |\n| `allowedFallbacks` | Optional allowlist of fallback models |\n| `compatibility` | Optional compatibility rules (API / reasoning / tools / streaming) |\n| `candidateProbe` | Probe candidates before switching |\n| `failbackProbe` | Probe primary before failback |\n| `candidateCooldown` | Cooldown durations for failed candidates |\n| `primaryCooldownSec` | Cooldown after failed failback |\n| `failoverOnErrors` | Error types that can trigger failover |\n| `ignoreErrors` | Error types that should never trigger failover |\n| `failThreshold` | Consecutive failures before failover |\n| `recoverThreshold` | Stable checks before failback |\n| `checkIntervalSec` | Health check interval (seconds) |\n| `testTimeoutSec` | Single test timeout (seconds) |\n\n### Run\n\n```bash\npython3 skills/model-failover-guard/scripts/failover.py once\npython3 skills/model-failover-guard/scripts/failover.py loop\n```\n\n### State & Logs\n\n- State: `~/.openclaw/failover-state.json`\n- Log: `~/.openclaw/failover.log`\n\n### Run as Systemd Service (Linux)\n\n#### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp skills/model-failover-guard/openclaw-model-failover.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\n```\n\n#### Enable & Start\n\n```bash\nsystemctl --user enable --now openclaw-model-failover\n```\n\n#### Logs\n\n```bash\njournalctl --user -u openclaw-model-failover -f\n```\n\n### FAQ\n\n**Q: Failback to primary is not happening. What should I do?**  \nA: Check `~/.openclaw/failover.log`. You can also run `python3 skills/model-failover-guard/scripts/failover.py once` manually.\n\n**Q: Log file is too large.**  \nA: Rotate/clean periodically. Example: `echo \"\" > ~/.openclaw/failover.log`\n\n**Q: How to stop the guard completely?**  \nA: `systemctl --user stop openclaw-model-failover` (if using systemd), or kill the process.\n\n**Q: Can I run multiple instances?**  \nA: Not recommended. Run only one instance per machine.\n\n---\n\n<a id=\"中文\"></a>\n\n## 中文\n\n```mermaid\nflowchart LR\n  A[主模型健康] -->|按间隔检查| B{连续失败达到阈值?}\n  B -->|否| A\n  B -->|是| C[构建候选池]\n  C --> D[过滤：白名单/排除/冷却/兼容性]\n  D --> E[探测候选]\n  E -->|有健康候选| F[切换并重启 Gateway]\n  E -->|无健康候选| A\n  F --> G{兜底稳定达到切回阈值?}\n  G -->|否| F\n  G -->|是| H[探测主模型并切回]\n  H -->|成功| A\n  H -->|失败| F\n```\n\n这是一个 OpenClaw 模型自动故障切换 + 自动切回守护技能。\n\n> 该守护器只负责 failover / failback，不会自动适配不同 provider 的请求协议。请只使用已验证兼容的兜底候选。\n\n当主模型不稳定时，守护进程会自动切换到可用的兜底模型，并在稳定后自动尝试切回主模型。\n\n### 概览\n\n- 按固定间隔检测模型健康\n- 主模型连续失败 N 次后触发故障切换\n- 构建候选池（优先使用 `allowedFallbacks`）\n- 过滤：排除 provider / 冷却 / 兼容性规则\n- 切换前可探测候选\n- 兜底稳定 N 次后探测主模型并尝试切回\n- 切回失败会回退兜底并进入主模型冷却\n\n### 安装\n\n```bash\nnpx skills add BovmantH/openclaw-model-failover-guard --skill model-failover-guard\n```\n\n### 文件\n\n| 路径 | 用途 |\n|---|---|\n| `skills/model-failover-guard/SKILL.md` | 技能定义 |\n| `skills/model-failover-guard/config.example.json` | 配置模板 |\n| `skills/model-failover-guard/scripts/failover.py` | 运行脚本 |\n\n### 配置\n\n复制 `config.example.json` 为 `config.json`。\n\n| 键 | 说明 |\n|---|---|\n| `primaryModel` | 可选；空则使用 OpenClaw 当前默认主模型 |\n| `preferredFallbackProvider` | 可选的优先兜底 provider |\n| `excludedProviders` | 不参与兜底的 provider 列表 |\n| `allowedFallbacks` | 可选；兜底模型白名单 |\n| `compatibility` | 可选；兼容性规则（API/推理/工具/流式） |\n| `candidateProbe` | 切换前候选探测 |\n| `failbackProbe` | 切回前主模型探测 |\n| `candidateCooldown` | 候选失败后的冷却时间 |\n| `primaryCooldownSec` | 切回失败后的主模型冷却 |\n| `failoverOnErrors` | 允许触发 failover 的错误类型 |\n| `ignoreErrors` | 明确不触发 failover 的错误类型 |\n| `failThreshold` | 触发故障切换的连续失败阈值 |\n| `recoverThreshold` | 触发切回主模型的稳定检查阈值 |\n| `checkIntervalSec` | 健康检查间隔（秒） |\n| `testTimeoutSec` | 单次测试超时（秒） |\n\n### 运行\n\n```bash\npython3 skills/model-failover-guard/scripts/failover.py once\npython3 skills/model-failover-guard/scripts/failover.py loop\n```\n\n### 状态与日志\n\n- 状态：`~/.openclaw/failover-state.json`\n- 日志：`~/.openclaw/failover.log`\n\n### 作为 Systemd 服务运行（Linux）\n\n#### 安装服务\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp skills/model-failover-guard/openclaw-model-failover.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\n```\n\n#### 启用并启动\n\n```bash\nsystemctl --user enable --now openclaw-model-failover\n```\n\n#### 查看日志\n\n```bash\njournalctl --user -u openclaw-model-failover -f\n```\n\n### 常见问题\n\n**问：切不回主模型怎么办？**  \n答：检查 `~/.openclaw/failover.log`，也可以手动运行 `python3 skills/model-failover-guard/scripts/failover.py once`。\n\n**问：日志文件太大怎么办？**  \n答：定期清理或用 logrotate。例如：`echo \"\" > ~/.openclaw/failover.log`\n\n**问：如何完全停止守护？**  \n答：如果用了 systemd，执行 `systemctl --user stop openclaw-model-failover`，或直接 kill 进程。\n\n**问：可以同时跑多个实例吗？**  \n答：不建议，同一台机器只跑一个实例。\n\n---\n\n## License\n\nMIT License · Copyright © 2026 BovmantH\n\nSee [LICENSE](./LICENSE) for full text.\n"}