Most AI assistants wait for you to come to them. You remember to check email, you think to ask about the weather, you have to remember to follow up on that deployment. OpenClaw's heartbeat system flips this model — your AI proactively checks in on things while you work.

This guide explains how heartbeats work, how to configure them, and the patterns that make them genuinely useful rather than annoying notification spam.

What Is the Heartbeat System?

Heartbeats enable proactive AI behavior — your assistant monitors things and speaks up when something needs attention

A heartbeat is a periodic poll that asks your AI: "Is there anything that needs attention right now?" If there is, the AI reaches out. If not, it stays quiet.

The default heartbeat prompt is:

"Check HEARTBEAT.md for your checklist. If nothing needs attention, reply HEARTBEAT_OK."

The magic is in that "if nothing needs attention" clause. Unlike a chatbot that responds to every ping with something, OpenClaw's heartbeat system is designed to be smart about when to speak up. A good heartbeat fires 2-4 times a day and produces meaningful output maybe once or twice a week — not every hour.

OpenClaw distinguishes heartbeats from cron jobs:

Step 1: Create Your HEARTBEAT.md

HEARTBEAT.md is the instruction file your AI reads during every heartbeat poll

The heartbeat system reads from HEARTBEAT.md in your workspace. This file defines what to check and under what conditions to notify you.

Create it at ~/.openclaw/workspace/HEARTBEAT.md:

# Heartbeat Checklist

## Checks to Rotate Through

### Email (check 2-3x per day)
- Scan inbox for urgent unread messages
- Flag anything marked urgent or from known important senders
- Skip newsletters, notifications, automated emails

### Calendar (check morning + midday)
- Any events starting in the next 2 hours?
- Prep reminders for meetings with prep work needed

### System Health (check 1x per day)
- Disk usage on the server (warn if >80%)
- Any failed cron jobs in the last 24h?
- Any errors in /var/log/app/error.log?

## When to Notify

DO notify when:
- Urgent email arrives from a known person
- Calendar event starts in < 2 hours
- Disk usage > 80%
- 3+ errors in error.log in the last hour

DO NOT notify when:
- It's between 23:00 and 08:00 UTC
- Nothing has changed since last check
- It's a newsletter, notification, or automated email

The file is plain text — write it in natural language. Your AI reads and interprets it, not a parser.

Step 2: Configure Heartbeat Frequency

Heartbeat frequency is configured in OpenClaw's settings — start conservative and adjust based on usefulness

Heartbeat frequency is set in your OpenClaw configuration. A sensible default is every 30 minutes during working hours. Access your OpenClaw settings:

openclaw config --edit

Look for the heartbeat interval setting. If you're using the Discord integration, heartbeats are delivered to your configured Discord channel. For Telegram, they go to your bot chat.

Start with less frequency. It's tempting to set heartbeats every 5 minutes, but frequent quiet pings train you to ignore them — and frequent notifications become noise. Start at 30-60 minutes and tighten only if you're missing important events.

Respect quiet hours. Add this to HEARTBEAT.md: "Do not send notifications between 23:00 and 08:00 UTC unless marked urgent." Your AI will honor this. The goal is to be a helpful colleague, not an always-on alarm.

Step 3: Batch Multiple Checks Together

Batching multiple checks into one heartbeat reduces API calls and produces coherent summaries

One of heartbeat's biggest advantages over individual cron jobs is batching. Instead of three separate jobs checking email, calendar, and system health at different times, one heartbeat check can do all three in a single API call and produce a coherent summary.

A batched heartbeat response looks like:

📧 Email: 2 unread from Sarah about Q2 planning — looks like she needs 
   a decision on the vendor choice by EOD.

📅 Calendar: Meeting in 90 minutes (3 PM — Product sync). You have prep 
   notes from last week's sync in /workspace/meeting-notes/.

💻 System: All clear. Disk at 67%, no errors in the last 24h.

That's three checks, delivered in one coherent message, taking 10 seconds to read. Compare that to three separate bots pinging you at different times with disconnected updates.

To encourage batching in your HEARTBEAT.md, add:

Always batch all checks into a single response. If nothing needs 
attention across all checks, reply only with HEARTBEAT_OK.

Step 4: Track State Between Heartbeats

State tracking prevents the AI from notifying you about the same thing twice

Without state tracking, a heartbeat might notify you about the same email five times across five consecutive checks. State tracking lets the AI remember what it's already reported.

Add state tracking instructions to HEARTBEAT.md:

## State Tracking

Track last-checked state in: /workspace/memory/heartbeat-state.json

Format:
{
  "lastChecks": {
    "email": <unix timestamp>,
    "calendar": <unix timestamp>,
    "system": <unix timestamp>
  },
  "alreadyReported": {
    "emails": ["<email-id-1>", "<email-id-2>"],
    "events": ["<event-id-1>"]
  }
}

Only report emails/events that aren't in alreadyReported.
Update the file after each check.

Your AI will read and update this file on each heartbeat, ensuring it never doubles up on notifications. If the state file doesn't exist yet, it will create it on the first heartbeat.

Step 5: Set Smart Notification Thresholds

Good thresholds mean you hear about things that matter, not things that can wait

The most important heartbeat configuration is the "when to bother me" threshold. Too sensitive and you get noise; too conservative and you miss things that matter.

Some patterns that work well in practice:

Email urgency scoring:

Notify for emails if:
- Subject contains: urgent, asap, deadline, broken, down, error
- From: [list of important senders]
- Reply-needed within 4 hours based on content

Skip notification for:
- Marketing, newsletters, automated notifications
- Anything from noreply@ addresses
- Threads where you already replied recently

Calendar thresholds:

Notify for upcoming events if:
- Event starts in < 2 hours AND has no prior notification sent
- Event has prep work needed (prep notes exist in /workspace/)
- Event is with someone you haven't met before

Skip notification for:
- All-day events
- Events you created yourself (you know about them)
- Recurring events unless there's a change

System health:

Notify for system issues if:
- Disk usage > 80% (warn) or > 90% (urgent)
- 5+ errors in /var/log/app/error.log in last 30 minutes
- Any failed systemd services that were running yesterday

Check daily, not every heartbeat

The key insight: heartbeats should surface exceptions, not status. "Everything is fine" shouldn't produce a notification.

Heartbeat vs Cron: When to Use Each

Choosing between heartbeat and cron depends on timing precision and task isolation needs

Now that you understand heartbeats, you'll face a recurring question: should this be a heartbeat check or a cron job?

Use heartbeat when:

• Multiple checks can batch together naturally
• Slight timing flexibility is fine (checking email at 2:30 vs 2:00 doesn't matter)
• You want conversational context (the AI knows recent chat history)
• You're monitoring things, not running tasks

Use cron when:

• Exact timing matters ("Run at 9 AM sharp every Monday")
• The task is self-contained and doesn't need conversation context
• You want a different model than your main session
• Output should go directly to a channel without your main session involvement

In practice: most monitoring goes in HEARTBEAT.md, most autonomous tasks become cron jobs. See the OpenClaw cron automation guide for the cron side of this equation.

Conclusion

A well-tuned heartbeat system makes your AI assistant feel genuinely proactive — aware of your world, not just waiting for input

The heartbeat system is what transforms OpenClaw from a powerful chatbot into something that feels like a genuine AI assistant. It watches things while you work, speaks up when needed, and respects your focus when there's nothing to report.

The setup takes 15 minutes: create HEARTBEAT.md with your check list, configure your thresholds, set up state tracking, and tune the frequency. After a week, you'll have an assistant that surfaces important things you would have missed and stays quiet the rest of the time.

For more on building proactive AI workflows, see the OpenClaw AI employee setup guide and the build a 24/7 AI assistant guide.

Frequently Asked Questions

What's the minimum heartbeat interval? Technically any interval, but practically, every 15 minutes is usually the lower useful bound. Below that, you're paying for frequent API calls that rarely produce actionable output. Start at 30 minutes.

Can heartbeats trigger actions, not just notifications? Yes. Instead of just notifying, your heartbeat can instruct the AI to take action: "If disk usage > 80%, run docker system prune -f to free space." Use this carefully — autonomous actions need good guardrails.

Will heartbeats interfere with my main conversation? Heartbeats run in a separate context from your main session. They don't interrupt an ongoing conversation. Notifications are delivered to your configured channel (Discord, Telegram, etc.) alongside normal messages.

How do I temporarily pause heartbeats? Update HEARTBEAT.md to add a pause instruction: "PAUSED UNTIL 2026-02-20 — skip all checks." Your AI will honor this and resume automatically after the date.