Managing Cron Jobs for Automation

OpenClaw's cron system allows you to schedule and automate tasks with precision. Unlike the heartbeat system that runs periodically and checks for things to do, cron jobs are scheduled for specific times or intervals, making them ideal for time-sensitive operations.

Core Concepts

Cron jobs in OpenClaw consist of three main components:

1. Schedule - When the job should run
2. Payload - What action should be taken
3. Delivery - How results should be communicated

Schedules

You can create cron jobs with different scheduling patterns:

• One-shot - Runs at a specific time using at scheduling
• Recurring interval - Runs every X milliseconds using every scheduling
• Cron expression - Uses standard cron syntax (e.g., 0 7 * * * for daily at 7 AM)

Timezones can be specified for cron expressions, with the Gateway host's local timezone used by default if none is provided.

Execution Contexts

Cron jobs can run in two different contexts:

Main session jobs enqueue a system event that processes during the next heartbeat. These are best for tasks that need access to the main session context or should appear in your primary conversation history.

Isolated jobs run in a dedicated agent session (cron:<jobId>). Each run starts fresh with no prior conversation carry-over. This is ideal for background chores that shouldn't clutter your main chat history.

Practical Examples

Creating a one-shot reminder:

cron add \
  --name "Expense Report" \
  --at "2026-02-16T18:00:00Z" \
  --session main \
  --system-event "Submit monthly expense report" \
  --wake now

Setting up a recurring morning briefing:

cron add \
  --name "Daily Brief" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Summarize inbox and calendar for today" \
  --announce \
  --channel telegram \
  --to "-1001234567890:topic:123"

Best Practices

1. Use isolated jobs for frequent or noisy tasks to keep your main session clean
2. Set appropriate timezones to ensure jobs run at the expected local time
3. Use descriptive names that make job purposes clear
4. Consider the wake mode (now vs next-heartbeat) based on urgency
5. For isolated jobs, configure delivery to send results to the appropriate channel

The cron system is particularly valuable for automation scenarios like scheduled data backups, regular system checks, periodic reporting, and timed reminders. By combining different schedule types with appropriate execution contexts, you can create sophisticated automation workflows that run reliably in the background.