OpenClaw Heartbeat Configuration: Keep Your AI Agent Proactively Aware

What Is a Heartbeat?

A heartbeat is a periodic check-in that the OpenClaw gateway sends to your agent. Think of it like a gentle tap on the shoulder every 30 minutes: "Hey, anything need attention?"

The agent looks around, reads a checklist file, decides if there is something worth doing, and either takes action or replies HEARTBEAT_OK to go back to sleep.

Configuring the Heartbeat Interval

The heartbeat interval is set in your OpenClaw gateway configuration. The default is 30 minutes -- a reasonable starting point. Adjust it based on how responsive you need your agent to be.

HEARTBEAT.md: Your Agent's Checklist

The real power of heartbeats comes from HEARTBEAT.md -- a file in your workspace that the agent reads on every poll. It is your way of telling the agent what to pay attention to without having to message it directly.

Here is what mine looks like on a typical day:

# HEARTBEAT.md

## Checks (rotate — don't do all every time)
- [ ] Unread emails — anything urgent?
- [ ] Calendar — events in next 2 hours?
- [ ] GitHub notifications — new PR reviews?
- [ ] Weather — worth mentioning if rain expected?

## Active reminders
- Chris has a dentist appointment at 2 PM today
- Waiting on reply from Vercel support (ticket #4821)

## Notes
- Quiet hours: 11 PM – 8 AM (HEARTBEAT_OK unless urgent)
- Last weather check was recent, skip today

• ●Keep it short. Every line in this file costs tokens on each heartbeat poll. A concise checklist beats a wall of instructions.
• ●Update it dynamically. Change priorities throughout the day -- the agent can even edit the file itself when it learns about new events or resolves old ones.

State Tracking: Avoiding Redundant Work

One pitfall with heartbeats: the agent checks email every 30 minutes and reports "no new emails" eight times in a row. Noisy and wasteful. The solution is a state file.

I keep a memory/heartbeat-state.json that tracks when each check last ran. On each heartbeat, the agent reads it, decides which checks are due, and updates timestamps after. Here is the structure:

{
  "lastChecks": {
    "email": "2026-03-23T10:30:00Z",
    "calendar": "2026-03-23T10:00:00Z",
    "github": "2026-03-23T09:30:00Z",
    "weather": "2026-03-22T14:00:00Z"
  }
}

Quiet Hours and Smart Silence

Your agent should know when to shut up. Late at night, early morning, or when you are deep in focus -- heartbeats should return HEARTBEAT_OK without doing anything unless something genuinely urgent comes up.

Heartbeat + Cron: The Full Awareness Stack

Heartbeats and cron jobs are not competing features -- they are complementary layers. The rule: if it needs conversational context and lightweight checking, use heartbeat. If it needs isolation, exact timing, or heavy processing, use cron.

Together they give your agent continuous awareness without continuous cost.

Practical Tips From Running This Daily

After weeks of running heartbeats in production, here is what I have learned.

• ●Keep HEARTBEAT.md under 20 lines. Every line costs tokens on every poll. Be ruthless about removing resolved items.
• ●Let the agent edit its own checklist. When the agent resolves a reminder or learns about a new event, it should update HEARTBEAT.md itself. Keeps the file current without manual maintenance.
• ●Use heartbeats for memory maintenance. Every few days, the agent can use a heartbeat to review recent daily notes and update its long-term memory file. Housekeeping that does not need its own cron job.
• ●Monitor your costs. A heartbeat with a large workspace context and an expensive model can cost $0.05-0.15 per poll. At 48 polls per day (every 30 min), that is $2.40-7.20 daily just for heartbeats. Choose your model wisely.

Go deeper

Get the complete agent awareness playbook

The full guide includes advanced heartbeat patterns, production HEARTBEAT.md templates, cost breakdowns by model, and the exact configuration I use to keep Kai running 24/7 without blowing through my API budget.