Cron vs Heartbeat

Introduction

OpenClaw offers two scheduling mechanisms: cron jobs and heartbeat. Both run on a timer, but they serve fundamentally different purposes and have different execution models. Choosing the right one for your use case avoids wasted tokens, missed events, and unnecessary complexity.

Key Concepts

• Cron Jobs: Precise, task-specific scheduled actions. Each job runs independently with its own schedule, command, and optional isolated session.
• Heartbeat: A single periodic check-in where the agent processes a checklist. All heartbeat tasks run in a single turn, batched together.
• Batching vs Precision: Heartbeat batches multiple checks into one turn (cost-efficient), while cron provides per-task precision (flexible scheduling).
• Session Context: Heartbeat runs in the main session context by default, while cron jobs can run in isolated sessions with their own context window.

Real World Context

Consider two scenarios. First, you want to check three things every 30 minutes: API health, disk space, and error logs. A single heartbeat with a three-item checklist handles this in one agent turn — three checks for the token cost of one. Second, you need to run a dependency update check every Monday at 9 AM and a database backup verification every night at midnight. These are separate tasks on different schedules — cron jobs are the right tool.

Deep Dive

Here is a side-by-side comparison of the two mechanisms:

The key tradeoff is batching efficiency vs scheduling flexibility.

With heartbeat, you define all your periodic checks in HEARTBEAT.md and they all run in a single agent turn:

markdown
# Heartbeat Checklist
- [ ] Check API health
- [ ] Verify disk space < 80%
- [ ] Scan error logs for critical entries

Three checks, one turn, one set of tokens. This is very cost-efficient for routine monitoring.

With cron, each task is an independent job with its own schedule:

bash
# These are three separate jobs, each consuming its own turn
openclaw cron add --every 30m --message "Check API health"
openclaw cron add --cron "0 9 * * MON" --message "Run dependency update check"
openclaw cron add --cron "0 0 * * *" --message "Verify nightly backup"

Each cron add command creates a separate job. The first runs every 30 minutes, the second every Monday at 9 AM, and the third at midnight daily. Each execution is its own agent turn.

When to Use Each

Use heartbeat when:

• You have multiple routine checks that should all run at the same interval
• Cost efficiency matters — batching saves tokens
• The checks are lightweight and do not need their own context

Use cron jobs when:

• Tasks need different schedules (daily, weekly, at specific times)
• A task is heavy and benefits from an isolated session
• You need precise control over individual task lifecycle (enable, disable, edit)

Use both together when:

• Heartbeat handles routine monitoring (health checks, disk space)
• Cron handles specific scheduled tasks (backups, reports, deployments)

Common Pitfalls

1. Using cron for tasks that should be heartbeat items — If you have five monitoring checks all on the same 30-minute schedule, putting them in five separate cron jobs costs five turns instead of one. Use heartbeat and batch them.
2. Overloading HEARTBEAT.md with heavy tasks — A task that takes minutes to complete blocks the entire heartbeat turn. Move heavy tasks to isolated cron jobs.
3. Forgetting that heartbeat runs in the main session — Heartbeat output goes into the main conversation context by default. If you do not want heartbeat noise in the session, set target: "none".

Best Practices

1. Audit your automation regularly — Review both heartbeat items and cron jobs quarterly. Remove tasks that are no longer relevant.
2. Use heartbeat for monitoring, cron for actions — Heartbeat checks status; cron performs operations. This mental model keeps your automation clean.
3. Combine with active hours — Both heartbeat and cron support time restrictions. Use them to avoid running automation during off-hours.

Summary

• Heartbeat batches multiple checks into one agent turn, making it cost-efficient for routine monitoring
• Cron provides per-task scheduling flexibility with independent lifecycle management
• Use heartbeat for same-interval monitoring checks and cron for tasks needing precise or varied schedules
• Heavy tasks should go in isolated cron sessions rather than bloating the heartbeat turn
• The two mechanisms complement each other — use both for comprehensive automation