Understanding Cron vs Heartbeat in OpenClaw

When building automated workflows in OpenClaw, two key mechanisms stand out: cron jobs and heartbeat. Both enable periodic task execution, but they serve different purposes and excel in different scenarios. Choosing the right one ensures your automation is reliable, efficient, and context-aware.

This guide breaks down when to use each, how they work under the hood, and how to combine them for maximum effectiveness.

The Core Difference

At a high level:

• Cron jobs run at exact times and can operate in isolation, making them ideal for precise schedules and standalone tasks.
• Heartbeat runs periodically (default: every 30 minutes) within the main session, making it ideal for batched, context-aware checks.

Understanding this distinction is crucial for designing robust automation.

Heartbeat: Context-Aware Periodic Checks

Heartbeat is designed for the agent to regularly check in with its environment and surface anything important. It runs in the main session, giving it full access to conversation history, memory, and current context.

When to Use Heartbeat

• ✅ Checking email for urgent messages
• ✅ Reviewing your calendar for upcoming events
• ✅ Performing lightweight health checks on running tasks
• ✅ Sending an occasional check-in if no interaction has occurred in hours

Heartbeat shines when multiple checks can be batched together efficiently. Instead of five separate cron jobs polling different systems, one heartbeat run can handle inbox, calendar, notifications, and weather in a single turn—reducing API calls and token usage.

How It Works

The agent reads HEARTBEAT.md (if it exists) and follows its instructions strictly. If nothing needs attention, it replies with HEARTBEAT_OK, which is suppressed unless configured otherwise.

You can customize the behavior via config:

{