Gateway Watchdog Lite

Installs a macOS or Linux service that probes the OpenClaw gateway every 2 minutes and auto-recovers it on failure, sending Telegram alerts.

<!-- Supplied by ConfusedUser.com — OpenClaw tools & skills | Full version: https://confuseduser.com -->

Overview

The gateway-watchdog-lite skill installs a macOS LaunchAgent or Linux systemd user service that monitors the OpenClaw gateway every 2 minutes. If the gateway is unresponsive, it automatically runs the recovery sequence and alerts via Telegram.

Supported platforms:

• macOS (LaunchAgent) — scripts/install.sh
• Linux (systemd user service) — scripts/install-linux.sh

What It Does

Feature	Detail
Probe interval	Every 120 seconds
Health check	HTTP probe to 127.0.0.1:<OC_PORT> — accepts 200, 301, 302
Auto-recovery	launchctl bootout + launchctl bootstrap (macOS) / systemctl restart (Linux)
Cooldown	5 minutes between recovery attempts (anti-thrash)
Alerts	Telegram via gog telegram send — success and failure
Logs	/tmp/openclaw/gateway-watchdog.log

Want crash loop detection + auto-mitigation? Upgrade to the full Gateway Watchdog skill (paid, from confuseduser.com).

Install

macOS

WORKSPACE_PATH=/your/workspace OC_PORT=18789 TELEGRAM_ID=your_id bash scripts/install.sh

To disable Telegram alerts:

WORKSPACE_PATH=/your/workspace OC_PORT=18789 TELEGRAM_ID="" bash scripts/install.sh

Variable	Required	Description	How to find it
WORKSPACE_PATH	✅	Path to your OpenClaw workspace root	Run openclaw status
OC_PORT	✅	Gateway port to probe (default: 18789)	Run openclaw status
TELEGRAM_ID	⬜ Optional	Your Telegram user ID	Message @userinfobot on Telegram

Linux

WORKSPACE_PATH=/your/workspace OC_PORT=18789 TELEGRAM_ID=your_id bash scripts/install-linux.sh

Verify (macOS)

launchctl list | grep watchdog

Verify (Linux)

systemctl --user status gateway-watchdog

Logs

tail -f /tmp/openclaw/gateway-watchdog.log

Manual Trigger

Test the watchdog immediately:

bash scripts/gateway-watchdog.sh

Reset cooldown first if testing recovery:

rm -f /tmp/openclaw/watchdog-last-recovery
bash scripts/gateway-watchdog.sh

Uninstall

macOS

launchctl bootout gui/$UID/ai.openclaw.gateway-watchdog
rm ~/Library/LaunchAgents/ai.openclaw.gateway-watchdog.plist

Linux

systemctl --user stop gateway-watchdog
systemctl --user disable gateway-watchdog
rm ~/.config/systemd/user/gateway-watchdog.service
systemctl --user daemon-reload

Recovery Gotchas

See references/gotchas.md for OC-specific recovery notes including:

• GGML Metal crash on restart — add GGML_NO_METAL=1 to env vars
• openclaw gateway install --force — use after config changes
• Bootout + bootstrap sequence — the correct recovery pattern
• Cooldown logic — 5 min between attempts, reset with rm /tmp/openclaw/watchdog-last-recovery
• Telegram alert failures — won't block recovery (uses || true)