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 \x3Csubsystem> 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 \x3Cseconds> (default: 300), --max-heals \x3Cn> 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

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
}