🛡️ 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. 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)

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):

CODEBLOCK0

2. Install as a system service

CODEBLOCK1

3. Verify it's running

CODEBLOCK2

4. Run manually (testing / foreground)

CODEBLOCK3

5. Uninstall

CODEBLOCK4

Environment Variable Reference

File Layout

CODEBLOCK5

Runtime files (created automatically, not committed):

How It Improves on myclaw-guardian

Logging

Logs are timestamped and structured:

CODEBLOCK6

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.