gateway-watchdog

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.json on 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.sh

This 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.json edit, 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)