HEARTBEAT.md: The File That Makes Your OpenClaw Agent Proactive

Most people who start with OpenClaw use it reactively. They open Telegram, ask a question, get an answer. That's useful — it's a very capable AI assistant accessible from your phone. But it's not an agent. An agent does things without being asked.

The mechanism that turns reactive into proactive is a heartbeat: a repeating cron that fires every 30 minutes, reads HEARTBEAT.md, and acts on whatever's in it. When nothing needs attention, it replies HEARTBEAT_OK and goes quiet. When something does, it reaches out.

The result, after a week of running it: you stop mentally tracking whether things are being watched, because you know they are. That's a qualitative shift in how you work with the system.

The Fundamental Distinction: Assistant vs Agent

An assistant is a question-answering system. You initiate every interaction. It never acts unless prompted. The burden of knowing what to ask and when to ask it is entirely on you.

An agent monitors the environment and acts on changes. You define what it should watch and under what conditions it should reach out. After that, the burden of tracking is on the system, not on you.

The difference matters practically because human attention is limited and inconsistent. You might remember to check email at 9AM, 1PM, and 5PM — but you'll miss the 11:30AM critical message on a day when you're busy. An agent running a heartbeat every 30 minutes doesn't have busy days. It checks everything, every time, with perfect consistency.

HEARTBEAT.md is how you tell the agent what "everything" means.

How the Heartbeat Loop Works

The setup is two parts: the file and the cron.

Step 1: Create ~/.openclaw/workspace/HEARTBEAT.md with your checklist:

# HEARTBEAT.md

## Checks
- Email: any urgent unread messages? Flag to Commander.
- Calendar: any events in the next 2 hours? Remind Commander.
- Stripe: any new activity since last heartbeat? Alert immediately.

## If nothing needs attention
Reply: HEARTBEAT_OK

Step 2: Add a repeating cron that reads the file and runs the checks:

openclaw cron add \
  --type every \
  --interval 30m \
  --prompt "Read HEARTBEAT.md in your workspace. Follow it exactly. Do not infer or repeat tasks from prior sessions. If nothing needs attention, reply HEARTBEAT_OK." \
  --label "heartbeat" \
  --deliver-to "telegram:group:-1003710289268"

Now every 30 minutes, the agent wakes up, reads the file, runs the checks, and either contacts you (if something matters) or replies HEARTBEAT_OK (if nothing does). The HEARTBEAT_OK reply is delivered to the channel but it's a known signal — your Telegram client can filter or mute it if you don't want to see it.

What to Put in HEARTBEAT.md

Good heartbeat checks share a structure: observable, actionable, bounded. Each check should have a clear answer and a clear condition for escalation.

Here's the full structure I run:

# HEARTBEAT.md

## 1. Email
Use the gog skill to check Gmail. Flag any emails that:
- Are from a customer (aussieclaw.ai domain or Stripe notification)
- Are marked urgent or require a response today
- Are about a failed payment or service outage
Skip: newsletters, marketing, automated notifications.

## 2. Calendar
Check Google Calendar via gog skill.
If there's an event in the next 2 hours: remind Commander with title, time, and location.
If there's nothing in the next 2 hours: no message needed.

## 3. Stripe Activity
Check heartbeat-state.json for last Stripe check timestamp.
If it's been more than 2 hours, run: python3 scripts/stripe_monitor.py --check
Alert Commander if there are new charges, failures, or refunds.
Update heartbeat-state.json with current timestamp.

## 4. Failed Crons
Check openclaw cron list for any crons showing error status.
If any cron has failed more than once consecutively, alert Commander with the label and last error.

## 5. Gateway Health
Run: openclaw gateway status
If not running, alert Commander immediately: "Gateway is down."
If running, no message needed.

## Decision Rule
Contact Commander if any check has actionable information.
Stay silent (HEARTBEAT_OK) if all checks are clear.
Do NOT send HEARTBEAT_OK if you've already sent a substantive message.

## Out of Scope
Do not take action on findings — only report.
Do not check the same thing twice in one heartbeat.
Do not infer tasks from prior conversations.

The "Out of Scope" section is as important as the checks. The heartbeat's job is to inform, not to act. Keeping it bounded prevents the agent from taking initiative beyond what's been authorised at a time when you may not be paying attention.

The HEARTBEAT_OK Pattern — Why Silent Acknowledgement Matters

When nothing needs attention, the agent replies HEARTBEAT_OK. This single string is the signal that everything is fine. It's short, unambiguous, and machine-parseable.

Why not just stay silent when nothing needs attention? Two reasons:

First, silence is ambiguous. If the heartbeat doesn't send anything, you don't know whether nothing happened or whether the cron failed to run. HEARTBEAT_OK is a positive confirmation that the check ran and found nothing. Failed crons are silent too — so silence doesn't tell you what you need to know.

Second, it gives you a lightweight audit trail. You can scroll through your Telegram history and see: "HEARTBEAT_OK at 09:30, 10:00, 10:30... then an email alert at 11:00, then HEARTBEAT_OK at 11:30." The cadence is visible. Gaps in the cadence are visible. That's useful when debugging.

If the HEARTBEAT_OK messages become noise in your Telegram, mute or filter them at the client level — but keep them being sent so the audit trail exists.

Token Cost Management

Every heartbeat is a Claude API call. At 30-minute intervals, that's 48 calls per day. At roughly 1,000–2,000 tokens per call (context + tools + response), that's 50,000–100,000 tokens per day for heartbeats alone.

At Claude Sonnet pricing (roughly $3 per million input tokens), that's $0.15–$0.30/day — about $5–10/month. Manageable, but worth being deliberate about.

Two levers to control it:

Interval. Every 30 minutes is right for most setups. Every 5 minutes would cost 6x as much and rarely finds something different. Every hour is fine if you're less time-sensitive. Pick the interval that matches how quickly you actually need to know things.

File length. The heartbeat file is loaded into context on every run. Keep it under 100 lines. Long, verbose checks burn more tokens and don't perform better. Each check should be 2–4 lines: what to check, the escalation condition, what to do. No more.

# Lean heartbeat check (good — ~3 lines, clear)
## Email
Check Gmail. Alert if email from a customer or about a payment.
Otherwise skip.

# Bloated heartbeat check (bad — verbose, costs more, same outcome)
## Email
Please use the gog skill to access Gmail and retrieve all unread messages
from the past 24 hours. Read each message carefully and determine whether
any of them require immediate attention. Consider the sender, subject line,
and message body when making this determination. If you find any messages
that seem urgent or are related to customers or payments, please summarise
them and alert the Commander with full details including sender, subject,
time received, and key content. If nothing seems urgent, you may skip.

The lean version does the same thing for a third of the tokens.

Real Examples: What Mine Actually Checks

My live HEARTBEAT.md covers five areas in about 40 lines. Here are the actual check structures:

## Gateway Health
Run: openclaw gateway status
Alert Commander immediately if status is not "running".

## Email (via gog skill)
Check Gmail for unread messages from the past 30 minutes.
Alert if: customer inquiry, payment notification, service outage.
Skip: newsletters, automated platform emails, anything marked promotional.

## Calendar (via gog skill)
If any event starts within 90 minutes: remind Commander with title + time.

## Stripe
If last Stripe check (heartbeat-state.json → lastChecks.stripe) is >2 hours ago:
Run: python3 scripts/stripe_monitor.py --check
Alert on any new activity. Update lastChecks.stripe timestamp.

## Cron Health
Check: openclaw cron list
Alert if any cron has status "failed" or hasn't run in 2x its expected interval.

Total: about 35 lines. Covers the five things that most need to be caught quickly. Has run reliably for weeks without meaningful drift or false alarms.

How to Start Simple and Expand

If you're setting this up for the first time, don't start with five checks. Start with three:

# Minimal HEARTBEAT.md — start here
# HEARTBEAT.md

## 1. Gateway Health
Run: openclaw gateway status
Alert if not running.

## 2. Email
Check for any urgent unread messages.
Alert if anything needs attention today.
Skip newsletters and automated emails.

## 3. Calendar
Any events in the next 2 hours? Remind me.

## Default
If nothing needs attention: HEARTBEAT_OK

Run this for a week. Get comfortable with the cadence, tune the email filter based on what actually fires, adjust the calendar window if 2 hours is wrong for your schedule. Then add checks one at a time — Stripe, cron health, specific webhooks, whatever matters for your setup.

The right amount of complexity is the minimum that catches everything you actually need caught. More than that is noise and token cost with no benefit.

The Mental Shift: From Checking to Knowing

Here's what changes after a few weeks of a running heartbeat:

Before: "I should check whether there's been a Stripe sale." (Manual friction. You might or might not do it.)

After: "I know if there's been a Stripe sale, because I'd have gotten a message." (The check is done. There's no friction.)

That's a subtle but real shift. The cognitive load of tracking whether things are being monitored goes to zero. You stop mentally scheduling checks because you've off-loaded the scheduling to the system. The agent's job is to watch; your job is to decide when it flags something.

It's the same mental relief as having a good calendar system. You don't have to remember appointments — you trust that they're there and the reminders will fire. HEARTBEAT.md is that, but for operational checks.

If you want to set this up with pre-built check templates and examples from a live installation, Guide 01: The AI Starter Kit includes a full HEARTBEAT.md starter, the heartbeat cron configuration, and the heartbeat-state.json tracking file. It also covers how to integrate email, calendar, and Stripe checks specifically, with the actual gog skill commands that work.