Self-Healing Agent

Automated failure detection, diagnosis, and recovery for OpenClaw agents. The watchdog that keeps your agent running.

Quick Start


# Full health check — scan all systems, diagnose issues, suggest fixes
python3 scripts/self-healing-agent.py check

# Auto-heal — detect and fix what it can automatically
python3 scripts/self-healing-agent.py heal

# Monitor mode — run continuously, fix issues as they appear
python3 scripts/self-healing-agent.py monitor --interval 300

# Check specific subsystem
python3 scripts/self-healing-agent.py check --target cron
python3 scripts/self-healing-agent.py check --target memory
python3 scripts/self-healing-agent.py check --target config
python3 scripts/self-healing-agent.py check --target sessions

Commands

`check` — Health Check

Runs diagnostic suite:

Cron health — Failed jobs, consecutive errors, stuck jobs, timeout patterns
Memory health — File sizes, bloated sessions, orphaned files, growth rate
Config health — Valid JSON, required fields present, deprecated settings
Session health — Active sessions, zombie processes, memory usage
Skill health — Broken scripts, missing dependencies, syntax errors
Network health — API endpoint reachability, DNS resolution, SSL cert validity

Options: --target to check one area, --json for machine output.

`heal` — Auto-Repair

For each detected issue, applies the safest fix:

Restarts failed cron jobs (after diagnosing root cause)
Clears bloated session files (with backup)
Fixes JSON syntax errors in config (common trailing comma, etc.)
Removes orphaned process files
Restores corrupted memory files from git history
Rotates oversized log files

Options: --dry-run to preview, --aggressive for riskier fixes.

`monitor` — Continuous Watchdog

Runs in a loop, checking health every N seconds:

Logs findings to memory/self-healing-log.json
Auto-heals fixable issues
Escalates unfixable issues to the agent's main session
Tracks MTTR (mean time to recovery) and failure patterns

Options: --interval (default: 300), --max-heals per cycle.

`report` — Health Report

Generates a markdown health report covering:

Last 24h failure count and types
MTTR statistics
Most common failure modes
Recommendations for prevention

What It Monitors

| Subsystem | Checks | Auto-Heals |

|-----------|--------|------------|

| Cron | Failed runs, timeouts, consecutive errors | Restart jobs, clear error state |

| Memory | File sizes >1MB, growth rate, duplicates | Archive old files, compact |

| Config | JSON validity, required fields, deprecated keys | Fix syntax, add defaults |

| Sessions | Zombie processes, bloated contexts | Kill zombies, archive contexts |

| Skills | Syntax errors, missing deps, broken imports | Log issue, skip broken skill |

| Network | API endpoints, DNS, SSL certs | Retry with backoff, switch endpoints |

Healing Log

All actions are logged to memory/self-healing-log.json:


{
  "timestamp": "2026-04-05T06:00:00Z",
  "issue": "cron job 'daily-intel' failed 3 consecutive times",
  "diagnosis": "Script timeout — API rate limit hit",
  "action": "Reset error count, added 30s backoff, restarted",
  "result": "success",
  "mttr_seconds": 12
}

File Access Scope

This skill accesses files outside the workspace directory:

~/.openclaw/sessions/ — Read-only stat() checks to detect zombie/bloated sessions. No session content is read or modified.
~/.openclaw/openclaw.json — Read to validate JSON syntax and required fields. May write to repair JSON syntax errors (e.g., trailing commas, missing brackets) during heal if config corruption is detected. A backup is created before any modification.

Self Healing Agent