Gateway Sentinel

Production-hardened OpenClaw gateway watchdog. Monitors the gateway process using graduated health checks, performs escalating repairs (restart → doctor fix...

Security Scan

The skill's code and instructions are consistent with a gateway watchdog: it needs openclaw/git/curl, runs as a system service, performs restarts/doctor fixes/optional safe git rollbacks, and sends alerts — but it will modify a local git workspace (daily commits and optional resets) and stores alert tokens in local service files, so you should review and lock down your repo and secrets before installing.

Purpose & Capability

Name/description match what the files do. Required binaries (openclaw, git, curl) and the presence of install/run scripts are appropriate for a gateway watchdog that can restart the gateway, run doctor fixes, perform git rollbacks, and call HTTP endpoints for alerts.

Instruction Scope

SKILL.md and guardian.sh stay within watchdog scope, but the guardian will run 'git add -A && git commit' daily and (if enabled) stash/reset/pop to roll back the workspace. Those operations legitimately belong to the stated rollback/snapshot features but will modify the user's git repo and may capture secrets if not excluded by .gitignore.

Install Mechanism

No external download/install step; all code is provided in the skill. install-guardian.sh writes launchd plist (macOS) or systemd user unit (Linux) and enables a user-level service — standard for a background watchdog.

Credentials

Requires optional sensitive env vars (Telegram bot token / chat id or Discord webhook) for alerting — this is expected. However, install_macos injects those values directly into a plist and install_linux references an EnvironmentFile; tokens will be stored in local service files and guardian.env in cleartext, so protect file permissions. The GUARDIAN_WORKSPACE and git access are justified but provide the guardian broad ability to commit, stash, reset, and pop in that repo.

Persistence & Privilege

The skill installs as a normal user-level service (launchd or systemd user) and is not marked always:true. It does not modify other skills or system-wide configs beyond creating/removing its own service unit/plist and lock/log files.

Assessment

This skill is coherent with its stated purpose, but it performs potentially impactful operations on your local repository and stores alert tokens in local service files. Before installing: 1) point GUARDIAN_WORKSPACE at a dedicated repository (not your entire home or a repo containing secrets), ensure .gitignore excludes any secrets you don't want committed, and consider using a dedicated repo for snapshots; 2) keep GUARDIAN_ENABLE_ROLLBACK=false unless you understand and trust the rollback behavior; 3) secure ~/.openclaw/guardian.env and the generated plist/unit (restrict permissions to your user) because Telegram/Discord credentials are stored in plain text there; 4) inspect the included scripts (guardian.sh, install/uninstall) yourself (they are bundled) and test in a non-production environment first; and 5) if you need alerts but want least exposure, prefer a Discord webhook with minimal scope or an intermediate alert relay rather than pasting long-lived bot tokens into service files.

🛡️ OpenClaw Guardian

A battle-hardened watchdog that keeps your OpenClaw gateway running — and tells you when it can't.

What It Does

OpenClaw Guardian runs as a background service and continuously monitors the OpenClaw gateway using two independent health signals. When the gateway goes down, it works through an escalating repair sequence before entering a cooldown and waiting for manual help. Every significant event is logged and sent to your configured alert channel(s).

Health Check Strategy (graduated)

1. CLI check — openclaw gateway status (the authoritative signal)
2. HTTP fallback — curl http://localhost:${OPENCLAW_PORT}/health (5s timeout)
3. Both must fail before the guardian considers the gateway truly down

Repair Strategy (escalating)

Level	Action	Trigger
1 — Restart	openclaw gateway restart	First failure
2 — Doctor Fix	openclaw doctor --fix → openclaw gateway start	After Level 1 fails
3 — Git Rollback	Stash → reset to last stable commit → pop stash	After GUARDIAN_MAX_REPAIR failures, only if GUARDIAN_ENABLE_ROLLBACK=true
Cooldown	Sleep GUARDIAN_COOLDOWN seconds	After all levels exhausted

Note: Level 3 rollback is off by default and requires explicit opt-in via GUARDIAN_ENABLE_ROLLBACK=true. Even then, it always stashes uncommitted work before resetting — your changes are never silently discarded.

Alerting

Guardian supports both Telegram and Discord simultaneously. If neither is configured, it runs in log-only mode.

Alert events:

• Guardian started / stopped
• Gateway down detected
• Each repair attempt (with level)
• Repair success / failure
• Rollback triggered
• All repairs exhausted (cooldown entered)

Daily Snapshots

Once per calendar day, guardian runs git add -A && git commit in your workspace. It respects .gitignore, so secrets you've excluded stay excluded. Commit message format: guardian: daily snapshot YYYY-MM-DD.

---

Quick Start

1. Configure environment variables

Create ~/.openclaw/guardian.env (or export in your shell profile):

# Required for alerts — set at least one
export GUARDIAN_TELEGRAM_BOT_TOKEN="bot123456:ABC..."
export GUARDIAN_TELEGRAM_CHAT_ID="-1001234567890"
# OR
export GUARDIAN_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

# Optional tuning
export GUARDIAN_CHECK_INTERVAL=30
export GUARDIAN_MAX_REPAIR=3
export GUARDIAN_COOLDOWN=600
export GUARDIAN_ENABLE_ROLLBACK=false  # set true to enable git rollback
export GUARDIAN_WORKSPACE="$HOME/.openclaw/workspace"
export GUARDIAN_LOG="/tmp/openclaw-guardian.log"
export OPENCLAW_PORT=3578

2. Install as a system service

# macOS or Linux — auto-detects
./scripts/install-guardian.sh

# With a custom log path
GUARDIAN_LOG=/var/log/openclaw-guardian.log ./scripts/install-guardian.sh

3. Verify it's running

# macOS
launchctl list | grep openclaw

# Linux
systemctl --user status openclaw-guardian

# Both
tail -f /tmp/openclaw-guardian.log

4. Run manually (testing / foreground)

# Source your config first
source ~/.openclaw/guardian.env

# Run guardian in the foreground (Ctrl-C to stop)
./scripts/guardian.sh

5. Uninstall

./scripts/uninstall-guardian.sh

---

Environment Variable Reference

Variable	Default	Description
GUARDIAN_CHECK_INTERVAL	30	Seconds between health checks
GUARDIAN_MAX_REPAIR	3	Max Level 1+2 attempts before Level 3
GUARDIAN_COOLDOWN	600	Cooldown sleep (seconds) after all repairs fail
GUARDIAN_ENABLE_ROLLBACK	false	Enable Level 3 git rollback (off by default)
GUARDIAN_LOG	/tmp/openclaw-guardian.log	Log file path (rotates at 1 MB)
GUARDIAN_WORKSPACE	$HOME/.openclaw/workspace	Path to the OpenClaw workspace git repo
GUARDIAN_TELEGRAM_BOT_TOKEN	(unset)	Telegram Bot API token
GUARDIAN_TELEGRAM_CHAT_ID	(unset)	Telegram chat or channel ID
GUARDIAN_DISCORD_WEBHOOK_URL	(unset)	Discord incoming webhook URL
OPENCLAW_PORT	(auto-detected)	Gateway HTTP port — auto-parsed from openclaw gateway status if not set

---

File Layout

skills/openclaw-guardian/
├── SKILL.md                    ← this file
└── scripts/
    ├── guardian.sh             ← main watchdog (run continuously)
    ├── install-guardian.sh     ← sets up launchd / systemd service
    └── uninstall-guardian.sh   ← clean removal

Runtime files (created automatically, not committed):

File	Purpose
/tmp/openclaw-guardian.lock	Single-instance lockfile containing PID
/tmp/openclaw-guardian-last-snapshot	Date of last successful daily snapshot
/tmp/openclaw-guardian.log	Current log (rotated to .log.1 at 1 MB)

---

How It Improves on myclaw-guardian

Issue in myclaw-guardian	Fix in openclaw-guardian
git reset --hard without stashing — could silently destroy uncommitted work	Always git stash before any reset; git stash pop to restore regardless of outcome
Process detection via pgrep — fragile, can match wrong process	Uses openclaw gateway status (the actual CLI) as primary, with HTTP fallback
No lockfile — multiple instances could run simultaneously	/tmp/openclaw-guardian.lock with PID written; stale lock detection on startup
Only Discord alerts	Supports Telegram and Discord simultaneously; log-only if neither configured
Level 3 rollback always enabled — risky default	Level 3 off by default (GUARDIAN_ENABLE_ROLLBACK=false), explicit opt-in required
No graduated health checking	Two independent checks: CLI → HTTP; both must fail before declaring gateway down
No cooldown after exhausting repairs	Configurable cooldown (GUARDIAN_COOLDOWN) before resuming monitoring

---

Logging

Logs are timestamped and structured:

[2026-03-05 11:30:00] [INFO] OpenClaw Guardian started (PID 12345)
[2026-03-05 11:30:30] [INFO] Gateway healthy
[2026-03-05 11:31:00] [WARN] CLI status check failed — trying HTTP health endpoint
[2026-03-05 11:31:05] [WARN] Gateway health check FAILED
[2026-03-05 11:31:05] [INFO] ALERT: 🔴 Gateway is DOWN — beginning repair sequence
[2026-03-05 11:31:05] [INFO] Repair Level 1: restarting gateway
[2026-03-05 11:31:35] [INFO] Level 1 repair succeeded

Log rotates automatically when it exceeds 1 MB (one backup: .log.1).

---

Security Notes

• No secrets in git — daily snapshots use git add -A which respects .gitignore. Ensure your .gitignore excludes .env, *.key, etc.
• Level 3 rollback is destructive by nature — only enable it if you understand git reset semantics and have tested your .gitignore coverage.
• Alert tokens in env only — never put GUARDIAN_TELEGRAM_BOT_TOKEN or webhook URLs in files that get committed.