Mastering OpenClaw Cron Jobs: Schedule, Automate, and Scale

OpenClaw’s cron system isn’t just a scheduler—it’s the engine that powers proactive automation across your AI agents. Whether you’re running daily status updates, time-based reminders, or isolated background tasks, cron gives you precise control over when and how your agents act. Let’s walk through core concepts, syntax, and real-world use cases so you can turn repetitive tasks into silent, reliable workflows.

How Cron Works: The Big Picture

At its core, OpenClaw cron is a persistent, event-driven scheduler running inside the Gateway process. Unlike heartbeat-driven checks—which wait for a periodic poll—cron jobs fire on demand, based on a defined schedule. This makes them ideal for time-sensitive actions like morning briefings, reminder pings, or delayed follow-ups.

When a job triggers, it can either:

• Run in your main session as a system event, funneling through the next heartbeat
• Run in isolation as a dedicated agent turn, keeping noise out of your chat history

This split is crucial: use main sessions when you want context carryover (e.g., summarizing the day with full memory access), and isolated sessions when you want cleaner output and independent processing (e.g., sending weekly reports).

Step 1: Define When It Runs

Cron supports three scheduling modes:

One-Shot: at

Perfect for reminders or delayed actions.

--at "2026-02-16T08:00:00Z"

Or using relative time:

--at "10m"  # 10 minutes from now

Timestamps without a timezone are treated as UTC. Add --tz "America/Los_Angeles" for local time scheduling.

Recurring: cron

The classic syntax for daily, weekly, monthly tasks.

--cron "0 7 * * *"  # 7:00 AM every day

Use crontab.guru to build and test expressions. Don’t forget the --tz flag if your host is in a different zone.

Interval: every

For simple, fixed loops—say, checking a health endpoint every 5 minutes.

--every-ms 300000  # 5 minutes in milliseconds

Step 2: Choose Execution Mode

Main Session Jobs (System Events)

Use these to inject context into your next heartbeat. They’re lightweight and reuse your existing session.

openclaw cron add \
  --name "Calendar Check" \
  --at "10m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

The --wake now flag forces an immediate heartbeat. Without it, the event waits for the next scheduled check.

Isolated Jobs (Agent Turns)

Better for noisy or stateless tasks. Each run is a clean slate—no shared history, no risk of context pollution.

openclaw cron add \
  --name "Daily Brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize inbox + calendar for today." \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

With --announce, the result is sent directly to WhatsApp and summarized in your main session. No extra messaging code needed.

💡 Pro tip: Use isolated jobs with delivery.bestEffort = true for non-critical pings. This prevents a failed notification from blocking the entire job.

Delivery & Output Control

Isolated jobs support two delivery modes:

• announce: Sends output directly to a channel (via the provider adapter) and posts a summary to main
• none: Internal-only—useful for silent background tasks

You can override model and thinking level on a per-job basis (e.g., --model opus --thinking high), which is perfect for deep weekly analysis without slowing down your default agent.

Real-World Use Cases

Reminder Automation

Schedule a follow-up after a support reply:

openclaw cron add \
  --at "24h" \
  --session main \
  --system-event "Follow up with user about resolved ticket" \
  --wake now

Multi-Agent Workflows

In multi-agent setups, bind jobs to specific agents using --agent ops or --agent marketing. This ensures the right persona handles the right task.

Silent Health Checks

Run isolated jobs with --delivery none to poll internal APIs, check disk space, or verify service uptime—no chat clutter.

Debugging Tips

• Use openclaw cron list to verify jobs exist
• Run openclaw cron runs --id <jobId> to inspect execution history
• If a job doesn’t fire, check cron.enabled in config and ensure the Gateway is running
• One-shot jobs auto-delete by default. Use --delete-after-run false to keep them

Conclusion

Cron turns passive agents into proactive teammates. Once you map out recurring tasks—from morning standups to monthly reporting—you’ll wonder how you ever managed without it.

Start small: one daily summary, one delayed reminder. Then scale. With cron, your AI doesn’t just respond—it anticipates.