Gateway Watchdog Lite

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

> 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

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)