Gateway Watchdog Discord

Monitor OpenClaw gateway health with a watchdog state machine, Discord alerts, cooldown dedupe, and isolated fallback deployment on macOS. Use when users wan...

Security Scan

The skill's files, runtime instructions, and requested capabilities are coherent with a gateway watchdog that notifies Discord and optionally performs bounded auto-recovery; nothing required or installed appears disproportionate to that purpose.

Purpose & Capability

Name/description (OpenClaw gateway watchdog + Discord alerts) align with required binaries (bash, python3, openclaw), the declared config requirement (channels.discord.enabled), and the included scripts which perform health checks, notify Discord, and optionally restart the gateway.

Instruction Scope

SKILL.md instructs running the included scripts, using OpenClaw cron or a macOS LaunchAgent, and storing runtime data under ~/.openclaw/watchdogs/gateway-discord. The instructions do not ask to read unrelated system files or exfiltrate data to unexpected endpoints; referenced files (openclaw.json and baseline) are relevant to auto-recovery.

Install Mechanism

No remote install/fetch steps are present (instruction-only plus bundled scripts). The provided macOS installer script writes a user LaunchAgent plist into ~/Library/LaunchAgents — expected for the fallback behavior.

Credentials

The skill expects Discord delivery credentials (webhook or bot token + channel ID) via env or a local config.env located in the skill's base dir; these are proportional to sending alerts. The skill can read and restore openclaw.json from a baseline and runs openclaw doctor/restart commands — privileged but consistent with an opt-in auto-recovery feature. Users should note config.env may contain secrets and is sourced by the script.

Persistence & Privilege

The skill does not request always:true and is not forced into every agent run. It offers a user-level LaunchAgent installer that creates/loads a plist in the user's LaunchAgents directory — this is expected for a persistent fallback worker but is a meaningful change to user launchd state and requires user confirmation before loading.

Assessment

This skill appears to do what it claims, but review and control the following before installing: 1) Inspect ~/.openclaw/watchdogs/gateway-discord/config.env before sourcing it (it may contain Discord tokens); 2) Prefer webhook mode (DISCORD_WEBHOOK_URL) if you want single-channel alerts and simpler permissions; 3) Test manually (GW_WATCHDOG_ENABLE_RESTART=0) before enabling auto-restart to avoid unexpected restarts; 4) If using the macOS installer, review the generated plist and only bootstrap it if you trust the behavior (it will create a LaunchAgent in your user domain); 5) Confirm the OpenClaw CLI path used by the script matches your expected install to avoid unintended commands. If you want extra assurance, run the script in a controlled/test environment and inspect event logs under ~/.openclaw/watchdogs/gateway-discord/.

Discord-first watchdog for OpenClaw gateway incidents.

🛠️ Installation

1. Ask OpenClaw (Recommended)

Tell OpenClaw: "Install the gateway-watchdog skill." The agent will handle the installation and configuration automatically.

2. Manual Installation (CLI)

If you prefer the terminal, run:

clawhub install gateway-watchdog

Isolation model

• Watchdog data is isolated under ~/.openclaw/watchdogs/gateway-discord/.
• No edits to openclaw.json are required.
• Default mode is read-only monitoring (GW_WATCHDOG_ENABLE_RESTART=0).
• Automatic restart is opt-in and bounded by max attempts.

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

The watchdog checks:

openclaw gateway status --json
openclaw health --json --timeout <ms>

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

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

Auto-recovery policy (opt-in)

Enable bounded restart:

export GW_WATCHDOG_ENABLE_RESTART=1
export GW_WATCHDOG_MAX_RESTART_ATTEMPTS=2

Safety constraints:

• restart only after failure threshold is met
• max attempts enforced per incident window
• no reinstall or destructive mutation

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.