What Is the OpenClaw Heartbeat Engine?

Introduction

Every AI tool built before OpenClaw shared one fundamental property: they waited. You had to initiate every interaction. Close the app, and the intelligence went dormant. It didn't matter how capable the model was — if you didn't ask, nothing happened.

The Heartbeat Engine breaks that constraint completely. It is the mechanism by which OpenClaw becomes genuinely proactive — waking itself, assessing its environment, taking action, and reporting results without any human trigger. It transforms your AI from a very smart calculator into something that behaves more like a tireless digital employee who works while you sleep.

Understanding the Heartbeat Engine is the key to unlocking OpenClaw's highest-value capabilities. This guide explains exactly how it works and how to configure it for real-world results.

Reactive vs Proactive AI

To appreciate what the Heartbeat Engine does, consider the difference between two approaches to the same task: monitoring your website's uptime.

With a reactive AI tool, you'd have to periodically ask: "Is my website up?" The AI would check and answer. But only if you asked. And only when you happened to think of asking. If your website went down at 3 AM, you'd find out at 9 AM when a customer complained.

With OpenClaw's Heartbeat Engine, the situation is fundamentally different. You configure the heartbeat task once: "Every 30 minutes, check if my website returns a 200 status code. If it doesn't, message me immediately on Telegram." Now the agent checks automatically every 30 minutes — no human involvement required. The 3 AM outage triggers a message to your phone. You know before your customers do.

This shift from reactive to proactive is the most significant capability difference between OpenClaw and every other consumer AI tool available today. The Heartbeat Engine is the technical implementation of that shift.

How the Heartbeat Engine Works

The Heartbeat Engine is implemented as an internal scheduler within the OpenClaw Node.js service. When the service starts, the engine registers a recurring timer based on the configured interval. When that timer fires, the engine creates a new agent session — not connected to any incoming message — and provides the agent with a specific instruction: process the HEARTBEAT.md checklist.

The agent then reads its HEARTBEAT.md file (a Markdown document you maintain that lists tasks and conditions to check), and works through each item. For each task, the agent may invoke Skills — checking server status via HTTP, querying a database, reading a local file, calling an external API, running a shell command. After processing each item, it decides whether to take further action or simply log that everything is normal.

If any task requires alerting you — a server is down, a price threshold has been crossed, a calendar event is approaching — the agent uses the configured messaging channel to send you a notification. These proactive messages appear in your Telegram (or WhatsApp, or Slack) exactly like any other message from the bot, but they arrive without you having initiated anything.

The entire heartbeat cycle — from wakeup to task processing to any notifications — typically takes 10 to 60 seconds, depending on the number of tasks and the Skills being invoked. For complex heartbeat checklists with many external API calls, cycles can take several minutes.

Configuring the Heartbeat

The heartbeat configuration lives in your ~/.openclaw/openclaw.json file (JSON5 format) under agents.defaults.heartbeat:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "model": "anthropic/claude-haiku-4-5",
        "target": "telegram",
        "lightContext": true,
        "isolatedSession": true,
        "ackMaxChars": 300,
        "activeHours": {
          "start": "07:00",
          "end": "22:00",
          "timezone": "America/New_York"
        }
      }
    }
  }
}

Key configuration options:

• every: How often the heartbeat fires as a duration string (e.g., "30m", "1h", "2h"). Default is "30m". Set "0m" to disable. Set lower (5–15 minutes) for time-sensitive monitoring. Set higher (60–120 minutes) to reduce API costs.
• model: Override the LLM model for heartbeat runs. Use a cheap model like Haiku or GPT-4o Mini to keep costs low — without this, heartbeat uses your default (potentially expensive) agent model.
• target: Which channel receives heartbeat output. Options: a specific channel name like "telegram" or "whatsapp", "last" for your last active external channel, or "none" to suppress delivery. Defaults to "none" — you must set this explicitly or your heartbeat won't deliver messages.
• lightContext: When true, keeps only HEARTBEAT.md from the workspace bootstrap files, dramatically reducing token usage per tick.
• isolatedSession: When true, runs each heartbeat in a fresh session with no conversation history. Combined with lightContext, this can reduce per-tick token usage from ~100K to ~2–5K tokens.
• ackMaxChars: Maximum characters allowed after HEARTBEAT_OK before the message is delivered anyway. Default is 300. When the agent replies with HEARTBEAT_OK at the start or end of its response and the remaining content is under this limit, the Gateway drops the message silently.
• activeHours: Optional time window restricting when heartbeat runs. Set timezone to your IANA timezone (e.g., "America/New_York") so the schedule aligns with your local time, not your server's clock.

Real-World Use Cases

The community has built hundreds of compelling heartbeat-powered workflows. Here are the most impactful categories:

Server & Infrastructure Monitoring: Checking HTTP endpoints, monitoring disk space and CPU usage, verifying that critical services are running, and alerting when Kubernetes pods crash. Community member "Reef" (an agent name) became famous in the community for autonomously rotating SSL certificates, clearing disk space, and restarting crashed services — all without a human waking up at 3 AM.

Financial & Market Monitoring: Checking RSI levels for cryptocurrency or stock positions, monitoring portfolio value changes, alerting when price targets are hit, and aggregating financial news. Traders have configured agents that check 20 different positions every hour and only message them when something crosses a threshold requiring attention.

Calendar & Schedule Management: Generating daily briefings at 8 AM with the day's meetings, alerting 30 minutes before an event starts, identifying scheduling conflicts, and summarizing upcoming deadlines across multiple connected calendars.

Health & Wellness Tracking: Reading data from WHOOP, Oura Ring, or Apple Health, calculating trends, and generating weekly health summaries. One community project correlated air quality sensor data with a WHOOP fitness band, adjusting an automated air purifier when the combination of poor air and elevated stress was detected.

Business Intelligence: Monitoring competitor websites for price changes, tracking keyword rankings, summarizing overnight news in your industry, and alerting to significant changes in key business metrics.

The HEARTBEAT.md File

The HEARTBEAT.md file is the control interface for your proactive agent. It lives at ~/.openclaw/workspace/HEARTBEAT.md and is a Markdown file you write and maintain, listing the tasks you want the agent to check on each heartbeat cycle. Unlike traditional cron jobs or scheduled scripts, the tasks in HEARTBEAT.md are written in natural language — the agent interprets them and decides how to execute them using its available Skills. If the file is empty (blank lines and headers only), OpenClaw skips the heartbeat run entirely to save API calls.

A simple HEARTBEAT.md might look like this:

# Heartbeat Checklist

## System Health
- [ ] Check that openclaw.mysite.com returns HTTP 200. Alert if not.
- [ ] Verify disk usage on /dev/sda1 is below 85%. Alert if above 90%.

## Morning Briefing (8:00–8:15 AM only)
- [ ] Send me a briefing with today's calendar events and top tech headlines

## Market Monitoring
- [ ] Check BTC price. Alert if it moves more than 5% since last check.

## Weekly Review (Mondays only)
- [ ] Summarize last week's completed tasks from memory and suggest priorities

The agent reads this checklist, understands the intent of each item, and uses its Skills to execute them. Time conditions like "8:00–8:15 AM only" are respected by the agent natively. The agent can also modify this file itself — checking off completed one-time tasks, adding new tasks it discovers are needed, and adjusting parameters based on what it learns about your preferences over time.

Limitations & Considerations

The Heartbeat Engine is powerful but not without limitations. A few important things to know:

API costs accumulate. Every heartbeat cycle consumes tokens from your LLM provider. A 30-minute interval means 48 cycles per day. Optimize by setting lightContext: true and isolatedSession: true in your heartbeat config — this reduces per-tick token usage from ~100K to ~2–5K tokens. Use a cheap model like Haiku or GPT-4o Mini via the model field, and reserve premium models for interactive conversations.

Not a real-time system. The heartbeat fires on an interval, not on events. If something happens 1 second after a heartbeat cycle, you won't hear about it for another 29 minutes (if on a 30-minute cycle). For true real-time alerting, configure dedicated monitoring services (like Uptime Robot) for critical systems and use OpenClaw for the intelligent response and analysis layer.

The agent can get distracted. A complex heartbeat checklist with many interdependent tasks can sometimes cause the agent to get stuck in a reasoning loop, consuming excessive tokens without completing all tasks. Keep heartbeat tasks atomic and focused. If a task is complex, break it into smaller steps.

Active hours help. Without activeHours configured in your heartbeat config, the heartbeat runs 24/7 and alerts can wake you at 2 AM for non-critical conditions. Set activeHours.start and activeHours.end with your IANA timezone to restrict heartbeat runs to waking hours. For critical alerts that must bypass this, use urgency tiers in your HEARTBEAT.md task descriptions.

Wrapping Up

The Heartbeat Engine is the feature that most fundamentally distinguishes OpenClaw from every other AI tool. It's what makes an AI assistant into an AI agent. The shift from "I ask, it answers" to "it monitors, it acts, it tells me what I need to know" is a qualitative change in the nature of human-AI collaboration.

Investing time in a well-designed HEARTBEAT.md file pays compound returns. Every task you configure well is a task you never have to remember to check manually again. Over days and weeks, that accumulation of delegated attention frees up significant cognitive bandwidth for the work that actually requires you.