docs/cron-system.md

OpenClaw Cron System

Cain's autonomous maintenance and health monitoring system.

Overview

The cron system provides self-healing capabilities for Cain by automatically monitoring health status and recovering from errors.

Job Configuration

Located in .openclaw/cron/jobs.json, following the OpenClaw cron schema:

{
  "jobs": [
    {
      "id": "health-check",
      "schedule": "*/30 * * * *",
      "enabled": true,
      "description": "Monitor Cain's health and auto-recover from errors",
      "tool": "hf_space_status",
      "on_failure": {
        "tool": "hf_restart_space",
        "condition": "status in ['RUNTIME_ERROR', 'BUILDING'] and duration_minutes > 10"
      }
    }
  ]
}

Current Jobs

health-check

• Schedule: Every 30 minutes
• Purpose: Monitor Cain's Hugging Face Space status
• Tool: hf_space_status
• Auto-recovery: Restarts space if in RUNTIME_ERROR or BUILDING state for >10 minutes
• Logs: .openclaw/logs/health-check.jsonl

session-archive

• Schedule: Weekly on Sunday at 2:00 AM
• Purpose: Automatically archive sessions older than 7 days
• Tool: session_archive
• Parameters: threshold_days: 7, dry_run: false
• Logs: .openclaw/logs/session-archive.jsonl

Session Archival

Cain includes an automatic session archival system to keep the active sessions directory clean and performant.

How It Works

1. Automatic Archival: Sessions older than 7 days (configurable) are automatically moved to the archived directory
2. Scheduled Job: Runs weekly by default (Sunday at 2:00 AM)
3. Index Updates: Both the main and archived session indices are updated
4. Restore Capability: Archived sessions can be restored if needed

Directory Structure

.openclaw/agents/main/sessions/
├── sessions.json              # Main sessions index (active sessions only)
├── session_*.jsonl            # Active session files
└── archived/
    ├── archived_sessions.json # Index of archived sessions
    └── session_*.jsonl        # Archived session files

Manual Archival Operations

Run the archive manager directly:

# Archive sessions (dry-run first)
python3 .openclaw/agents/main/sessions/archive_manager.py --archive --dry-run

# Actually archive sessions
python3 .openclaw/agents/main/sessions/archive_manager.py --archive

# List archived sessions
python3 .openclaw/agents/main/sessions/archive_manager.py --list

# Restore a session
python3 .openclaw/agents/main/sessions/archive_manager.py --restore SESSION_ID

# Show statistics
python3 .openclaw/agents/main/sessions/archive_manager.py --stats

# Custom threshold (e.g., 14 days)
python3 .openclaw/agents/main/sessions/archive_manager.py --archive --threshold 14

Archival Log Format

{"timestamp":"2026-03-14T02:00:00Z","action":"archive_sessions","threshold_days":7,"dry_run":false,"total_files":50,"archived_count":35,"skipped_count":10,"error_count":0,"status":"success"}
{"timestamp":"2026-03-14T02:00:01Z","action":"restore_session","session_id":"session_abc123","status":"success","restored_from":"/path/to/archived/session_abc123.jsonl"}

Configuration

To modify the archival behavior, edit .openclaw/cron/jobs/session-archive.json:

{
  "id": "session-archive",
  "schedule": "0 2 * * 0",  // Adjust cron schedule
  "enabled": true,
  "params": {
    "threshold_days": 7,     // Days before archival
    "dry_run": false         // Set true for testing
  }
}

Log Format

Health checks are logged in JSONL format:

{"timestamp":"2026-03-14T00:00:00Z","job_id":"health-check","status":"RUNNING","stage":"RUNNING","detail":"HuggingClaw is running","action":"check"}
{"timestamp":"2026-03-14T00:30:00Z","job_id":"health-check","status":"RUNTIME_ERROR","action":"recovery_triggered"}
{"timestamp":"2026-03-14T00:31:00Z","job_id":"health-check","status":"RUNNING","action":"recovery_success"}

Adding New Jobs

1. Edit .openclaw/cron/jobs.json
2. Add a new job object to the jobs array
3. Set enabled: true to activate
4. Restart the cron daemon

Monitoring

View recent health checks:

tail -20 .openclaw/logs/health-check.jsonl

Count failures in last 24 hours:

jq -r 'select(.action=="recovery_triggered")' .openclaw/logs/health-checks.jsonl | wc -l