Exploring OpenClaw's Heartbeat System

OpenClaw's heartbeat system is a powerful mechanism for creating periodic awareness and proactive assistance without overwhelming your chat interface. While cron jobs handle exact timing and isolated execution, the heartbeat is all about context-aware, intelligent check-ins that respect your attention.

How Heartbeat Works

At regular intervals — configurable down to the minute — OpenClaw triggers a heartbeat cycle. This isn't just a timer going off; it's a full agent turn that runs in your main session with access to all your recent context. The agent reviews what has happened, checks for pending tasks, and decides whether anything requires your attention.

The default interval is 30 minutes, though this can be adjusted up or down based on your needs and tolerance for notifications. Importantly, if there's nothing urgent, the system responds with HEARTBEAT_OK — a signal that gets suppressed, meaning you won't see it. Only when there's something important does the agent break through with an actual message.

This design prevents notification fatigue while ensuring you're kept in the loop about critical updates.

Heartbeat vs. Cron

One of the first questions developers ask is: "When should I use heartbeat versus cron?"

The answer lies in intent and precision:

• Use heartbeat when you want batched, context-aware monitoring. Checking your inbox, calendar, and notifications together every 30 minutes? That's a heartbeat task.

• Use cron when you need exact timing or isolation. Sending a daily report at precisely 9:00 AM every morning? That's a cron job.

Heartbeat is your periodic check-in; cron is your precision clockwork.

Configuring Your Heartbeat

You can customize heartbeat behavior through OpenClaw's config. Key settings include:

• every: How often the heartbeat runs (e.g., 30m, 1h)
• target: Where to deliver alerts (last, whatsapp, slack, etc.)
• activeHours: Restrict heartbeats to business hours only
• prompt: Customize what the agent looks for during each check-in

For example, to limit heartbeats to 9 AM to 10 PM Eastern time:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "activeHours": {
          "start": "09:00",
          "end": "22:00",
          "timezone": "America/New_York"
        }
      }
    }
  }
}

The Power of HEARTBEAT.md

One of the most useful features is the optional HEARTBEAT.md file in your workspace. If this file exists, the agent reads it during every heartbeat cycle and follows its instructions strictly.

This allows you to create a custom checklist of things you want monitored. For instance:

# Heartbeat checklist

- Scan inbox for urgent messages
- Check calendar for events in next 2 hours
- Light check-in if quiet for 8+ hours

Keep this file small and focused — it becomes part of your prompt — and you'll have a powerful, personalized monitoring system.

Manual Wake and Debugging

Sometimes you want to trigger a heartbeat immediately. You can do this with:

openclaw system event --text "Check for urgent follow-ups" --mode now

This enqueues a system event and forces an immediate heartbeat run, bypassing the usual schedule.

For troubleshooting, use openclaw cron status and openclaw system heartbeat last to verify everything is running as expected.

Final Thoughts

The heartbeat system embodies OpenClaw's philosophy: intelligent assistance that respects your attention. It's not about flooding you with data, but about delivering the right information at the right time — or saying nothing at all when silence is the best response.

By combining heartbeat for awareness and cron for precision, you create a balanced automation ecosystem that works for you, not against you.