In This Article
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 config.yaml file:
heartbeat:
enabled: true
interval_minutes: 30
heartbeat_file: "./memory/HEARTBEAT.md"
notify_channel: telegram
quiet_hours:
start: "22:00"
end: "07:00"
timezone: "America/New_York"Key configuration options:
- interval_minutes: How often the heartbeat fires. 30 minutes is the default. Set lower (5–10 minutes) for time-sensitive monitoring. Set higher (60–120 minutes) to reduce API costs.
- quiet_hours: Optional time windows where the heartbeat runs but suppresses notifications. Useful so you're not woken by low-priority alerts at 3 AM.
- notify_channel: Which messaging channel receives proactive notifications. You can specify different channels for different urgency levels with more advanced configuration.
- heartbeat_file: Path to your HEARTBEAT.md file. This file defines what the agent actually does on each cycle.
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's 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.
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 prioritiesThe 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. If each cycle uses 1,000 tokens on a moderate model, that's 48,000 tokens daily — meaningful cost if you're using expensive frontier models. Optimize by using smaller, cheaper models for heartbeat tasks and reserving 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.
Quiet hours help. Without quiet hours configured, a heartbeat-driven alert will wake you up at 2 AM for a non-critical condition. Invest a few minutes in configuring appropriate quiet hours and urgency tiers for your notifications.
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.