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 at ~/.openclaw/workspace/HEARTBEAT.md. 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 (set via the every field in agents.defaults.heartbeat in your openclaw.json), the first thing the agent does is read this file and process each item as a task. If the file is empty (blank lines and headers only), OpenClaw skips the heartbeat run entirely to save API calls.

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). You can also use the tasks: block inside HEARTBEAT.md to give individual tasks their own intervals — OpenClaw parses this block and only includes tasks that are due on a given tick, skipping the heartbeat entirely if no tasks are due. This lets you run server checks every 15 minutes while your morning briefing runs once per day, all from a single HEARTBEAT.md file. Set lightContext: true and isolatedSession: true in your heartbeat config to reduce per-tick token usage from ~100K to ~2–5K tokens.

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: The target field in your heartbeat config defaults to "none" — meaning no delivery. You must explicitly set it to "telegram", "whatsapp", "last", or another channel name. Also specify the channel in your HEARTBEAT.md tasks for clarity: "Alert me via Telegram" rather than just "alert me."
• Ignoring active hours: Without activeHours configured in your heartbeat config (learn more), you'll get 2 AM alerts for non-critical items. Set activeHours.start, activeHours.end, and activeHours.timezone in agents.defaults.heartbeat.
• 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? The heartbeat system has a built-in suppression mechanism: the agent replies with HEARTBEAT_OK when nothing needs attention, and the Gateway drops the message silently (as long as the remaining content is under ackMaxChars, which defaults to 300 characters). You can also configure activeHours in your heartbeat config to restrict when heartbeat runs. For finer control, configure severity levels in task descriptions: "Alert at any hour if critical. Include in morning briefing if informational."

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.