OpenClaw Auto-Recovery & Reliability

1 What is OpenClaw Auto-Recovery?

OpenClaw is an open-source personal AI assistant platform that runs as a multi-channel gateway supporting Telegram and WhatsApp. As your AI assistant runs continuously for days, weeks, or months, various issues can occur: configuration files can become corrupted, channels can silently fail, and the gateway can enter "zombie states" where it appears healthy but isn't functioning properly.

The auto-recovery system addresses these challenges through five defense layers that work together to ensure your assistant stays operational. According to the official OpenClaw documentation, the platform only accepts configurations that fully match the schema, and when validation fails, diagnostic commands like openclaw doctor become essential for recovery.

Multi-Layer Defense Architecture

These layers work together to create a self-healing system. When a problem is detected, the monitor first validates the configuration, attempts automatic repair, falls back to backups if needed, and notifies you throughout the process.

2 The Zombie State Problem

One of the most challenging issues with long-running AI assistants is the "zombie state" - a condition where the gateway process is running and health checks pass, but channels like Telegram or WhatsApp silently stop receiving messages. This can go unnoticed for hours or even days.

Real-World Scenario

Consider this actual incident: A Telegram channel was silent for 46 hours (February 2-4, 2026) while the gateway reported "OK" status. The process was running, the health endpoint responded, but no messages were being received or sent. Without proactive monitoring, this would have continued indefinitely.

Root Causes of Zombie States

Why Traditional Health Checks Fail

The standard approach of checking http://localhost:18789/health returns OK as long as the Node.js process responds. This tells you nothing about:

• Channel connectivity: Is Telegram actually connected?
• Message flow: Are messages being received and sent?
• Provider state: Is the long-polling session active?
• Processing capability: Can the AI actually respond?

This is why OpenClaw auto-recovery implements five distinct health checks that go beyond simple process monitoring to validate actual messaging functionality.

3 Config Corruption & Recovery

Configuration corruption is a common cause of gateway failures. According to the OpenClaw doctor documentation, the gateway validates all configuration against OpenClawSchema (a Zod schema) before startup. Invalid configs cause the gateway to refuse to start for safety.

Common Config Corruption Causes

• Manual editing errors: Typos, missing commas, or invalid JSON syntax
• Plugin/skill conflicts: Skills adding incompatible config keys
• Incomplete updates: Interrupted config writes during updates
• Version mismatches: Old config format after OpenClaw upgrade
• Environment variable issues: Unresolved ${...} references

The Doctor Command

The openclaw doctor command is the primary repair tool. As noted in the CLI reference, it automates common repair tasks and runs a series of checks with fixes for detected issues.

# Run health check (diagnosis only)
openclaw doctor

# Run with automatic fixes
openclaw doctor --fix

# Run without interactive prompts (for scripts/cron)
openclaw doctor --non-interactive --fix

# Deep diagnostics
openclaw doctor --deep

Config Validation Process

Before any restart, the health monitor validates the configuration using the native OpenClaw API:

# Validate config programmatically
openclaw gateway call config.get --json

# Response includes:
# - .valid: true/false
# - .issues: array of validation problems

The validation function checks the .valid field and, if false, counts issues from the .issues array to provide detailed diagnostics.

Recovery Flow

4 Backup System Architecture

OpenClaw maintains a rotating backup system that preserves the last 5 versions of your configuration. These backups are created automatically on config modifications, providing a safety net for recovery.

Backup File Locations

Cascade Backup Testing

When config corruption is detected and doctor auto-fix fails, the recovery system tests backups in order from newest to oldest. Here's the actual restoration logic:

restore_from_backup() {
    log "Attempting config restore from backups..."

    # Try backups in order: .bak, .bak.1, .bak.2, .bak.3, .bak.4
    for backup in "" ".1" ".2" ".3" ".4"; do
        local backup_file="$OPENCLAW_DIR/openclaw.json.bak$backup"

        if [[ ! -f "$backup_file" ]]; then
            continue
        fi

        log "Testing backup: $(basename "$backup_file")"
        cp "$backup_file" "$OPENCLAW_DIR/openclaw.json"

        if validate_config; then
            log "Successfully restored from $(basename "$backup_file")"
            notify "[OK] Config Restored from: $(basename "$backup_file")"
            return 0
        fi
    done

    log "CRITICAL: All backups failed validation"
    notify "[ALERT] Config Recovery Failed - Manual intervention required"
    return 1
}

Why This Approach Works

• Non-destructive: Original config is preserved during testing
• Validation-first: Each backup is validated before being accepted
• Ordered cascade: Newest backups tried first (most likely to be valid)
• Graceful degradation: Falls back through progressively older configs
• Clear notifications: You're informed at every recovery step

5 Gateway Health Monitor

The gateway health monitor is the first line of defense against zombie states and channel failures. It runs every 15 minutes via macOS LaunchAgent and performs five distinct health checks.

The Five Health Checks

Message Activity Check Strategy

The message activity check uses a two-strategy approach for maximum reliability:

Restart Process

When issues are detected, the monitor triggers a safe restart sequence:

restart_gateway() {
    log "Validating config before restart..."

    # Step 1: Validate current config
    if ! validate_config; then
        log "Config invalid - attempting auto-repair"
        notify "[WARNING] Config Corruption Detected - Attempting repair..."

        # Step 2: Try doctor auto-fix
        if openclaw doctor --non-interactive --fix; then
            if validate_config; then
                notify "[FIX] Config Auto-Fixed Successfully"
            else
                # Step 3: Fall back to backup restoration
                restore_from_backup || return 1
            fi
        else
            restore_from_backup || return 1
        fi
    fi

    # Step 4: Config valid, safe to restart
    log "Config validated - initiating gateway restart..."
    launchctl kickstart -k "gui/$(id -u)/ai.openclaw.gateway"
    sleep 5
    log "Gateway restart complete"
}

Running the Health Monitor

# Check health monitor service status
launchctl list | grep health-monitor

# Force run health check immediately
launchctl kickstart -k gui/$(id -u)/ai.openclaw.health-monitor

# View health monitor logs
tail -f ~/.openclaw/logs/health-monitor.log

# Manual test run
~/.openclaw/scripts/gateway-health-monitor.sh

6 Error Monitor & Auto-Remediation

The error monitor provides intelligent error diagnosis with automatic remediation for known issues. It scans the error log every 5 minutes and takes corrective action when possible.

Error Categories & Auto-Fixes

Intelligent Deduplication

The error monitor implements smart deduplication to prevent notification spam:

• 6-hour window: Same error signature won't notify again for 6 hours
• Signature normalization: Timestamps, PIDs, and session IDs are stripped before hashing
• Rate limiting: 5-minute minimum between any notifications
• Ignore patterns: Deprecation warnings and known non-issues are filtered

# Clear deduplication cache to re-enable all alerts
rm ~/.openclaw/logs/.sent-errors

# Check which errors have been sent
cat ~/.openclaw/logs/.sent-errors

# View error monitor activity
tail -f ~/.openclaw/logs/error-monitor.log

SearXNG Integration for Unknown Errors

When an error doesn't match any known pattern, the monitor searches for solutions using a self-hosted SearXNG instance:

search_for_solution() {
    local error_text="$1"
    local search_query

    # Create focused search query by cleaning error text
    search_query=$(echo "$error_text" | 
        sed 's/[.*]//g' |            # Remove brackets
        sed 's/[0-9]{4}-[0-9]{2}...//g' |   # Remove timestamps
        sed 's//Users/[^[:space:]]*//g' |    # Remove paths
        head -c 100)

    search_query="fix $search_query"

    # Query local SearXNG instance
    curl -s "${SEARXNG_URL}/search?q=${search_query}&format=json"
}

7 Implementation Guide

Setting up the auto-recovery system requires creating the health monitoring scripts and configuring LaunchAgents on macOS. Here's a complete implementation guide.

Prerequisites

• OpenClaw installed and configured (openclaw status should work)
• macOS with LaunchAgent support
• Telegram bot for notifications (optional but recommended)
• jq installed for JSON parsing (brew install jq)

Step 1: Create Scripts Directory

# Create scripts directory
mkdir -p ~/.openclaw/scripts
mkdir -p ~/.openclaw/logs

Step 2: Create Telegram Notification Script

#!/bin/bash
# ~/.openclaw/scripts/telegram-notify.sh

TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"
TELEGRAM_CHAT_ID="YOUR_CHAT_ID"

message="$1"

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" 
    -d chat_id="${TELEGRAM_CHAT_ID}" 
    -d parse_mode="HTML" 
    -d text="${message}" > /dev/null

Step 3: Create LaunchAgent for Health Monitor

# Create LaunchAgent plist
cat > ~/Library/LaunchAgents/ai.openclaw.health-monitor.plist << 'EOF'




    Label
    ai.openclaw.health-monitor
    ProgramArguments
    
        /bin/bash
        -c
        ~/.openclaw/scripts/gateway-health-monitor.sh
    
    StartInterval
    900
    RunAtLoad
    
    StandardOutPath
    ~/.openclaw/logs/health-monitor.log
    StandardErrorPath
    ~/.openclaw/logs/health-monitor.log


EOF

# Load the LaunchAgent
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.health-monitor.plist

Step 4: Verify Installation

# Check if service is loaded
launchctl list | grep health-monitor

# Force run to test
launchctl kickstart -k gui/$(id -u)/ai.openclaw.health-monitor

# Check logs
tail -20 ~/.openclaw/logs/health-monitor.log

8 Troubleshooting Common Issues

Gateway Won't Start After Config Change

Health Monitor Not Running

# Check LaunchAgent status
launchctl list | grep health-monitor

# If not listed, reload it
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.health-monitor.plist

# Check for errors
launchctl print gui/$(id -u)/ai.openclaw.health-monitor

# Verify script is executable
chmod +x ~/.openclaw/scripts/gateway-health-monitor.sh

Telegram Notifications Not Working

# Test notification script manually
~/.openclaw/scripts/telegram-notify.sh "Test message"

# Verify bot token
curl "https://api.telegram.org/botYOUR_TOKEN/getMe"

# Check chat ID is correct
curl "https://api.telegram.org/botYOUR_TOKEN/getUpdates"

Error Monitor Missing Errors

# Clear deduplication cache
rm ~/.openclaw/logs/.sent-errors

# Check state file
cat ~/.openclaw/logs/.error-monitor-state

# Reset state to reprocess all logs
rm ~/.openclaw/logs/.error-monitor-state

# Force run
launchctl kickstart -k gui/$(id -u)/ai.openclaw.error-monitor

All Backups Are Corrupted

If all 5 backup versions are corrupted (rare but possible), you'll need to manually recreate the configuration:

# Start fresh with wizard
openclaw init

# Or manually create minimal config
cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-20250514"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}
EOF

# Validate
openclaw doctor

9 Frequently Asked Questions

10 Abbreviations & Glossary

Related Reading

OpenClaw Articles

Claude Code Articles