- name
- gateway-watchdog
- description
- Self-healing watchdog for OpenClaw gateway. Auto-backup openclaw.json before changes, health-check the gateway process, and auto-rollback to last known good config on failure. Use when setting up gateway resilience, self-recovery, auto-restart, config backup, or when the user mentions watchdog, self-heal, gateway down, or config recovery.
Gateway Watchdog
Automated self-healing system for OpenClaw gateway failures including config corruption, process crashes, and auth failures.
How It Works
Three-layer protection:
- Config Guard — Auto-backup
openclaw.jsonon every successful health check - Process Watchdog — Detect gateway process death → auto-restart
- Auth Health Check — Detect running-but-broken state → rollback config → restart
Setup
Run the setup script to install the watchdog:
bash scripts/setup-watchdog.shThis will:
- Create the watchdog script at
~/.openclaw/watchdog.sh - Register it as a cron job (every minute)
- Take an initial config backup
Manual Commands
# Check watchdog status
bash scripts/watchdog-status.sh
# Force backup current config
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# View watchdog logs
cat ~/.openclaw/watchdog.log | tail -20
# Disable watchdog
crontab -l | grep -v watchdog | crontab -Recovery Levels
| Level | Condition | Action | Auto? |
|---|---|---|---|
| 1 | Process dead, config OK | Restart gateway | ✅ |
| 2 | Process alive, health check fail | Rollback config + restart | ✅ |
| 3 | No valid backup exists | Log alert, notify if possible | ⚠️ Manual |
Config Backup Strategy
- Auto-backup: On every successful health check, current config overwrites
.bak - Pre-change backup: Before any
openclaw.jsonedit, copy to.bak.prev - Broken config preserved: Failed configs saved as
.broken.<timestamp>for debugging
Logs
All watchdog activity logged to ~/.openclaw/watchdog.log with timestamps.
Platform Support
- macOS: cron-based (launchd alternative in
references/launchd.md) - Linux: cron or systemd (see
references/systemd.md) - Docker: Use HEALTHCHECK directive (see
references/docker.md)