Gateway Watchdog

Automated self-healing system for OpenClaw gateway failures including config corruption, process crashes, and auth failures.

How It Works

Three-layer protection:

1. Config Guard — Auto-backup openclaw.json on every successful health check
2. Process Watchdog — Detect gateway process death → auto-restart
3. 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)