Mastering OpenClaw Cron Jobs for Reliable Automation

OpenClaw's cron system is a powerful engine for scheduling automated tasks, from periodic reminders to complex operational workflows. Unlike simpler heartbeat checks, cron jobs provide precise timing, persistent storage, and robust delivery mechanisms that make them ideal for mission-critical automation.

Core Architecture

The cron subsystem runs independently within the Gateway process, storing job definitions in ~/.openclaw/cron/jobs.json. This persistence ensures schedules survive restarts and crashes, providing reliability that's essential for production automation.

Jobs have two execution contexts:

• Main session: Enqueues a system event that processes during the next heartbeat
• Isolated session: Runs in a dedicated cron:<jobId> session with fresh context

Execution Strategies

Main Session Jobs

Use main session jobs when you need access to the primary conversation history and persistent memory. These jobs enqueue a system event that triggers during the next heartbeat cycle. This approach is perfect for status checks that build on previous context.

openclaw cron add \
  --name "Daily check" \
  --cron "0 9 * * *" \
  --session main \
  --system-event "Check calendar and email" \
  --wake now

Isolated Jobs

For background operations that shouldn't pollute your main conversation, use isolated sessions. Each run gets a fresh context, preventing state leakage between executions. This is ideal for high-frequency tasks like monitoring scripts.

openclaw cron add \
  --name "System monitor" \
  --cron "*/5 * * * *" \
  --session isolated \
  --message "Check server health metrics" \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

Delivery Mechanisms

Isolated jobs support three delivery modes:

• Announce: Sends output directly to a specified channel without using the messaging API
• Webhook: POSTs results to an external endpoint (useful for CI/CD integration)
• None: Internal-only execution for silent operations

The announce delivery is particularly valuable as it bypasses the agent loop, reducing latency and avoiding potential message queuing issues.

Best Practices

Model and Thinking Overrides

Isolated jobs can specify different models and thinking levels:

openclaw cron add \
  --name "Weekly analysis" \
  --cron "0 6 * * 1" \
  --session isolated \
  --message "Analyze weekly performance metrics" \
  --model "opus" \
  --thinking high \
  --announce

This allows resource-intensive tasks to use more capable models without affecting your primary agent configuration.

Error Handling and Retry

OpenClaw applies exponential backoff for failing recurring jobs (30s, 1m, 5m, 15m, then 60m). This prevents spam during outages while ensuring recovery when systems come back online. One-shot jobs disable after completion or failure, making them safe for temporary reminders.

Timezone Management

Always specify timezones explicitly using the --tz flag. Relying on the system local timezone can lead to inconsistencies, especially when deploying across different regions.

openclaw cron add \
  --name "West Coast check" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated

By leveraging these features, you can build robust automation that handles everything from simple reminders to complex operational workflows with enterprise-grade reliability.