OpenClaw Heartbeat Explained

Who is active? Who is passive? This is the first question in AI agent design.

The vast majority of today's AI agents are passive. You don't talk, they don't move. You go to a meeting, they sit there idle. Ten urgent emails flood your inbox, they see none. A calendar event starts in five minutes, they say nothing. A background task finished an hour ago, they keep quiet, waiting for you to remember to ask.

This kind of agent is, at bottom, a tool. You pick it up, it's useful. You put it down, it's dead.

OpenClaw's Heartbeat exists to fix this.

1. What Heartbeat Is

Heartbeat is an alarm clock. It rings every 30 minutes. When it rings, the agent wakes. When it wakes, it runs through a checklist you wrote in advance, item by item. Something found, it reports. Nothing found, it replies HEARTBEAT_OK, the system swallows the message, and you receive nothing.

That's it.

Five steps:

1. System timer fires, triggers one round of conversation
2. Agent reads HEARTBEAT.md from the workspace root. This is your checklist
3. Agent executes the checks, item by item
4. Nothing to report: replies HEARTBEAT_OK, system handles it silently, you are not disturbed
5. Something to report: agent sends the message to your channel of choice. WhatsApp, Telegram, Slack, whatever you configured

The most important design decision here: the agent is silent by default. It only opens its mouth when there is actually something to say. No notification bombardment.

The Checklist: HEARTBEAT.md

This file sits in your workspace root. You write it, the agent checks it.

# Heartbeat checklist

- Scan inbox for urgent emails
- Check calendar for meetings in the next 2 hours
- If I've been idle 8+ hours, ask if I need anything

Keep it short. This file gets injected into the prompt every heartbeat cycle. Write too much and you're burning tokens for nothing.

If you authorize it, the agent can also edit this file itself, adding new items it discovers are worth monitoring.

2. Why Heartbeat Needs to Exist

The reasoning is not complicated.

Without Heartbeat, you check your own inbox. You watch your own calendar. You track your own task queue. If you want the agent to watch these things for you, you wire up a separate timer for each one. One for email. One for the calendar. One for the task queue. Things pile up, and soon you're spending more time maintaining timers than doing actual work.

And there is a fundamental blind spot: anything that happens between two checks is invisible. To you and to the agent.

Heartbeat's solution: one alarm clock, one checklist, one round of conversation, all checks bundled together. Inbox checked. Calendar checked. Task progress checked. If you've been quiet for hours, it asks. One heartbeat, everything covered.

This changes what the agent is. From a hammer you pick up, to a sentry standing watch.

3. The Money Problem

Heartbeat is good, but every beat is a full agent conversation, and conversations cost tokens. Run it carelessly and you burn over four hundred dollars a month on nothing.

Where does the money go? Into conversation history.

Under default settings, heartbeat runs in the agent's main session. The main session carries the full conversation history. If you've been chatting with your agent all day and accumulated a hundred thousand tokens of context, every heartbeat re-sends that hundred thousand tokens. 48 heartbeats a day. 48 redundant transmissions. That is the root of the waste.

How to fix it?

First cut: Isolate the session

Set isolatedSession: true. Each heartbeat gets a clean new session with zero history. Input tokens drop from a hundred thousand to two or three thousand. One parameter, 95%+ of the cost gone. This is the deepest cut.

Second cut: Strip the context

When OpenClaw starts, it stuffs a pile of workspace files into the session as bootstrap context. Config files, documentation, miscellaneous junk. Heartbeat patrol doesn't need any of it. Set lightContext: true. Keep only HEARTBEAT.md. Throw out the rest.

Third cut: Use a cheaper model

Patrol duty doesn't need the smartest brain. "Any urgent emails?" is not a task that requires frontier intelligence. Set model: "ollama/llama3.2:1b". Cost drops to zero.

Fourth cut: Empty file skip

If HEARTBEAT.md contains nothing but a title and blank lines, OpenClaw doesn't even make the API call. Skipped entirely.

The numbers

Using Claude Sonnet 4.6 ($3/M input tokens, $15/M output tokens), 30-minute intervals, 48 heartbeats per day:

Unoptimized: $434 a month. Two parameters: $12.60. Add working-hours restriction: under $7. A 60x difference.

That entire 60x gap comes from one place: whether or not you cut the redundant re-sending of conversation history.

4. The Difference Between Heartbeat and Cron

OpenClaw has another timed mechanism called Cron. Both run on schedules. Easy to confuse. But their natures are entirely different.

Heartbeat is a patrol. Wake up at intervals, walk the checklist, report if something's wrong, go back to sleep if not. Timing doesn't need to be precise. A few minutes of drift is fine. The point is bundling multiple checks into one round.

Cron is an order. Do this thing at this time, not a second late. Supports standard cron expressions. Can assign different models per task. Can run in isolated sessions. Can set one-shot reminders.

When to use which?

The decision path is simple:

Need exact timing? Cron. Need session isolation or a different model? Cron. Can it merge with other periodic checks? Heartbeat. One-shot reminder? Cron --at. None of these apply? Default to Heartbeat.

Best practice is to use both. Heartbeat handles the daily patrol, merging small checks into one round. Cron handles scheduled tasks and heavy independent jobs. Each covers its own ground. No interference.

5. Practical Configurations

As a personal assistant

Write a HEARTBEAT.md to watch over your daily essentials:

# Heartbeat checklist
- Scan inbox for urgent emails
- Check calendar for meetings in the next 2 hours
- If idle 8+ hours, check in with me

Set target: "last" to deliver messages to whichever channel you used most recently.

As ops monitoring

Spin up a dedicated ops agent. Check system health every hour:

{
  id: "ops",
  heartbeat: {
    every: "1h",
    target: "slack",
    prompt: "Check server health metrics. If CPU > 80% or disk > 90%, alert immediately."
  }
}

As a background sentry

No messages to you. Internal record-keeping only:

heartbeat: {
  every: "30m",
  target: "none",
  isolatedSession: true,
  lightContext: true
}

Wakes up. Checks things. Writes internal notes if needed. Goes back to sleep. Zero notifications. Near-zero cost.

Working hours only

No 3 AM wake-ups:

heartbeat: {
  every: "30m",
  target: "whatsapp",
  to: "+15551234567",
  activeHours: { start: "09:00", end: "22:00" }
}

Manual trigger, no waiting

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

Full configuration: Heartbeat + Cron together

HEARTBEAT.md (runs every 30 minutes):

# Heartbeat checklist
- Scan inbox for urgent emails
- Check calendar for events in the next 2 hours
- Review task progress
- If idle 8+ hours, say hello

Cron tasks (precision-timed):

# Daily morning briefing at 7 AM
openclaw cron add --name "Morning brief" --cron "0 7 * * *" \
  --session isolated --message "..." --announce

# Weekly project review, Monday 9 AM, stronger model
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" \
  --session isolated --message "..." --model opus

# One-shot reminder, 2 hours from now
openclaw cron add --name "Call back" --at "2h" \
  --session main --system-event "Call back the client" --wake now

6. Summary

Heartbeat, in one sentence: give the agent an alarm clock so it stops waiting for orders and starts standing watch.

The design is restrained. Silent when there's nothing. Vocal only when it matters. No notification bombing.

Cost is controllable. Two parameters cut 95% of the expense. A local model makes it free.

Division of labor with Cron is clear. Patrol goes to Heartbeat. Scheduled tasks go to Cron. Each covers its own ground.

An agent goes from tool to sentry. All it takes is this alarm clock.

---

References:

• Heartbeat Documentation
• Cron vs Heartbeat
• Session Management