Exploring OpenClaw's Heartbeat System

This article dives into OpenClaw's heartbeat system, a powerful automation feature that enables periodic awareness and proactive checking without overwhelming the user.

What is the Heartbeat System?

The heartbeat system in OpenClaw is designed to periodically run agent turns in the main session, allowing the AI to surface important information or actions that require attention. Unlike traditional cron jobs that run at exact scheduled times, heartbeats are more about maintaining regular awareness and can be configured to batch multiple checks together efficiently.

Heartbeats run on a regular interval (default is every 30 minutes) and are particularly useful for tasks like checking emails, reviewing calendars, monitoring notifications, and performing light check-ins during the day. The system is intelligent—when there's nothing urgent, it simply replies with HEARTBEAT_OK and no message is delivered to the user, effectively reducing noise.

Heartbeat vs Cron Jobs: When to Use Each

Choosing between heartbeats and cron jobs depends on your specific needs:

Use Heartbeats When:

• You need to batch multiple periodic checks (inbox, calendar, weather, notifications)
• Context-aware decisions are required (the agent has full session context)
• You want to reduce API calls by combining checks
• Conversational continuity is beneficial
• Timing can drift slightly (±5 minutes is acceptable)

Use Cron Jobs When:

• Exact timing is critical (e.g., "send report at 9:00 AM sharp")
• You need isolation from the main session context
• The task requires a different model or thinking level
• One-shot reminders are needed (e.g., "remind me in 20 minutes")
• You want the task to run independently of the agent's activity

A best practice is to use both systems together: heartbeats for routine monitoring and cron jobs for precise scheduling. This combination creates an efficient automation setup that balances reliability with flexibility.

Configuring Heartbeats

Heartbeats are configured through OpenClaw's configuration system. Here's a basic example:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "activeHours": { "start": "08:00", "end": "22:00" }
      }
    }
  }
}

Key configuration options include:

• every: The interval between heartbeat runs (e.g., "30m", "1h")
• target: Where alerts should be delivered ("last" for last used channel)
• activeHours: Restrict heartbeats to specific hours of the day
• includeReasoning: Optional transparency for debugging

The HEARTBEAT.md Checklist

You can create a HEARTBEAT.md file in your workspace to provide a checklist for the heartbeat system. This file acts as your personalized monitoring guide. For example:

# 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

The agent will read this checklist during each heartbeat and handle all items in one turn, making your monitoring system both comprehensive and efficient.

Practical Implementation

To implement an effective heartbeat system:

1. Start with the default 30-minute interval
2. Create a HEARTBEAT.md file with your priority checks
3. Consider active hours to respect sleep time
4. Use cron jobs for time-critical tasks
5. Monitor costs by keeping the heartbeat checklist concise

The heartbeat system exemplifies OpenClaw's philosophy of being genuinely helpful without being performatively helpful—checking in when it matters, but staying quiet when everything is under control.