Understanding Cron vs. Heartbeat in OpenClaw

When building automations with OpenClaw, you’ll encounter two primary scheduling systems: cron jobs and heartbeats. Both allow you to run periodic tasks, but they serve different purposes and work best in different scenarios. Choosing the right one ensures your automations are efficient, timely, and well-integrated with your workflow.

What Are They?

Heartbeat

The heartbeat is a periodic check-in system that runs in your main agent session at regular intervals (default: every 30 minutes). Think of it as your AI assistant glancing at its watch and asking, “Is there anything I should pay attention to right now?”

Heartbeats are ideal for batching multiple checks—like scanning your inbox, reviewing your calendar, or checking system status—into a single, context-aware operation.

Cron Jobs

Cron jobs, on the other hand, are precise, fire-and-forget tasks scheduled using traditional cron syntax or one-shot timestamps. They can run in isolated sessions, meaning they don’t interfere with your main conversation history and can even use different models or settings.

Cron is perfect when you need something to happen at an exact time, like sending a daily report at 9:00 AM sharp, or when you want to run background tasks without cluttering your main session.

When to Use Each

| Use Case | Recommended | Why | |----------------------------------------|-----------------|----------------------------------------------------------------------| | Check email every 30 minutes | Heartbeat | Batches with other checks; context-aware decisions | | Send a daily briefing at 7:00 AM ET | Cron | Requires exact timing | | Monitor upcoming calendar events | Heartbeat | Naturally fits periodic awareness checks | | Run weekly deep analysis | Cron | Standalone task; can use a more powerful model (e.g., Opus) | | Remind me in 20 minutes | Cron | One-shot with precise delay | | Background project health check | Heartbeat | Piggybacks on existing cycle; low overhead |

Heartbeat: Best for Contextual Awareness

Use heartbeats when:

You want to batch multiple checks into one agent turn.
The decision logic benefits from recent conversation context.
Timing doesn’t need to be exact—close enough is fine.
You want to reduce API calls and token usage.

How It Works

OpenClaw runs a heartbeat according to the schedule defined in your config (e.g., every 30m). On each run, it processes the instructions in HEARTBEAT.md, which might include checking emails, scanning for urgent messages, or reviewing upcoming events.

If nothing needs attention, it replies HEARTBEAT_OK and no message is delivered. If there’s something important, it surfaces the alert directly.

Example: HEARTBEAT.md

# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in

This single file powers your agent’s proactive behavior—simple, effective, and easy to maintain.

Cron: Best for Precision and Isolation

Use cron jobs when:

An action must occur at an exact time.
You want isolation from the main session (no history pollution).
You need different models or settings (e.g., high thinking with Opus).
The task is noisy or frequent and would clutter your main chat.
It’s a one-shot reminder (e.g., “remind me in 2 hours”).

Execution Modes

Cron supports two execution modes:

Main Session: Enqueues a system event that triggers during the next heartbeat. Useful for reminders that should appear in context.
Isolated Session: Runs in a clean environment (cron:<jobId>), starts fresh each time, and can announce results directly to a channel.

Example: Daily Morning Briefing (Cron)

openclaw cron add \\
  --name "Morning briefing" \\
  --cron "0 7 * * *" \\
  --tz "America/New_York" \\
  --session isolated \\
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \\
  --model opus \\
  --announce \\
  --channel whatsapp \\
  --to "+15551234567"

This job runs every day at 7:00 AM Eastern Time, uses the high-capability Opus model, and delivers a summary directly to WhatsApp—no interaction with the main session required.

Example: One-Shot Reminder

openclaw cron add \\
  --name "Meeting reminder" \\
  --at "20m" \\
  --session main \\
  --system-event "Reminder: standup meeting starts in 10 minutes." \\
  --wake now \\
  --delete-after-run

This creates a one-time reminder that fires 20 minutes from now and automatically deletes itself after execution.

Decision Flowchart

To help you choose:

Does the task need to run at an EXACT time?
  YES → Use cron
  NO  → Continue...

Does the task need isolation from main session?
  YES → Use cron (isolated)
  NO  → Continue...

Can this task be batched with other periodic checks?
  YES → Use heartbeat (add to HEARTBEAT.md)
  NO  → Use cron

Is this a one-shot reminder?
  YES → Use cron with --at
  NO  → Continue...

Does it need a different model or thinking level?
  YES → Use cron (isolated) with --model/--thinking
  NO  → Use heartbeat

Combining Both for Maximum Efficiency

The most powerful setups use both systems together:

Heartbeat handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
Cron handles precise schedules (daily reports, weekly reviews) and one-shot reminders.

This hybrid approach minimizes noise, respects timing needs, and keeps your main session clean while still being proactive.

Final Tips

Keep HEARTBEAT.md lean—only include essential checks to minimize token usage.
Use isolated cron jobs for high-frequency or high-cost tasks to avoid polluting your main history.
Prefer cron over multiple heartbeats when exact timing matters.
Test new cron jobs with openclaw cron run <job-id> before relying on them.

By understanding the strengths of each system, you can design automations that feel seamless, intelligent, and perfectly timed.