WatchClaw

Auto-recovery watchdog for OpenClaw gateway. Monitors health, detects bad config changes, and recovers via git stash/revert. Supports native and Docker resta...

OpenClaw gateway watchdog — auto-recovery from bad config changes.

What It Does

watchclaw monitors your OpenClaw gateway and automatically recovers from bad configurations:

• Health polling — checks gateway HTTP endpoint every N seconds
• Config change detection — detects uncommitted or new commits in your config repo
• Auto-recovery — stashes uncommitted changes (U1) or reverts bad commits (U2) via git
• Probation — validates stability after config changes before promoting to known-good
• Pluggable alerts — iMessage, webhook, or custom command on failure/recovery

Usage

# Start watching (background daemon)
watchclaw --config /path/to/watchclaw.conf start

# Start in foreground (for debugging)
watchclaw --config /path/to/watchclaw.conf start --foreground

# Check status
watchclaw --config /path/to/watchclaw.conf status

# Follow logs
watchclaw --config /path/to/watchclaw.conf logs -f

# Stop
watchclaw --config /path/to/watchclaw.conf stop

Config

Create a .conf file (see watchclaw.conf.example):

GATEWAY_PORT=18790
GATEWAY_CONFIG_DIR="$HOME/.openclaw"
POLL_INTERVAL_SEC=10
HEALTH_TIMEOUT_SEC=5
GATEWAY_TLS=0              # Use https for health check
MAX_RETRIES=3
ALERT_HOOK="imsg"           # imsg | webhook | command | none
ALERT_IMSG_TO="[e-mail]"
RESTART_MODE="native"       # native | docker

Recovery Modes

Scenario	Detection	Recovery
Uncommitted config change breaks gateway	Health check fails + dirty openclaw.json	git stash → restart
Bad commit breaks gateway	Health check fails + new commit	git revert → restart
Config change during healthy operation	HEAD ≠ known-good in HEALTHY state	Enter probation, monitor

Docker Mode

For containerized OpenClaw (e.g., 飞书/Feishu bot):

RESTART_MODE="docker"
DOCKER_CONTAINER="openclaw-feishu"

Requirements

• bash 4+, git, curl
• OpenClaw gateway config must be in a git repo
• python3 or node for JSON validation