Mastering OpenClaw Cron Jobs: Schedule, Automate, and Scale

If you've ever wanted to automate a task, send a precise reminder, or run a daily report without lifting a finger, OpenClaw's cron system is your solution. Built directly into the Gateway, cron jobs let you schedule any action with exact timing—whether it's a one-shot alert in five minutes or a weekly deep analysis every Monday at 8 AM.

This guide walks you through the core concepts, best practices, and real-world examples so you can use cron with confidence.

What Is OpenClaw Cron?

OpenClaw cron is a persistent, robust scheduling system that runs inside the Gateway daemon. Unlike temporary timers, cron jobs are stored on disk (~/.openclaw/cron/jobs.json) and survive agent restarts, crashes, and reboots. This makes cron the go-to mechanism for any task that must run reliably on time.

Whether you're managing a single personal workflow or orchestrating a fleet of agents, cron handles:

One-shot reminders ("Notify me in 20 minutes")
Recurring background checks ("Scan inbox every hour")
Scheduled reports ("Send weekly summary every Sunday")
Isolated heavy processing ("Run Opus analysis nightly")

Core Concepts

Before diving into commands, understand the two key decisions you make when creating a cron job:

When should it run? → Define the schedule
What should it do? → Define the payload

Schedules: When to Run

Cron supports three schedule types:

at: Run once at an exact time (ISO 8601 timestamp)
every: Run repeatedly at a fixed interval (milliseconds)
cron: Use a standard 5-field cron expression with optional timezone

For example:

# One-shot: reminder in 30 minutes
--at "30m"

# Every 2 hours
--every "2h"

# Every day at 7:30 AM New York time
--cron "30 7 * * *" --tz "America/New_York"

Note: If you omit a timezone in an at timestamp, it defaults to UTC.

Payloads: What to Do

Every job must specify what happens when it runs. But more importantly, you choose where it runs:

Main session jobs: Trigger a system event in your main chat
Isolated jobs: Run in a fresh, dedicated session

Main Session Jobs

These are perfect for reminders or checks that benefit from full conversational context. They use payload.kind = "systemEvent" and are processed during the next heartbeat.

Example: "In 1 hour, check if the deployment finished."

openclaw cron add \
  --name "Deployment check" \
  --at "1h" \
  --session main \
  --system-event "Check latest CI status" \
  --wake now

Isolated Jobs

Use these for tasks that should run independently—especially noisy ones, heavy processing, or scheduled announcements. Each run starts fresh, with no memory of past runs.

Ideal for:

Daily standup summaries
Weekly analytics reports
Automated status pings

openclaw cron add \
  --name "Morning Brief" \
  --cron "0 8 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Summarize today's calendar, urgent emails, and weather" \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

The --announce flag delivers a summary directly to your specified channel—no main session involvement.

Real-World Use Cases

1. One-Shot Reminders

Need to take a break, call someone back, or check on a task?

openclaw cron add \
  --name "Pomodoro break" \
  --at "25m" \
  --session main \
  --system-event "Break time! Step away for 5 minutes." \
  --wake now \
  --delete-after-run

This creates a single-use reminder. Once delivered, it deletes itself.

2. Daily Reports with Announce

Automate your morning routine with a tailored briefing to your preferred channel:

openclaw cron add \
  --name "Daily Digest" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's digest: top emails, calendar events, weather, and priority tasks" \
  --model opus \
  --thinking high \
  --announce \
  --channel telegram \
  --to "@your_daily_digest"

Pro tip: Use --model opus for higher quality analysis, and --thinking high for deeper reasoning.

3. Weekly Deep Analysis

Reserve Opus or another high-power model for weekly reviews without disrupting your main workflow:

openclaw cron add \
  --name "Weekly Code Review" \
  --cron "0 9 * * 1" \
  --tz "America/New_York" \
  --session isolated \
  --message "Review git activity, open PRs, and code quality trends from the past week" \
  --model opus \
  --thinking high \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

4. Deliver to Telegram Topics

If you use Telegram forums, cron can post directly to specific topics:

openclaw cron add \
  --name "Nightly Summary" \
  --cron "0 22 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Summarize today's key events and pending tasks" \
  --announce \
  --channel telegram \
  --to "-1001234567890:topic:123"

Use -100...:topic:123 to route output to the correct discussion thread.

Cron vs Heartbeat: Which Should You Use?

It's easy to confuse cron with heartbeats—they both run on a schedule. Here’s the difference:

| Feature | Heartbeat | Cron | |--------|----------|------| | Timing | Approximate (e.g. ~every 30 min) | Exact (e.g. 8:00 AM sharp) | | Context | Full main session history | Fresh (isolated) or main | | Best for | Batched awareness checks | Precise or standalone tasks | | Token use | One turn per interval | One turn per job |

Use heartbeat when:

You're batching inbox, calendar, weather, and notifications
Context matters
Slight drift is acceptable

Use cron when:

Timing must be exact
You need isolation from main chat
Running a report or announcement independently
Using a different model/thinking level

In practice, use both: heartbeat for routine awareness, cron for precision tasks.

Troubleshooting Common Issues

"Nothing runs"

Confirm cron is enabled: cron.enabled in config and no OPENCLAW_SKIP_CRON env var
Ensure the Gateway is running continuously
For --cron, verify the timezone matches your host

Job runs but no message is delivered

For --announce, ensure delivery.channel and delivery.to are valid
If the isolated run already sent a message via tools, announce is skipped (to avoid duplicates)
Use delivery.bestEffort: true to prevent job failure on delivery errors

Recurring job keeps failing

OpenClaw applies exponential backoff (30s, 1m, 5m, 15m, 60m) after consecutive errors. The backoff resets after one success.

Final Thoughts

OpenClaw cron isn't just a timer—it's a full-featured automation engine with persistence, precision, and flexibility. By combining one-shot reminders, recurring jobs, and isolated workflows, you can build reliable systems that run themselves.

Start small: schedule a daily check-in. Then scale up: automate reports, enforce habits, and let your agents do the work.

For full reference, see Cron Jobs in the official docs.

Happy scheduling.