The Complete Guide to heartbeat.md for OpenClaw — What the Top Agents Do

If you're using OpenClaw, you've probably noticed something: most AI assistants wait for you to ask something. OpenClaw doesn't have to. Every 30 minutes (by default), your agent wakes up, checks its workspace, and decides if there's something you need to know.

That's the heartbeat. And the file that controls it? That's HEARTBEAT.md.

This is the guide I wish I had when we started building our agent stack. Everything you need to know about heartbeat.md in one place.

What heartbeat.md Actually Does

The heartbeat is OpenClaw's way of making your agent proactive instead of reactive. Here's how it works:

Every 30 minutes (configurable), OpenClaw wakes your agent
It loads your workspace context — including HEARTBEAT.md if it exists
The agent runs through its checklist and decides: anything needs attention?
If yes → it messages you. If no → it replies HEARTBEAT_OK and goes back to sleep

The default prompt is broad: "Read HEARTBEAT.md if it exists. Follow it strictly. Do not infer or repeat old tasks. If nothing needs attention, reply HEARTBEAT_OK."

But you can customize this. And that's where the magic happens.

The Response Contract

This is crucial and most people get it wrong:

If nothing needs attention → reply with exactly HEARTBEAT_OK (at the start or end of message)
If there IS something → do NOT include HEARTBEAT_OK. Just send the alert.

OpenClaw treats HEARTBEAT_OK as an ack and drops the message if it's under 300 characters. If you include HEARTBEAT_OK in an alert, your message gets silenced.

What the Top Agents Do

We studied the best OpenClaw agents in production to see how they use heartbeat.md. Here's what works:

Felix (Nat Eliason) — The Revenue-Generating Agent

Felix is famous: $14,718 in 2.5 weeks, running his own business. His heartbeat focuses on:

Sales monitoring — checking for new purchases, Stripe events
Customer support — monitoring for new emails or messages
Content performance — checking engagement on his posts
Pipeline health — verifying the system is running

Felix's heartbeat isn't a checklist of tasks — it's a monitoring dashboard. He's looking for signals that need a response.

Anti Hunter — The Security Agent

Anti Hunter uses heartbeat for:

Threat detection — scanning for security vulnerabilities
Access audits — checking who has access to what
Compliance monitoring — verifying configurations haven't drifted

His heartbeat is strict: only alert on confirmed issues. No noise.

The Unwind AI Team (Dwight, Kelly, Rachel, Pam)

Shubham's team runs six agents, each with their own heartbeat:

Dwight (Research) — runs 3x daily, checks X/HN/GitHub for trending AI news
Kelly (Twitter) — reads Dwight's intel, crafts tweets, checks engagement
Rachel (LinkedIn) — same intel, different platform, different voice
Pam (Newsletter) — compiles intel into a digest

The key insight: each agent has ONE job, and the heartbeat checks that one job.

Our Basir Setup

Here's what we use:

# HEARTBEAT.md

Checklist for heartbeat runs (every 10 minutes via OpenClaw).

## Rules
- Only report items that are truly new or changed.
- Do not invent tasks from old chat context.
- Heartbeat strict mode: return exactly HEARTBEAT_OK unless there is an active, newly detected alert.

## 1. Coding session monitoring (only when sessions are active)

Check for active ralphy/coding tmux sessions:
- If sessions exist: check for recent commits and output
- If no progress for 30+ min: investigate and potentially restart
- If session ended: report results

## 2. Editorial pipeline health (quick glance)

Only flag if something is stuck:
- Check editorial queue for tasks stuck >24h

## 3. Cron job failures

Only report if daily processes haven't run.

Best Practices (What Works)

After studying these agents, here are the patterns that actually work:

1. Keep It Narrow

The #1 mistake: heartbeat.md that's too broad. "Check everything and let me know if anything is up."

That's not helpful — it's noise. Your agent will either spam you or learn to ignore everything.

Instead: Be specific. "Check if the Stripe webhook fired" or "Verify the build pipeline ran successfully."

2. Check State, Not Progress

Don't ask "how's the project going?" That's a conversation, not a heartbeat.

Ask: "Did the cron job run? Yes/no." "Are there new commits since last check? Yes/no."

State checks are reliable. Progress assessments are subjective.

3. Use Decision Trees

Don't leave room for interpretation:

| Condition | Action |
|-----------|--------|
| Session alive + recent output | HEARTBEAT_OK |
| Session alive + no progress 30+ min | Alert me |
| Session ended | Report results |

The agent shouldn't be deciding what matters. You should have already decided, and the heartbeat just executes the decision.

4. Only Alert on True Changes

The heartbeat should detect new problems, not report ongoing ones:

❌ "The build is failing" (ongoing)
✅ "The build started failing in the last 30 minutes" (new)

This requires tracking state between heartbeats. Store what you checked last, compare to now.

5. Separate Monitoring from Action

The heartbeat's job is to notice. Not to fix.

If something's wrong → alert the human. Let the human decide whether to fix it now, later, or never.

6. Respect Active Hours

Configure heartbeat to respect your timezone. You don't want alerts at 3am.

"heartbeat": {
  "activeHours": {
    "start": "08:00",
    "end": "22:00"
  }
}

Common Mistakes

Mistake #1: No heartbeat.md at all

Without it, your agent uses the default prompt which is too vague to be useful.

Mistake #2: Too many checks

Heartbeat runs every 30 minutes (or 10, or 5). If you're checking 10 things each time, that's 480 checks per day. Something will always be "wrong."

Fix: Check fewer things, more strategically.

Mistake #3: Alerting on everything

If your heartbeat messages you every time something is in a "warning" state, you'll tune it out.

Fix: Only alert on new issues. Use HEARTBEAT_OK as the default.

Mistake #4: Not using HEARTBEAT_OK

If your heartbeat runs but never says HEARTBEAT_OK, you're getting spammed.

Fix: HEARTBEAT_OK should be the 90% case. Alerts should be rare.

The Ideal Heartbeat Ratio

Here's what you're aiming for:

90% of heartbeats → HEARTBEAT_OK (nothing to report)
9% of heartbeats → informational updates (not urgent)
1% of heartbeats → actual alerts (needs attention now)

If you're inverted — getting more alerts than OKs — your heartbeat is broken. Fix it.

Advanced: Custom Prompts

You can override the default prompt entirely:

"agents": {
  "defaults": {
    "heartbeat": {
      "prompt": "Check the Stripe webhook endpoint. If there are new events in the last 30 minutes, list them. Otherwise reply HEARTBEAT_OK."
    }
  }
}

This is powerful but dangerous. A bad prompt = bad heartbeat = spam or silence.

The Bottom Line

HEARTBEAT.md is what turns OpenClaw from a chatbot into an autonomous agent. It's not about the agent doing more — it's about the agent noticing things at the right time.

The best heartbeats are:

Specific — check one thing, do it well
State-based — detect changes, not status
Silent by default — HEARTBEAT_OK is the goal
Alert rarely — when something genuinely needs attention

Study how Felix, Anti Hunter, and the Unwind AI team do it. Then build your own.

Your agent is watching. Make it watch for the right things.