{"skill":{"slug":"openclaw-claw-guard","displayName":"ClawGuard","summary":"System-level watchdog for OpenClaw gateway restarts and sub-agent task PIDs. Monitors registered PIDs and optional log/directory freshness. Auto-reverts conf...","description":"---\nname: claw-guard\ndescription: 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.\n---\n\n# ClawGuard — Task & Gateway Watchdog\n\nA lightweight service that monitors **registered** events:\n\n1. **Sub-agent task PIDs** — if PID dies → notify and remove. If log/dir stale → alert and remove.\n2. **Gateway restarts** — if restart fails → revert config backups (newest to oldest) → retry → notify.\n\n**ClawGuard only monitors what is explicitly registered.** It does not auto-discover.\n\n## Install\n\n```bash\ncd <skill-dir>\nbash scripts/install.sh\n```\n\nInstalls:\n- **Daemon**: systemd user service (Linux) or launchd agent (macOS) — `Restart=always`, auto-starts on boot\n- **CLI**: `claw-guard` in `~/.local/bin/`\n- **Data**: `~/.openclaw/workspace/tools/claw-guard/`\n\n## OpenClaw Integration (Recommended)\n\n### 1. Auto-register gateway restarts\n\nAdd `ExecStartPre` to your gateway service so every restart (manual, crash, or `Restart=always`) is automatically registered:\n\n```ini\n# ~/.config/systemd/user/openclaw-gateway.service\n[Service]\nExecStartPre=/home/<user>/.local/bin/claw-guard register-restart\nExecStart=...\n```\n\nThen reload: `systemctl --user daemon-reload`\n\nNow every gateway restart automatically:\n- Snapshots the current config (rotates up to 5 backups)\n- Watches for the gateway to come back\n- If it fails → reverts config backups newest-to-oldest → notifies default channel\n\n**No manual `claw-guard register-restart` needed — systemd handles it.**\n\n### 2. Add task execution rules to AGENTS.md\n\nAdd these rules so the agent always registers its work:\n\n```markdown\n## Task Execution Rules (MANDATORY)\n\n### Sub-agent requirement\n- **Any exec/tool call that might take >5s → sub-agent** (`sessions_spawn`).\n  Main agent stays responsive.\n- **Complex or unpredictable tasks → always sub-agent.** Even if they might\n  be fast. If you can't guarantee it won't block, delegate it.\n- **Only run in main agent** if certain it won't block I/O (quick file reads,\n  short `grep`, `git status`, `claw-guard status`, etc.)\n\n### ClawGuard registration (MANDATORY for all sub-agents)\nEvery sub-agent and background process **must** be registered:\n```bash\nclaw-guard register --id \"<descriptive-id>\" --pid <PID> \\\n  --target \"<channel where task was requested>\" \\\n  --log \"/path/to/logfile\" --timeout 180 \\\n  --command \"<what it does>\"\n```\n- `--target`: same channel/room where the user asked for the task\n- `--log` and `--timeout`: optional but recommended for long tasks\n- If PID dies → claw-guard notifies the target channel and removes the entry\n- If log goes stale → claw-guard notifies and removes\n\n### Gateway restarts\n- **Never restart the gateway while tasks are running** — it kills all sub-agents\n- Gateway service has `ExecStartPre=claw-guard register-restart` — automatic\n- No manual registration needed for restarts\n```\n\n### 3. How it works end-to-end\n\n**Sub-agent task flow:**\n1. User requests a long-running task\n2. Agent spawns sub-agent → gets PID\n3. Agent runs: `claw-guard register --id \"task-name\" --pid $PID --target \"room:...\" --command \"...\"`\n4. If PID dies → claw-guard notifies the target channel → agent confirms result with user\n5. If log goes stale → claw-guard alerts → agent investigates\n\n**Gateway restart flow:**\n1. Gateway restarts (manual, crash, or auto)\n2. `ExecStartPre` runs `claw-guard register-restart` → config backed up\n3. Gateway starts successfully → claw-guard logs `✅ Gateway restart succeeded` → watch cleared\n4. Gateway fails to start → claw-guard tries config backups → notifies default channel\n\n## CLI Reference\n\n### Register a task\n\n```bash\nclaw-guard register --id \"benchmark-q8\" --pid 12345 \\\n  --target \"room:!abc:server\" \\\n  --log \"/path/to/task.log\" --timeout 180 \\\n  --command \"python3 benchmark.py\"\n\n# Or watch a directory for new file creation:\nclaw-guard register --id \"export-gguf\" --pid 12345 \\\n  --target \"room:!abc:server\" \\\n  --watch-dir \"/path/to/output/\" --timeout 300 \\\n  --command \"export_gguf.py\"\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--id` | yes | Unique task identifier |\n| `--pid` | yes | Process ID to watch |\n| `--target` | yes | Notification target (see formats below) |\n| `--log` | no | Log file path — checks mtime only |\n| `--watch-dir` | no | Directory — checks newest file mtime |\n| `--timeout` | no | Stale threshold in seconds (default: 180) |\n| `--command` | no | Description included in notifications |\n\n### Register a gateway restart\n\n```bash\nclaw-guard register-restart [--target \"room:!abc:server\"]\n```\n\nNo `--target` needed — sends to OpenClaw's default channel. Pass `--target` to override.\n\n### Manage\n\n```bash\nclaw-guard status          # Show tasks, restart watch, config backups\nclaw-guard remove --id X   # Remove a task\nclaw-guard clear-done      # Remove completed/gone tasks\n```\n\n## Behavior\n\n### Check cycle (every 15s)\n\n1. **Gateway restart**: if registered and gateway not active after 30s → revert + retry + notify\n2. **PID check**: if PID gone → notify target → remove entry\n3. **Log/dir freshness**: if mtime exceeds timeout → notify target → remove entry\n\n### Deduplication\n\nAfter notifying, the registered entry is **removed from the registry**. Once removed, it can't fire again. No dedup tracking needed.\n\n### Restart / reboot behavior\n\nOn service restart or system reboot:\n- **All registered tasks are cleared** — nothing carries over\n- **Config backups persist** on disk (only thing that survives)\n\nThis is by design: after a reboot, all monitored processes are gone anyway. The agent must re-register any new tasks.\n\n## Notification Targets\n\nAny format `openclaw message send --target` accepts:\n- `room:!roomId:server` (Matrix)\n- `telegram:chatid`\n- `discord:#channel`\n- `slack:#channel`\n\nGateway restart alerts with no `--target` are sent without a target flag, letting OpenClaw route to the default channel.\n\n## Design Principles\n\n- **Registration-based, not auto-discovery** — only watches what's explicitly registered\n- **Notify once, then remove** — no duplicate alerts, no stale state\n- **In-memory state** — registry clears on service restart (clean slate)\n- **Disk persistence only for config backups** — the only thing worth keeping across restarts\n- **Cross-platform** — Linux (systemd) and macOS (launchd)\n- **Minimal overhead** — ~7MB RAM, negligible CPU\n","tags":{"latest":"1.1.0"},"stats":{"comments":0,"downloads":864,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":3},"createdAt":1772427603436,"updatedAt":1778994419360},"latestVersion":{"version":"1.1.0","createdAt":1772429356751,"changelog":"Comprehensive SKILL.md: OpenClaw integration guide with ExecStartPre auto-registration, AGENTS.md rules template, end-to-end flow docs, CLI reference table.","license":null},"metadata":null,"owner":{"handle":"camopel","userId":"s173h157g83yxadz0b0brs0h6s884my9","displayName":"camopel","image":"https://avatars.githubusercontent.com/u/18227220?v=4"},"moderation":null}