OpenClaw Self-Healing
A five-level autonomous recovery ladder for OpenClaw Gateway — instant restart, AI diagnosis, human escalation — so 3 AM pages get tried on the machine first.
Secrets stored in a chmod 600 .env, --dry-run preview exists, the AI tier can be degraded by leaving ANTHROPIC_API_KEY empty, and the docs explicitly disclose that Level 3 grants an AI session write access to config/process/logs — external effects are well disclosed. However, Level 3 inherently gives an AI write access to a live system with no explicit confirmation gate, doctor --fix runs automatically, preflight refuses to start the gateway, and rollback relies on manual backups; deductions center on these.
The changelog honestly records multiple severe historical defects (installer silently writing 404 bodies as scripts, key scripts committed base64-encoded and unrunnable, plist path mismatch, validate-deployment.sh path mismatch), showing key paths were long unrunnable. Most were fixed in Unreleased, but a static read cannot verify the fixes, and known gaps remain (Level 2 alerts never delivered, hardcoded Claude path). Failure feedback is well documented; scored 8, below the static cap of 10.
Target scenario (crash recovery for long-running OpenClaw Gateway), boundaries and non-fit ranges (other services require script edits, --dry-run macOS-only) are declared very clearly in the README, with per-level trigger conditions; Korean and English covered but no Chinese. Core Level 3 depends entirely on the Claude Code CLI and overseas alert channels (Discord/Slack/Telegram), which is a real mainland-China reachability obstacle; deducted here.
Layered docs (SKILL.md + README + CHANGELOG + CONTRIBUTING), version synced to 3.4.0, Keep-a-Changelog format, MIT license, a candid 'Known Gaps' section, and honest documentation of what the installer actually wires up — high-quality governance. Deducted because referenced docs files cannot all be confirmed present in this evidence, and the project's own changelog shows docs/behavior mismatches were historically pervasive.
Claims a 64% autonomous recovery rate from a self-audit of 14 incidents, with a clear value proposition and a comparison table versus plain watchdog/supervisord. But the figure is author-asserted without independent verification, a static read cannot confirm the fixed scripts produce directly usable output, and known gaps (undelivered alerts, false-failing validation script) weaken out-of-the-box results; scored 6, below the static cap of 7.
CI lint workflows (bash -n, ShellCheck) and a detailed changelog provide some auditable material; but the 64% recovery rate is narrative only, there is no committed test suite covering the skill's key paths and no third-party execution evidence, so key conclusions are not independently reproducible; scored 3, below the static cap of 5.
- Level 3 grants an AI session write access to OpenClaw config, gateway process control and logs; confirm you accept this before enabling. Leaving ANTHROPIC_API_KEY empty stops the chain at Level 2.
- Known gaps: Level 2 watchdog alerts are not delivered by default (depends on an alert.sh not shipped in the repo); validate-deployment.sh checks the wrong path and false-reports; the Claude CLI path is hardcoded to /opt/homebrew/bin/claude and needs manual patching on Intel Macs and Linux.
- Core function depends on the Claude Code CLI and Discord/Slack/Telegram overseas services; usability is limited from mainland-China networks, and there are no Chinese docs.
- The changelog shows the project previously had severe defects — installer silently writing 404 bodies as scripts and key scripts committed base64-encoded and unrunnable; most fixes are not yet independently execution-verified.
- The 64% autonomous recovery rate is author self-audited and not third-party verified.
What does this skill do, and when should you use it?
openclaw-self-healing (v3.4.0) wraps OpenClaw Gateway in a five-level recovery ladder of shell scripts. Level 0 validates config before start; Level 1 is instant restart via the gateway's own service unit; Level 2 runs PID/HTTP/memory checks every 3–5 minutes with exponential backoff; Level 3 opens a tmux session with the Claude Code CLI that reads real logs before diagnosing and repairing; Level 4 alerts a human via Discord, Slack or Telegram. Production data shows 9 of 14 real incidents (64%) resolved fully autonomously. It deploys via macOS LaunchAgent, Linux systemd, or Docker Compose.
Validates gateway binary, node, .env keys and JSON configs before cold start, backing up known-good configs; polls PID, HTTP 200 and memory every 3/5 minutes with exponential backoff and auto-runs openclaw doctor --fix on config-schema errors; after 30 minutes of continuous failure, opens a tmux PTY session running Claude Code CLI with a mandatory read-real-state prompt, producing recovery reports, reasoning logs and a persistent symptom→cause→fix learnings file; sends log-path-attached alerts to Discord/Slack/Telegram when automation is exhausted; exports eight Prometheus gauges and generates a weekly incident digest.
- A solo operator running OpenClaw Gateway long-term who keeps getting paged by crash loops that a restart cannot fix (corrupted config, missing key)
- A developer who wants AI to read the logs and attempt a repair before humans are notified, with log paths attached when it fails
- A team needing Grafana dashboards and alert rules, served by the eight Prometheus gauges including recovery-rate tracking
- Users on macOS LaunchAgent or Linux systemd (with user lingering) who want a one-line curl install
- Container-based deployments that want gateway plus watchdog via Docker Compose
What are this skill's strengths and limitations?
- Five-level ladder covers instant restart through AI diagnosis to human escalation
- Level 3 forces the model to read real logs and config first, and flags reports with tool_use=0 as suspected hallucination
- Persistent learnings file accumulates symptom → root cause → fix → prevention across incidents
- Production-proven: 9 of 14 real incidents resolved fully autonomously (64%)
- Good operational tooling: deployment validator, --dry-run installer preview, weekly incident digest
- Honest, well-documented known-gaps list
- Level 2 watchdog alerts depend on an alert.sh the repo does not ship — out of the box they are logged but never delivered
- The LLM router is shipped but not wired in; OPENCLAW_LLM_PROVIDER has no effect and Claude Code CLI is a hard dependency
- Claude CLI path hardcoded to /opt/homebrew/bin/claude; Intel Macs and Linux require a script edit
- validate-deployment.sh checks the wrong path and reports false failures for Level 0 and Level 2 scripts
- Uneven notification coverage: emergency-recovery-v2.sh lacks Slack; gateway-preflight.sh supports only Discord and ntfy
- Tested only against OpenClaw Gateway; adapting to another service means editing scripts
- Environment-specific requirements: systemd user lingering on Linux, macOS 12+, Homebrew at /opt/homebrew
- The 64% autonomous-recovery figure comes from a single-instance audit of 14 incidents — a small sample
How do you install this skill?
One-line install (macOS; Linux auto-hands off to install-linux.sh): curl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-self-healing/main/install.sh | bash. Preview first with bash -s -- --dry-run (macOS only). The installer checks prerequisites (tmux, claude, curl; jq and systemd on Linux), downloads scripts, generates ~/.openclaw/.env, and registers LaunchAgent/systemd timers. Manually edit ~/.openclaw/.env to add your webhook and gateway token. Docker: clone the repo, cp .env.example .env, then docker compose up -d. Note: the Level 3 Claude CLI path is hardcoded to /opt/homebrew/bin/claude — Intel Macs and Linux need a manual edit.
How do you use this skill?
After install, the watchdog and healthcheck run as scheduled units automatically. To enable Level 0, point your gateway's LaunchAgent/systemd unit at gateway-preflight.sh (it execs the real gateway once checks pass). Verify with launchctl list | grep openclaw.healthcheck (or systemctl --user list-timers | grep openclaw on Linux); kill the gateway process and tail -f ~/.openclaw/logs/watchdog.log to watch recovery; run bash scripts/validate-deployment.sh for a full five-level check (mind the known false-failure path bug). Recovery reports and learnings land in ~/openclaw/memory/.
How does this skill compare with similar options?
The README compares it against a basic watchdog and supervisord: both only restart on crash (supervisord with partial backoff), while this adds HTTP health polling, exponential backoff, pre-start config validation, AI root-cause diagnosis, openclaw doctor --fix auto-repair, multi-channel alerts, and Prometheus metrics. The gap that matters: when a crash loop is caused by something a restart cannot fix, the other tools page you — this one tries to read the logs first.