OpenClaw Heartbeats: Making Your AI Agent Proactive Instead of Reactive

Hex · March 11, 2026 · 8 min read

Most AI agents are reactive. You ask, they answer. You forget to ask, nothing happens. That's fine for a chatbot — it's not fine for an employee.

A real employee doesn't wait for you to ask "did anything go wrong?" They check. They surface issues. They follow up. OpenClaw's heartbeat system is what gives your AI agent that same proactive behavior — without you having to babysit it.

What Is a Heartbeat?

A heartbeat is a periodic agent turn that OpenClaw's Gateway triggers on a schedule. Every N minutes (default: 30), the Gateway wakes up the agent and says: "check on things." The agent reads your HEARTBEAT.md checklist, looks at whatever you've told it to monitor, and either stays silent or surfaces something that needs attention.

If nothing needs attention, the agent replies HEARTBEAT_OK. OpenClaw treats that as a silent acknowledgment — no message is delivered, no noise. The moment something does need attention, you get an alert.

That's the key insight: heartbeats are mostly silent. You only hear from the agent when it has something to say. The rest of the time it's quietly doing its job in the background.

How It Works Under the Hood

Heartbeats run as full agent turns inside the main session. The Gateway sends a message to the agent — the default prompt is:

Read HEARTBEAT.md if it exists (workspace context). Follow it strictly.
Do not infer or repeat old tasks from prior chats.
If nothing needs attention, reply HEARTBEAT_OK.

The agent has full context: your HEARTBEAT.md checklist, the main session history, and access to all its tools. It can read files, run searches, check APIs, inspect logs — whatever your checklist tells it to do.

The result is either:

HEARTBEAT_OK — stripped and discarded. No delivery, no noise.
An alert message — delivered to whatever channel you've configured (Slack, Telegram, WhatsApp, Discord, etc.).

Heartbeat-only turns don't keep your session "active" — idle expiry behaves normally. This is deliberate: the system is designed to be low-overhead.

Setting Up Heartbeats

Heartbeats are on by default at a 30-minute interval. To customize, add a heartbeat block to your openclaw.json:

Key fields:

every: interval (e.g. "15m", "1h"). Set "0m" to disable.
target: where to deliver alerts. Use "last" for the last active channel, or explicitly name one: "slack", "telegram", "whatsapp", "discord". Default is "none" (runs silently, no external delivery).
activeHours: restrict heartbeats to a time window. Outside the window, ticks are skipped. Uses your configured timezone.

The HEARTBEAT.md Checklist

This is the file that actually makes heartbeats useful. It's a small markdown checklist that the agent reads on every heartbeat turn. Think of it as your standing instructions for what to monitor.

Example:

# Heartbeat checklist

- Check Slack DMs for anything urgent
- If a background task finished, summarize results
- Review calendar for events in the next 2 hours
- If it's been more than 8 hours since last check-in, send a brief status update

The agent follows this list on every tick. If the inbox is clear and nothing is pending, it replies HEARTBEAT_OK and you never hear about it. If something is urgent, you get a message.

Keep this file small. It's injected into every heartbeat turn — the bigger it gets, the more tokens every tick costs. Short, stable, actionable items only.

Updating HEARTBEAT.md

It's just a file in your agent workspace. You can edit it yourself, or tell the agent in normal chat: "Update HEARTBEAT.md to add a daily calendar check." The agent will modify the file, and every future heartbeat will include that check automatically.

Restricting to Active Hours

You probably don't want your agent waking up and pinging you at 3am. The activeHours setting handles this:

Outside 9am–10pm Eastern, heartbeats are skipped entirely. The next tick inside the window runs normally. If you omit activeHours, heartbeats run 24/7.

The timezone field accepts any IANA timezone identifier. If omitted, it falls back to your agents.defaults.userTimezone, and then to the host system timezone.

Per-Agent Heartbeats

If you're running multiple agents (for example, a main agent and a separate ops agent), you can configure heartbeats independently per agent. The moment any agent in agents.list[] has a heartbeat block, only those agents run heartbeats — the defaults stop applying globally.

In this setup, only the ops agent runs heartbeats, at 1-hour intervals, delivering alerts to Telegram.

Lightweight Context Mode

By default, heartbeat turns include your full workspace bootstrap context (AGENTS.md, SOUL.md, USER.md, and so on). That's useful when the agent needs full context to make good decisions — but it also costs more tokens per tick.

If your heartbeat checklist is simple and self-contained, enable lightContext:

With lightContext: true, the heartbeat turn loads only HEARTBEAT.md from workspace files and skips the rest. Cheaper per tick. Use it when your checklist doesn't need the agent to know its full identity and instructions.

Heartbeat vs Cron: Knowing When to Use Each

If you've read our post on OpenClaw Cron Jobs, you might be wondering when to use heartbeats vs cron jobs. Here's the short version:

Heartbeat: periodic awareness, batched monitoring, context-aware decisions. One turn handles everything on your checklist. Smart suppression keeps it quiet when nothing needs attention.
Cron: precise timing, isolated runs, different model, standalone tasks. Use when you need "send report at exactly 9:00 AM" or want a clean session without main context.

The most efficient setup uses both: heartbeat for routine monitoring, cron for precisely scheduled deliveries. A single heartbeat every 30 minutes batching five checks is dramatically cheaper than five separate cron jobs doing the same thing.

Manual Wake

You can trigger an immediate heartbeat on demand from the CLI:

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

This enqueues a system event and wakes the agent immediately, bypassing the normal schedule. If multiple agents have heartbeat configured, the manual wake triggers all of them.

Use --mode next-heartbeat instead if you want the event handled at the next scheduled tick rather than immediately.

Visibility Controls

By default, HEARTBEAT_OK acknowledgments are silently dropped while alerts are delivered. You can tune this per-channel:

Setting all three (showOk, showAlerts, useIndicator) to false skips the heartbeat run entirely — no model call, no cost.

Cost Awareness

Heartbeats are full agent turns. More frequent = more tokens. A few things to keep in mind:

Keep HEARTBEAT.md tight — it's injected every single tick.
Use lightContext: true if the agent doesn't need full workspace context for its checks.
Consider a cheaper model override for heartbeat turns: "heartbeat": { "model": "anthropic/claude-haiku-3-5" }
Set target: "none" if you only want internal state updates with no external delivery.
Use activeHours to stop burning tokens at night when nobody's watching.

A well-tuned heartbeat setup is surprisingly cheap. At 30-minute intervals, lightContext: true, and a lean HEARTBEAT.md, you're looking at maybe a few cents per day for a genuinely proactive agent that never misses anything.

What This Looks Like in Practice

I run heartbeats for this entire operation — blog publishing, Slack monitoring, task follow-ups. My HEARTBEAT.md is maybe 8 lines. Every 30 minutes, the agent wakes up, reads the checklist, checks if anything needs attention, and either goes back to sleep (silently) or pings me on Slack with exactly what's needed.

99% of the time: silence. The rare time it surfaces something — a blocked task, a stale deploy, an urgent message I missed — is exactly when it matters. That's the point.

The difference between a reactive chatbot and an actual AI employee isn't intelligence. It's initiative. Heartbeats are what give your agent that.