What Is the HEARTBEAT.md File in OpenClaw?

Introduction

Every proactive action your OpenClaw agent takes without you asking originates from one file: HEARTBEAT.md. It's a simple Markdown checklist that the agent reads on a schedule — typically every 30–60 minutes — and works through systematically, taking whatever actions each item requires. Understanding how to write and maintain this file well is the single most important skill for getting sustained value from OpenClaw.

Unlike traditional cron jobs or automation scripts that execute rigid code, the HEARTBEAT.md tasks are written in natural language. Your agent interprets them intelligently, uses its Skills to gather required information, makes judgment calls, and acts — all without human involvement. A well-designed HEARTBEAT.md file is the difference between an OpenClaw setup that's occasionally useful and one that's genuinely transformative to how you work.

Here's what we're covering: everything from the basic file format to advanced patterns used by the most sophisticated community deployments.

What Is HEARTBEAT.md?

HEARTBEAT.md is a plain Markdown file stored in your OpenClaw memory directory. Its name isn't arbitrary — it is the literal heartbeat of your agent's autonomous operation. When OpenClaw's Heartbeat Engine fires on its configured schedule, the first thing the agent does is read this file and process each item as a task.

The file uses standard Markdown checkbox syntax to represent tasks. Items marked with - [ ] are active tasks the agent should check and potentially act on. Items marked with - [x] are completed (typically used for one-time tasks that should only run once). Section headers organize related tasks into groups. Comments (lines starting with > or HTML comment syntax) provide context without becoming tasks.

What makes HEARTBEAT.md powerful is that the agent doesn't just execute predefined scripts — it reasons about each task. The same instruction "check if anything important happened overnight in the crypto markets" will result in different specific actions depending on what actually happened overnight, what counts as "important" given the agent's learned knowledge of your preferences, and what information it can gather through its available Skills.

File Structure & Syntax

A well-structured HEARTBEAT.md uses headers to group related tasks and conditional syntax to handle time-based logic:

# HEARTBEAT TASKS
> Last updated: Feb 18, 2026
> Heartbeat interval: 30 minutes

## Always Run
- [ ] Check that primary website returns 200 OK. Alert via Telegram if not.
- [ ] Verify disk usage on main server is below 80%. Alert if above 85%.

## Morning Routine (7:30–8:30 AM on weekdays only)
- [ ] Pull today's calendar events and send a formatted daily briefing to Telegram
- [ ] Check weather for my location and include in briefing if significant
- [ ] Summarize any high-priority emails received overnight

## Market Monitoring (weekdays, 9 AM–4 PM)
- [ ] Check Bitcoin price. Alert if it moves more than 3% since last heartbeat.
- [ ] Check S&P 500 level. Note in memory if it crosses any key levels.

## Weekly Review (Monday mornings only)
- [ ] Summarize completed tasks from DECISIONS.md over the past 7 days
- [ ] Review memory/goals.md and suggest any outdated goals to remove

## One-Time Tasks
- [ ] Research and summarize the top 5 agentic AI frameworks besides OpenClaw
- [x] Set up initial HEARTBEAT.md structure (completed)

Key structural conventions:

• Group by frequency and context: "Always Run" tasks run every cycle; time-conditional groups run only during specified windows; one-time tasks run once and get marked complete.
• Be specific about alert conditions: Don't write "monitor the server" — write "check if the web server returns HTTP 200 and alert if it doesn't within 3 consecutive checks."
• Specify the output channel: For tasks that produce notifications, specify where (Telegram, Slack, email). Without this, the agent will choose the default channel.
• Include completion criteria: The agent needs to know when a task is "done" for this cycle. "Review the GitHub PR queue and add any PRs older than 48 hours to my to-do list" has a clear completion state.

Writing Effective Tasks

The quality of tasks you write in HEARTBEAT.md is the primary determinant of how useful your agent's proactive behavior is. Three principles guide effective task writing:

Principle 1: Specify triggers, not just monitoring. "Monitor my website" is a monitoring instruction without a trigger. "Check my website every cycle and alert me via Telegram immediately if it returns anything other than HTTP 200" has a clear trigger (non-200 response) and a clear action (Telegram alert). The agent needs to know what "something happened" looks like.

Principle 2: Define urgency levels. Not all alerts are equal. A server down at 2 AM should wake you up. A competitor publishing a new blog post can wait until your morning briefing. Classify tasks by urgency and configure quiet hours for non-critical alerts: "Alert at any hour if critical, include in morning briefing only if medium-priority."

Principle 3: Include relevant context. Rather than relying entirely on the agent's memory, include key context directly in the task: "Check the BTC price. My current position is long from $48,000. Alert if price drops below $45,000 (stop level) or rises above $55,000 (take-profit level)." This context removes ambiguity and ensures the agent acts on your actual parameters.

Common task patterns that work well in HEARTBEAT.md:

• "Check X. If condition Y, do action Z. Otherwise, log OK status."
• "At [time], compile [data sources] into a [format] and send to [channel]."
• "Every [day/week/month], review [resource] and suggest [improvement/update/action]."
• "If [event detected], immediately [alert/record/escalate] and include [specific information]."

Setting the Heartbeat Cadence

The heartbeat interval determines how frequently the agent works through its HEARTBEAT.md checklist. There's no single right interval — it depends on your use cases and cost tolerance:

Use shorter intervals for tasks where time-to-alert matters (infrastructure, trading). Use longer intervals for tasks where hourly or twice-daily processing is sufficient (news summaries, competitive monitoring, weekly digests). Configure different heartbeat intervals for different task categories by running multiple OpenClaw instances with specialized HEARTBEAT.md files and different interval settings.

Example HEARTBEAT.md Files

For a freelance developer:

# Dev Freelancer Heartbeat

## Always
- [ ] Check that all client project monitoring URLs return 200. Alert me immediately if any are down.

## Morning (8:00–8:30 AM)
- [ ] Pull GitHub notifications. Summarize any PRs awaiting my review or urgent issues.
- [ ] Check email. Flag anything from client domains as urgent and send preview to Telegram.

## Afternoon (4:30–5:00 PM)
- [ ] Compile what I accomplished today from memory and send an end-of-day summary.
- [ ] Check if any time-sensitive client communications need follow-up.

## Weekly (Fridays 4 PM)
- [ ] Generate a weekly report: projects updated, hours tracked, upcoming deadlines.

For a small e-commerce business:

# E-Commerce Heartbeat

## Always
- [ ] Check Shopify order queue. Alert if any orders have been unfulfilled for more than 4 hours.
- [ ] Monitor website uptime. Alert immediately if down.

## Daily (9 AM)
- [ ] Pull yesterday's sales metrics. Compare to 7-day average. Flag if down more than 15%.
- [ ] Check inventory levels. Alert for any SKUs below 10 units.
- [ ] Review customer support tickets opened overnight. Categorize and send summary.

## Weekly (Mondays 8 AM)
- [ ] Generate week-over-week sales comparison report for last 4 weeks.
- [ ] Review pending reviews and identify themes for product improvements.

Advanced Patterns

Conditional escalation: Tasks can reference previous states stored in memory to implement multi-level escalation. "Check server response time. If above 500ms and this is the third consecutive check above 500ms (see memory/alert-state.md), escalate to phone call via Twilio rather than just Telegram message."

Self-modifying heartbeat: The agent can modify its own HEARTBEAT.md as needed. "During sprint weeks (check memory/sprints.md for current sprint status), add a 30-minute standup generation task at 9:30 AM. During non-sprint periods, remove it." This allows the HEARTBEAT.md to stay relevant as your workflow changes without constant manual maintenance.

Agent-to-agent tasks: In multi-agent setups, heartbeat tasks can write to shared files as instructions for other agents: "Check METRICS.md. If MRR growth rate has dropped below 5% for 2 consecutive weeks, write a task in TASKS.md for the strategy agent to conduct a growth diagnosis."

Common Pitfalls to Avoid

• Vague tasks: "Monitor my website" gives no trigger. Use "Check HTTP 200. Alert if not."
• Too many tasks: 20+ tasks per cycle = slow, expensive. Start with 5–8. Add incrementally.
• No output channel: "Alert me" — where? Specify Telegram, Slack, or email. Otherwise the agent may not notify.
• Ignoring quiet hours: Without quiet hours, you'll get 2 AM alerts for non-critical items.
• Full-LLM for everything: Use two-tier. Scripts for checks; LLM only when reasoning is needed. Saves 70%+ on API costs.

Frequently Asked Questions

Can the agent modify HEARTBEAT.md itself? Yes. The agent has write access to its memory files including HEARTBEAT.md. It will modify the file when you instruct it to ("add a Monday weekly review task") and can modify it autonomously for one-time tasks (marking them complete after execution).

What if a heartbeat task fails? The agent logs the failure and continues to the next task. It will not retry the failed task in the same cycle but will attempt it again in the next heartbeat cycle. For critical tasks, configure a specific failure handling instruction: "If this task fails, immediately alert me via Telegram with the error."

How do I prevent the agent from alerting me constantly? Use quiet hours in config.yaml and configure severity levels in task descriptions. "Alert at any hour if critical. Include in morning briefing if informational." The agent respects these qualifications.

Should I use HEARTBEAT.md for tasks that require my confirmation? Yes — just add a confirmation requirement to the task description. "Review any invoices over $500 in the accounts payable queue. Send me a summary via Telegram and wait for confirmation before approving payment."

Wrapping Up

HEARTBEAT.md is where OpenClaw's proactive intelligence is configured. A thoughtfully designed HEARTBEAT.md file transforms your agent from a reactive assistant into a proactive partner that monitors your world, catches issues before they escalate, compiles the information you need before you ask for it, and takes action autonomously on the tasks you've delegated. Invest time in writing good tasks, specify clear triggers and actions, set appropriate intervals, and your agent will compound that investment every day with autonomous work you never have to think about.