Cron Jobs & Scheduled Tasks

Automation is where AI agents become truly powerful. Instead of waiting for user input, your OpenClaw agent can wake itself up, check systems, process data, and take action on a schedule you define.

This guide covers everything about scheduling in OpenClaw: cron syntax, heartbeat patterns, practical examples, and best practices for reliable automation.

What Are Cron Jobs?

Cron is a time-based job scheduler found in Unix-like operating systems. OpenClaw leverages cron to trigger agent actions at specific times or intervals.

Common Use Cases

• Health checks: Verify systems are running correctly
• Data sync: Pull data from APIs on a schedule
• Reports: Generate and send daily/weekly summaries
• Maintenance: Clean up old files or prune databases
• Monitoring: Check website uptime or service status
• Backups: Trigger backup operations automatically
• Content publishing: Post to blogs or social media

Cron Syntax Basics

Cron expressions consist of five fields representing time intervals:

* * * * *
│ │ │ │ │
│ │ │ │ └── Day of week (0-7, Sunday = 0 or 7)
│ │ │ └──── Month (1-12)
│ │ └────── Day of month (1-31)
│ └──────── Hour (0-23)
└────────── Minute (0-59)

Common Patterns

Special Characters

• * — Any value (wildcard)
• , — Value list separator (e.g., 1,3,5)
• - — Range (e.g., 1-5 means 1,2,3,4,5)
• / — Step values (e.g., */5 means every 5th unit)

Heartbeat Pattern

A heartbeat is a scheduled check that verifies your systems are healthy and operational. It is the foundation of reliable automation.

Basic Heartbeat Configuration

# config.yaml - Heartbeat configuration
heartbeat:
  enabled: true
  # Run every 5 minutes
  schedule: "*/5 * * * *"
  # The agent runs this prompt on schedule
  prompt: |
    Perform a system health check:
    1. Check if all critical services are running
    2. Verify disk space is above 20%
    3. Check for any error logs in the last hour
    4. Report any issues found
    5. If everything is healthy, log "All systems operational"

Heartbeat with Actions

A more advanced heartbeat that takes action when issues are detected:

heartbeat:
  enabled: true
  schedule: "*/10 * * * *"
  prompt: |
    Run the following health checks:
    
    1. WEBSITE CHECK:
       Use browser to verify https://mysite.com loads
       If status is not 200, add to issues list
    
    2. API CHECK:
       Use web_fetch to test API endpoint
       If response time > 5s, add to issues list
    
    3. DISK CHECK:
       Run df -h and check disk usage
       If any partition > 90%, add to issues list
    
    4. ACTION:
       If issues were found:
       - Send a message to admin via Telegram
       - Log the issues to heartbeat-errors.log
       - Include timestamp and severity
       
       If no issues:
       - Log "Health check passed" silently

Scheduled Tasks in OpenClaw

Beyond heartbeats, you can define multiple scheduled tasks for different purposes.

Task Configuration

# Multiple scheduled tasks
scheduled_tasks:
  - name: "daily-report"
    schedule: "0 8 * * *"
    enabled: true
    prompt: |
      Generate a daily summary report:
      1. Read yesterday's activity logs
      2. Summarize key events and metrics
      3. Send report to team via email/Discord
      
  - name: "backup-check"
    schedule: "0 2 * * *"
    enabled: true
    prompt: |
      Verify last night's backup:
      1. Check if backup files exist
      2. Verify file sizes are reasonable
      3. Test a sample restore if needed
      4. Report backup status
      
  - name: "api-sync"
    schedule: "0 */6 * * *"
    enabled: true
    prompt: |
      Sync data from external API:
      1. Fetch new records from API
      2. Process and validate data
      3. Store in local database
      4. Log sync results

Implementation Examples

Example 1: Website Monitoring

Check your website every 5 minutes and alert on downtime:

scheduled_tasks:
  - name: "uptime-monitor"
    schedule: "*/5 * * * *"
    enabled: true
    prompt: |
      Check website uptime:
      1. Use web_fetch to GET https://example.com
      2. If status is 200: do nothing (silent success)
      3. If status is not 200 or timeout:
         - Read previous status from /tmp/uptime-status.txt
         - If status changed from UP to DOWN:
           * Send alert: "Website DOWN: HTTP [status]"
           * Notify via configured channel
         - Write "DOWN" to /tmp/uptime-status.txt
      4. If recovery detected (was DOWN, now UP):
         - Send "Website recovered" notification
         - Write "UP" to /tmp/uptime-status.txt

Example 2: Daily Data Processing

Process CSV files dropped in a folder every morning:

scheduled_tasks:
  - name: "process-csv-files"
    schedule: "0 6 * * *"
    enabled: true
    prompt: |
      Process pending CSV files:
      1. List all .csv files in /data/incoming/
      2. For each file:
         - Read and validate contents
         - Transform data as needed
         - Import to database
         - Move processed file to /data/processed/
         - Log processing results
      3. If no files found, log "No files to process"
      4. Send summary of processed files

Example 3: Social Media Posting

Post content from a queue at optimal times:

scheduled_tasks:
  - name: "social-post-morning"
    schedule: "0 9 * * *"
    enabled: true
    prompt: |
      Post to social media:
      1. Read /data/social-queue/next-post.txt
      2. If file exists:
         - Extract post content and platform
         - Use appropriate API/tool to publish
         - Move post to /data/social-queue/posted/
         - Log publication
      3. If no posts queued, check RSS for new content
      
  - name: "social-post-afternoon"
    schedule: "0 15 * * *"
    enabled: true
    prompt: |
      Same as morning post task for afternoon slot

Running Cron with Docker

Docker containers don't have cron by default. Here are three approaches:

Option 1: Host Cron (Recommended)

Use the host system's cron to trigger container tasks:

# On the host, edit crontab: crontab -e
# Add lines to trigger OpenClaw tasks:

*/5 * * * * docker exec openclaw-agent openclaw heartbeat
0 8 * * * docker exec openclaw-agent openclaw task daily-report

Option 2: Cron in Container

Add cron to your Docker image:

# Dockerfile
FROM openclaw/base:latest

# Install cron
RUN apt-get update && apt-get install -y cron

# Add crontab
COPY crontab /etc/cron.d/openclaw
RUN chmod 0644 /etc/cron.d/openclaw

# Start cron with OpenClaw
CMD cron && openclaw start

Option 3: Ofelia Scheduler

Use Ofelia for Docker-native job scheduling:

# docker-compose.yml
version: '3'
services:
  ofelia:
    image: mcuadros/ofelia:latest
    command: daemon --config=/etc/ofelia/config.ini
    volumes:
      - ./ofelia.ini:/etc/ofelia/config.ini
      - /var/run/docker.sock:/var/run/docker.sock
    
  openclaw:
    image: openclaw/agent:latest
    container_name: openclaw-agent

# ofelia.ini
[job-exec "heartbeat"]
schedule = */5 * * * *
container = openclaw-agent
command = openclaw heartbeat

[job-exec "daily-report"]
schedule = 0 8 * * *
container = openclaw-agent
command = openclaw task daily-report

Best Practices

Scheduling Guidelines

• Spread the load: Don't schedule all tasks at the same minute
• Use appropriate intervals: Every minute is usually overkill; every 5-15 minutes is often sufficient
• Consider timezones: Cron uses system time; document your server's timezone
• Avoid midnight: Many systems are busy at 00:00; pick off-peak times

Error Handling

• Always log task results, both success and failure
• Set up alerts for critical task failures
• Use exit codes to indicate success/failure
• Implement retry logic for transient failures
• Keep a task execution history for debugging

Idempotency

Design tasks to be safe to run multiple times:

• Check if work is already done before repeating
• Use file locks or database flags to prevent duplicate processing
• Make data operations atomic where possible
• Track state between runs

Resource Management

• Limit concurrent scheduled tasks
• Set timeouts to prevent runaway processes
• Monitor memory and CPU usage
• Clean up temporary files after tasks complete

Testing Your Cron Setup

Validate Cron Expression

Test your cron syntax before deploying:

# Use online validators or command line tools
# Install croniter for Python validation:
pip install croniter

# Test expression
python3 -c "from croniter import croniter; 
print(croniter('*/5 * * * *').get_next())"

Manual Task Testing

Run your scheduled task manually before automating:

# Test the exact command that cron will run
openclaw task daily-report --dry-run

# Or run the prompt directly in an interactive session
# to verify it works as expected

Log Monitoring

Set up log tracking for your scheduled tasks:

# View recent cron logs
tail -f /var/log/cron.log

# Or in Docker:
docker logs openclaw-agent --follow | grep "scheduled"

Troubleshooting

Task Not Running

• Check syntax: Verify cron expression is valid
• Enable tasks: Confirm enabled: true is set
• Timezones: Verify system timezone matches expectations
• Service running: Ensure OpenClaw daemon is active
• Check logs: Look for parsing or execution errors

Tasks Running Too Frequently

• Double-check step values: */1 vs */5
• Verify no duplicate entries exist
• Check if multiple schedulers are running

Resource Exhaustion

• Tasks may overlap if previous run hasn't finished
• Implement file locking to prevent concurrent runs
• Increase interval or optimize task performance
• Consider breaking large tasks into smaller chunks

Summary

Cron jobs and scheduled tasks transform your OpenClaw agent from a reactive assistant into a proactive automation system. Master cron syntax, implement heartbeat patterns for monitoring, and design reliable tasks that run without human intervention.

Start with simple health checks, then build up to complex automation workflows. Always test thoroughly, handle errors gracefully, and monitor your scheduled tasks to ensure they continue running smoothly.