Gateway Watchdog (Discord)

Discord-first watchdog for OpenClaw gateway incidents.

🛠️ Installation

1. Ask OpenClaw (Recommended)

Tell OpenClaw: "Install the gateway-watchdog skill." Loading a LaunchAgent or configuring Discord delivery remains an explicit operator action.

2. Manual Installation (CLI)

If you prefer the terminal, run:

openclaw skills install @jonathanjing/openclaw-gateway-watchdog-skill

Isolation model

• Watchdog data is isolated under ~/.openclaw/watchdogs/gateway-discord/.
• No edits to openclaw.json are required.
• The shipped watchdog is read-only: it does not rewrite openclaw.json, run doctor --fix, promote baselines, or restart services.
• Discord delivery exports a bounded incident summary to a third party; use an allowlisted private channel.
• A foreground run probes four targets: OpenClaw Gateway, Spark status, Local API Hub health, and Dashboard health. The latter three default to loopback endpoints and may be overridden with the declared environment variables.
• The script writes per-target state plus an append-only event log under the watchdog data directory. It creates background persistence only when the operator explicitly runs the cron or LaunchAgent installation commands below.
• config.env is parsed as data using an allowlist; it is never sourced or executed. For Spark only, the script may read the single SPARK_API_TOKEN value from ~/.openclaw/.env when that token is not already configured.

Files in this skill

• scripts/gateway-watchdog.sh - health checks + state machine + Discord notification.
• scripts/install-launchd.sh - installs a user LaunchAgent from template.
• references/com.openclaw.gateway-watchdog.plist.template - launchd template.
• references/cron-agent-turn.md - isolated cron prompt template.

Health checks

Every run performs these checks:

openclaw gateway status --json
openclaw health --json --timeout <ms>
curl "${SPARK_API_URL:-http://127.0.0.1:17070}/status"
curl "${LOCAL_API_URL:-http://localhost:3456}/health"
curl "http://localhost:${DASHBOARD_PORT:-18793}/health"

Pass criteria:

• gateway runtime is running
• RPC probe is healthy (when present)
• health snapshot returns successfully

Failure classes:

• runtime_stopped
• rpc_probe_failed
• health_unreachable
• auth_mismatch
• config_invalid
• target-specific Spark, Local API Hub, or Dashboard connectivity failure

Quick start (manual run)

bash "{baseDir}/scripts/gateway-watchdog.sh"

Optional env:

export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
export DISCORD_BOT_TOKEN="discord_bot_token"
export DISCORD_CHANNEL_ID="<your_discord_channel_id>"
export GW_WATCHDOG_SOURCE="manual"
export GW_WATCHDOG_FAIL_THRESHOLD=2
export GW_WATCHDOG_COOLDOWN_SECONDS=300

Delivery priority:

1. DISCORD_WEBHOOK_URL
2. DISCORD_BOT_TOKEN + DISCORD_CHANNEL_ID

macOS background mode (LaunchAgent)

Install LaunchAgent (does not edit OpenClaw core config):

bash "{baseDir}/scripts/install-launchd.sh" --interval 30 --load

Check status:

launchctl list | rg "com.openclaw.gateway-watchdog"

OpenClaw cron mode (internal path)

Use isolated job and keep messaging in one channel:

openclaw cron add \
  --name "gateway-watchdog-internal" \
  --cron "*/1 * * * *" \
  --session isolated \
  --message "Run bash {baseDir}/scripts/gateway-watchdog.sh and report state changes only." \
  --announce \
  --channel discord \
  --to "channel:<your_channel_id>" \
  --best-effort-deliver

Backup and audit artifacts

• state file: ~/.openclaw/watchdogs/gateway-discord/state.json
• state backups: ~/.openclaw/watchdogs/gateway-discord/backups/state-*.json
• event log: ~/.openclaw/watchdogs/gateway-discord/events.jsonl

The script rotates old backups and keeps recent history for rollback/debugging.