- name
- claw-guard
- description
- System-level watchdog for OpenClaw gateway restarts and sub-agent task PIDs. Monitors registered PIDs and optional log/directory freshness. Auto-reverts config on failed gateway restarts. Requires explicit registration — does NOT auto-discover. Use when running long background tasks or before gateway restarts.
ClawGuard — Task & Gateway Watchdog
A lightweight service that monitors registered events:
- Sub-agent task PIDs — if PID dies → notify and remove. If log/dir stale → alert and remove.
- Gateway restarts — if restart fails → revert config backups (newest to oldest) → retry → notify.
ClawGuard only monitors what is explicitly registered. It does not auto-discover.
Install
cd <skill-dir>
bash scripts/install.shInstalls:
- Daemon: systemd user service (Linux) or launchd agent (macOS) —
Restart=always, auto-starts on boot - CLI:
claw-guardin~/.local/bin/ - Data:
~/.openclaw/workspace/tools/claw-guard/
OpenClaw Integration (Recommended)
1. Auto-register gateway restarts
Add ExecStartPre to your gateway service so every restart (manual, crash, or Restart=always) is automatically registered:
# ~/.config/systemd/user/openclaw-gateway.service
[Service]
ExecStartPre=/home/<user>/.local/bin/claw-guard register-restart
ExecStart=...Then reload: systemctl --user daemon-reload
Now every gateway restart automatically:
- Snapshots the current config (rotates up to 5 backups)
- Watches for the gateway to come back
- If it fails → reverts config backups newest-to-oldest → notifies default channel
No manual claw-guard register-restart needed — systemd handles it.
2. Add task execution rules to AGENTS.md
Add these rules so the agent always registers its work:
## Task Execution Rules (MANDATORY)
### Sub-agent requirement
- **Any exec/tool call that might take >5s → sub-agent** (`sessions_spawn`).
Main agent stays responsive.
- **Complex or unpredictable tasks → always sub-agent.** Even if they might
be fast. If you can't guarantee it won't block, delegate it.
- **Only run in main agent** if certain it won't block I/O (quick file reads,
short `grep`, `git status`, `claw-guard status`, etc.)
### ClawGuard registration (MANDATORY for all sub-agents)
Every sub-agent and background process **must** be registered:claw-guard register --id "<descriptive-id>" --pid <PID> \ --target "<channel where task was requested>" \ --log "/path/to/logfile" --timeout 180 \ --command "<what it does>"
- `--target`: same channel/room where the user asked for the task
- `--log` and `--timeout`: optional but recommended for long tasks
- If PID dies → claw-guard notifies the target channel and removes the entry
- If log goes stale → claw-guard notifies and removes
### Gateway restarts
- **Never restart the gateway while tasks are running** — it kills all sub-agents
- Gateway service has `ExecStartPre=claw-guard register-restart` — automatic
- No manual registration needed for restarts3. How it works end-to-end
Sub-agent task flow:
- User requests a long-running task
- Agent spawns sub-agent → gets PID
- Agent runs:
claw-guard register --id "task-name" --pid $PID --target "room:..." --command "..." - If PID dies → claw-guard notifies the target channel → agent confirms result with user
- If log goes stale → claw-guard alerts → agent investigates
Gateway restart flow:
- Gateway restarts (manual, crash, or auto)
ExecStartPrerunsclaw-guard register-restart→ config backed up- Gateway starts successfully → claw-guard logs
✅ Gateway restart succeeded→ watch cleared - Gateway fails to start → claw-guard tries config backups → notifies default channel
CLI Reference
Register a task
claw-guard register --id "benchmark-q8" --pid 12345 \
--target "room:!abc:server" \
--log "/path/to/task.log" --timeout 180 \
--command "python3 benchmark.py"
# Or watch a directory for new file creation:
claw-guard register --id "export-gguf" --pid 12345 \
--target "room:!abc:server" \
--watch-dir "/path/to/output/" --timeout 300 \
--command "export_gguf.py"| Flag | Required | Description |
|---|---|---|
--id | yes | Unique task identifier |
--pid | yes | Process ID to watch |
--target | yes | Notification target (see formats below) |
--log | no | Log file path — checks mtime only |
--watch-dir | no | Directory — checks newest file mtime |
--timeout | no | Stale threshold in seconds (default: 180) |
--command | no | Description included in notifications |
Register a gateway restart
claw-guard register-restart [--target "room:!abc:server"]No --target needed — sends to OpenClaw's default channel. Pass --target to override.
Manage
claw-guard status # Show tasks, restart watch, config backups
claw-guard remove --id X # Remove a task
claw-guard clear-done # Remove completed/gone tasksBehavior
Check cycle (every 15s)
- Gateway restart: if registered and gateway not active after 30s → revert + retry + notify
- PID check: if PID gone → notify target → remove entry
- Log/dir freshness: if mtime exceeds timeout → notify target → remove entry
Deduplication
After notifying, the registered entry is removed from the registry. Once removed, it can't fire again. No dedup tracking needed.
Restart / reboot behavior
On service restart or system reboot:
- All registered tasks are cleared — nothing carries over
- Config backups persist on disk (only thing that survives)
This is by design: after a reboot, all monitored processes are gone anyway. The agent must re-register any new tasks.
Notification Targets
Any format openclaw message send --target accepts:
room:!roomId:server(Matrix)telegram:chatiddiscord:#channelslack:#channel
Gateway restart alerts with no --target are sent without a target flag, letting OpenClaw route to the default channel.
Design Principles
- Registration-based, not auto-discovery — only watches what's explicitly registered
- Notify once, then remove — no duplicate alerts, no stale state
- In-memory state — registry clears on service restart (clean slate)
- Disk persistence only for config backups — the only thing worth keeping across restarts
- Cross-platform — Linux (systemd) and macOS (launchd)
- Minimal overhead — ~7MB RAM, negligible CPU