Using Cron Jobs for Automated Tasks in OpenClaw

Cron jobs are a powerful feature in OpenClaw that allow you to schedule and automate recurring tasks within your AI agent workflows. Whether you need to send daily summaries, check system status, or trigger complex agent chains, cron provides a reliable mechanism for time-based automation.

Understanding Cron vs Heartbeat

Before diving into implementation, it's important to understand the difference between cron jobs and heartbeat polling:

• Cron jobs are ideal for tasks that need to happen at specific times or intervals (e.g., "every morning at 9:00 AM" or "every 30 minutes")
• Heartbeat polling is better for batched checks that can drift slightly in timing and benefit from conversational context

Use cron when exact timing matters, or when you want isolation from your main session history.

Creating Your First Cron Job

You can create cron jobs through the CLI, API, or directly via tool calls. Here's a basic example using the CLI to set up a daily summary:

openclaw cron add \
  --name "Daily Summary" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Summarize yesterday's activity and key metrics." \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

This job will run every day at 7:00 AM Eastern time, generate a summary in an isolated session, and deliver it directly to the specified WhatsApp number.

Job Execution Modes

Cron supports two execution modes:

Main session jobs enqueue a system event that runs during the next heartbeat. These are useful when you need access to your main session context.

Isolated jobs run dedicated agent turns with fresh context. These are ideal for background tasks that shouldn't clutter your main conversation history.

Scheduling Options

Cron supports three schedule types:

• at: One-shot execution at an absolute timestamp
• every: Recurring jobs at fixed intervals (in milliseconds)
• cron: Standard 5-field cron expressions with optional timezone specification

For recurring jobs, you can use cron expressions like 0 7 * * * (daily at 7:00 AM) or */30 * * * * (every 30 minutes).

Delivery and Announcements

Isolated cron jobs can deliver output directly to messaging channels without going through your main agent. This "announce" delivery mode suppresses duplicates and ensures reliable delivery:

{
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "channel:C1234567890",
    "bestEffort": true
  }
}

Advanced Configuration

You can override the model and thinking level for isolated jobs:

openclaw cron add \
  --name "Deep Analysis" \
  --cron "0 6 * * 1" \
  --tz "America/New_York" \
  --session isolated \
  --message "Perform weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

This runs a high-thinking Opus model every Monday morning for in-depth analysis.

Monitoring and Troubleshooting

Check your job status and history:

# List all jobs
openclaw cron list

# View run history for a specific job
openclaw cron runs --id <jobId> --limit 50

# Manually trigger a job
openclaw cron run <jobId>

Common issues include timezone mismatches and delivery target errors. Always test one-shot jobs before deploying recurring ones.

Best Practices

1. Start with one-shot jobs to validate your workflow
2. Use isolated sessions for noisy or frequent tasks
3. Implement delivery.bestEffort for non-critical announcements
4. Monitor run history to catch failures early
5. Document your cron jobs in version control

Cron jobs transform your AI agents from reactive helpers into proactive operations managers. By automating routine tasks, you free up mental space for higher-value work while ensuring critical operations never get overlooked.