OpenClaw Heartbeats: How to Make Agents Proactive, Not Just Reactive

The Problem With Purely Reactive Agents

An agent that only waits for messages is basically a better chatbot. You write, it responds. That's useful — but it wastes the real potential.

Imagine you have an important meeting at 9 AM, and your agent knows about it — but says nothing because you didn't ask. Or a critical email arrives in the inbox, and the agent just keeps sleeping.

That's the difference between reactive and proactive. OpenClaw heartbeats solve exactly that.

---

What Is a Heartbeat?

A heartbeat is a periodic message that OpenClaw automatically sends to your agent — like an alarm clock ringing every 30 minutes.

The agent receives the heartbeat prompt, checks what's going on, and decides: Is there something to report? Or is everything quiet?

```

# What a heartbeat looks like internally (OpenClaw):

→ [System] Heartbeat: Check HEARTBEAT.md, execute tasks.

If nothing needs attention: reply with HEARTBEAT_OK.

```

The key principle: HEARTBEAT_OK is a signal, not an obligation. If there's something to do, the agent does it. If not, it briefly acknowledges and goes back to sleep.

---

How We Use Heartbeats in Our 6-Agent Setup

Sam (Team Lead) — every 30 minutes

Sam gets regular heartbeats and checks (on rotation, not all at once):

That sounds like a lot — but through rotation, Sam only checks 1-2 things per heartbeat. The rest sleeps.

Atlas (CEO Agent) — daily at 8:00 AM

Atlas has a single cron job: send a daily briefing to Dimitrios at 8:00 AM sharp. No heartbeat polling — a precise schedule.

This is an important distinction: heartbeat for flexible, staggered checks. Cron for exact times.

Peter (Coding Agent) — no heartbeat

Peter only waits for explicit coding tasks. A heartbeat would just burn tokens with no value. Not every agent needs heartbeats.

---

HEARTBEAT.md: Your Control Center

The simplest way to control heartbeats is a `HEARTBEAT.md` file in the workspace. The agent reads this file on every heartbeat and knows what to check.

```markdown

# HEARTBEAT.md

Regular Checks

Status

```

The agent reads the file, runs the relevant checks, and updates the status lines. This prevents duplicate checks and avoids burning unnecessary tokens.

---

Tracking Heartbeat State with JSON

For more precise tracking, we use a simple JSON file in the workspace:

```json

// memory/heartbeat-state.json

{

"lastChecks": {

"email": 1741603200,

"calendar": 1741600000,

"disk": null

}

}

```

The agent reads this timestamp, compares it to the current time, and decides: "Email was checked 3 hours ago — time for a new check."

That might sound like a lot of logic — but in practice you write it once as an instruction in `HEARTBEAT.md` and the agent manages the rest itself.

---

The Silence Principle: No Spam, Please

The most common heartbeat mistake: too many messages.

If the agent writes on every heartbeat — even when nothing happened — it gets annoying fast. That's why we follow the silence principle:

| Situation | Action |

|-----------|--------|

| Nothing important | `HEARTBEAT_OK` (no message) |

| Something relevant | Send a short message |

| Critical alert | Immediate message, even at night |

In our setup, Sam keeps quiet from 11 PM to 8 AM — except for real emergencies (disk full, server down). The quiet window is defined in `HEARTBEAT.md`:

```markdown

Quiet Window

No messages between 23:00 and 08:00 UTC —

except for critical alerts (disk >90%, server unreachable).

```

---

Heartbeat vs. Cron: When to Use Which?

This is a question we had to figure out. The answer:

Use heartbeat when:

Use cron when:

Examples from our setup:

---

Token Costs: What Does a Heartbeat Cost?

That's the legitimate question. Our real numbers:

Using Claude Haiku for heartbeats and Claude Sonnet/Opus only for real work: negligible costs.

Pro tip: Use the cheapest model (Haiku) for heartbeat checks. When real work comes up, the agent can decide to escalate or delegate complex tasks.

---

Practical Heartbeat Configuration

In the OpenClaw config (or via `openclaw configure`) you set the heartbeat interval:

```

# openclaw gateway heartbeat --interval 30

# → Heartbeat every 30 minutes

```

The heartbeat prompt is freely configurable:

```

Check HEARTBEAT.md in the workspace. Run the checks defined there.

If nothing needs attention: reply with HEARTBEAT_OK.

```

Simple, clear, repeatable.

---

What We Learned

After several months with proactive agents:

1. Start small. One check (just email) is better than ten at once.

2. Quiet windows are not optional. Without them you'll get pinged at night for unimportant things.

3. HEARTBEAT_OK must be genuine. The agent should truly stay silent when nothing's going on — not politely.

4. State in files, not in memory. Storing timestamps in JSON prevents duplicate checks.

5. Heartbeats ≠ cron. Understand the difference and use both deliberately.

The difference between an agent that just waits and one that thinks ahead — that's the heartbeat.

The complete configuration — including HEARTBEAT.md templates, heartbeat-state.json schema, and the exact OpenClaw settings for all 6 agents — is documented in the OpenClaw Setup Playbook.

Fully available in German too. 🇩🇪