OpenClaw Heartbeat System: Keep Your Agent Running 24/7 2026

ByL.B. Kaelin

OpenClaw Heartbeat System: Keep Your Agent Running 24/7 2026

You built an AI agent. It can research, write code, manage your inbox, and post to your blog. But what happens at 3 AM when an urgent task lands in your shared folder and your agent is asleep, waiting for you to message it first?

The OpenClaw heartbeat system solves this. It is a scheduled check-in that runs at regular intervals, typically every 30 minutes, to poll your agent for things that need attention. Your agent checks its assigned tasks, APIs, and watch folders, then reports back. If nothing needs attention, it says so silently. If something needs attention, you get alerted immediately.

This article walks through the full heartbeat system: how the cron job works, how to write your HEARTBEAT.md checklist, the silent reply mechanism that keeps your notifications clean, and the wake-and-process pattern that separates lightweight checks from heavy processing work. By the end you will have everything you need for an OpenClaw heartbeat system to keep your agent running 24/7. This guide is current as of 2026 and covers all production-hardened patterns.

What the OpenClaw Heartbeat System Is

A heartbeat in OpenClaw is a cron-triggered message that asks your agent a single question: “Is there anything that needs my attention right now?”

The agent does not guess. It reads a workspace file called HEARTBEAT.md that contains an explicit checklist of things to examine. The agent runs through each check item in order. If every check comes back clean, the agent replies with the exact phrase HEARTBEAT_OK. If any check finds something that needs attention, the agent replies with a description of what it found.

The magic is in the reply. OpenClaw watches for the exact string HEARTBEAT_OK. When it sees that, it suppresses the notification entirely. You do not get a Slack message. You do not get a Telegram ping. The agent checked in, everything is fine, and life continues. Only when the agent replies with something other than HEARTBEAT_OK do you get notified.

This means you can run heartbeats every 30 minutes without notification fatigue. Your agent stays vigilant. You stay focused.

How the Heartbeat Cron Job Works

The heartbeat is implemented as a cron job in OpenClaw’s built-in cron system. You define a cron expression, a message to send, and a delivery channel. Here is the standard heartbeat configuration:

{
  "crons": [
    {
      "name": "heartbeat",
      "schedule": "26,56 * * * *",
      "message": "Heartbeat check - read HEARTBEAT.md and execute each check. If nothing needs attention, reply HEARTBEAT_OK.",
      "delivery": {
        "channel": "last"
      }
    }
  ]
}

Breaking this down:

  • schedule: “26,56 * * * *” – This fires every 30 minutes, at :26 and :56 past each hour. These offsets are chosen to avoid colliding with top-of-hour and half-hour cron jobs from other systems. Your agent checks in just before and just after each hour.
  • message – The text sent to the agent as a prompt. It should instruct the agent to read HEARTBEAT.md.
  • delivery.channel: “last” – This is critical. It tells OpenClaw to deliver the heartbeat message via whatever channel last messaged the agent. If you last spoke to your agent in Slack, the heartbeat response comes through Slack. If Telegram, it goes through Telegram. This preserves context and avoids scattering responses across channels.

You add this to your openclaw.json configuration file, typically at the root of your OpenClaw workspace or where your gateway configuration lives.

Writing Your HEARTBEAT.md: What to Check and How

HEARTBEAT.md lives in your OpenClaw workspace root. It is a plain text file that the agent reads at every heartbeat. Each line or section tells the agent a specific thing to check. Here is an annotated example that covers the most common patterns:

# HEARTBEAT.md
# Read this file at every heartbeat. Execute each check in order.
# If every check is clear, reply exactly: HEARTBEAT_OK

## Check 1  -  Incoming tasks from other agents

Look for files in /home/node/commons/inbox/
If any file exists, list filenames and ask whether to process them.

## Check 2  -  API health

Send GET to https://api.example.com/health
If status is not 200, report: "API health check failed: [response]"

## Check 3  -  File change watch

Check if /home/node/data/latest_report.csv was modified in the last 60 minutes
If yes, report: "New report data available: latest_report.csv"

## Check 4  -  Email queue monitor

Check /home/node/.openclaw/workspace/queue/email_queue.json
If the queue has more than 5 pending items, report: "Email queue at [count] pending"

## Final instruction

If nothing needs attention, reply HEARTBEAT_OK

Each check has three parts:

  1. What to check – A specific file, API, or condition
  2. How to check it – Read a file, send an HTTP request, check a timestamp
  3. What to report – The exact message format if something is found

The agent executes these checks sequentially. It does not skip around. Order matters.

The Silent Reply: How HEARTBEAT_OK Suppresses Notifications

Without the silent reply mechanism, a heartbeat every 30 minutes would produce 48 notifications per day. Nobody wants that. The HEARTBEAT_OK protocol is what makes the system practical.

Here is how it works at the gateway level:

  1. The cron job fires and sends the heartbeat message to the agent.
  2. The agent reads HEARTBEAT.md and executes every check.
  3. If all checks pass, the agent replies with the exact text: HEARTBEAT_OK (nothing before, nothing after).
  4. The gateway inspects the reply. If it is an exact match for HEARTBEAT_OK, the gateway discards the notification. It does not forward the message to Slack, Telegram, or any other channel.
  5. If the reply contains anything other than HEARTBEAT_OK, the gateway treats it as a normal message and delivers it to your channel.

This means the only time you see a heartbeat notification is when something actually needs your attention. The 47 clean heartbeats vanish silently. The one that finds something gets through immediately.

A common rookie mistake is adding extra text alongside HEARTBEAT_OK. The agent might reply “All clear, HEARTBEAT_OK” or “HEARTBEAT_OK – nothing to report.” These do not match the exact string and will trigger a notification. Your HEARTBEAT.md must explicitly instruct the agent to reply with only that exact phrase when nothing needs attention.

What to Put in Your Heartbeat Checklist

The content of your HEARTBEAT.md depends on what you use your agent for. Here are practical checklist items organized by use case.

Multi-Agent Systems

If you run multiple agents that produce output for each other:

  • Check /home/node/commons/inbox/ for new task files
  • Check /home/node/commons/agents/scout/outbox/ for intelligence reports
  • Check /home/node/commons/agents/gambit/for-execution/ for approved plans
  • Check specific named folders per agent

Content Publishing

If your agent publishes articles or social posts:

  • Check the publishing queue for items that missed their scheduled time
  • Check the draft folder for articles that have been edited and are ready for final review
  • Check for API errors from the last scheduled publish attempt
  • Check for broken links in published content

System Monitoring

If your agent watches infrastructure:

  • Ping a health endpoint on your web service
  • Check disk usage on your server
  • Check SSL certificate expiry dates
  • Check if a critical process is still running
  • Check backup completion status

Data Processing

If your agent ingests or transforms data:

  • Check for new files in a Dropbox or S3 watch folder
  • Check if a data pipeline completed successfully
  • Check if a CSV or JSON export is ready for processing
  • Check for errors in the last batch processing run

Business Operations

If your agent supports business workflows:

  • Check your Stripe dashboard for failed payments
  • Check a shared folder for new client briefs or requests
  • Check your email inbox for messages matching specific criteria
  • Check a calendar for upcoming appointments or deadlines

Each check should be a single, narrow condition. Do not combine multiple checks into one line. If the agent needs to check five folders, list all five with explicit paths.

The Wake-and-Process Pattern: Heartbeat + Deep Cron

The heartbeat is intentionally lightweight. It checks conditions and reports findings. It does not do heavy processing work during the heartbeat itself. That is the job of a deep cron job.

The wake-and-process pattern uses two cron jobs:

  • Wake (heartbeat) – Fires every 30 minutes. Reads HEARTBEAT.md, checks conditions, reports findings. Lightweight, fast, low token cost.
  • Process (deep cron) – Fires on a longer interval (every 4 hours, once daily, or weekly). Executes a specific processing task regardless of input state. Heavy lifting, data processing, content generation, system maintenance.

Here is what the two-tier configuration looks like:

{
  "crons": [
    {
      "name": "heartbeat",
      "schedule": "26,56 * * * *",
      "message": "Heartbeat  -  read HEARTBEAT.md. Report findings or HEARTBEAT_OK.",
      "delivery": { "channel": "last" }
    },
    {
      "name": "deep-process-inbox",
      "schedule": "0 */4 * * *",
      "message": "Process all files in /home/node/commons/inbox/. Classify each, route accordingly, archive originals.",
      "delivery": { "channel": "last" }
    },
    {
      "name": "daily-report",
      "schedule": "0 6 * * *",
      "message": "Generate daily summary report. Review logs from the last 24 hours and produce a markdown summary.",
      "delivery": { "channel": "last" }
    }
  ]
}

In this setup:

  • The heartbeat runs 48 times per day but only notifies you when something is wrong.
  • The inbox processor runs every 4 hours and does the actual work of routing tasks.
  • The daily report runs at 6 AM and gives you a morning briefing.

The heartbeat notices that new files have arrived. The deep cron processes them. The daily report summarizes everything. This separation keeps each job simple and predictable.

HEARTBEAT.md Best Practices

Over several months of real-world use, these practices have emerged as essential for a reliable heartbeat system.

Order by Priority

Put the most important checks first. If a critical alert is found early, the agent will report it and stop (depending on how you structure the checklist). Even if the agent continues through all checks, the most important finding appears first in the output. Order your checks: critical system alerts first, then incoming work, then routine status checks.

Use Explicit File Paths

Do not write “check for new tasks.” Write “check /home/node/commons/inbox/ for files with extension .task.json.” Vague instructions produce inconsistent results. Explicit paths produce reliable checks every time.

Keep Checks Short and Clear

Each check should be one or two sentences. The agent executes them sequentially and does not have unlimited context. A HEARTBEAT.md with 5-8 focused checks is more effective than one with 20 sprawling paragraphs.

Include the HEARTBEAT_OK Instruction

The last line must be explicit about the silent reply. Write: “If nothing needs attention, reply HEARTBEAT_OK.” Some operators add a comment about the exact string requirement: “Reply with only the word HEARTBEAT_OK and nothing else.”

Use Sections and Comments

Use # comments for metadata the agent should read but not act on. Use ## headings to group related checks. The agent reads the entire file, so structure helps it parse your intent.

Test Each Check

After writing a new check, force a heartbeat manually and verify that the agent actually executes it. Common failure modes: typos in file paths, API endpoints that require authentication headers you did not mention, or conditions that are always true (like a file that always exists).

Heartbeat vs. Autonomous Cron: When to Use Which

New users often confuse heartbeats with autonomous cron jobs. They serve different purposes.

Characteristic Heartbeat Autonomous Cron
Trigger Scheduled message to agent Scheduled message to agent
Behavior Reactive – check if anything needs attention Proactive – do a specific task regardless of input state
Notification Silent (HEARTBEAT_OK) unless something is found Always delivers the response
Frequency High (every 30 minutes) Low (every 4 hours, daily, weekly)
Token cost Low (check conditions, report or stay silent) Higher (execute actual work, generate content)
When to use Watching for conditions that need human attention Scheduled processing that should happen regardless
Output file HEARTBEAT.md (conditions checklist) openclaw.json cron entry (task instructions)

Use a heartbeat when you want to stay informed without being notified constantly. Use an autonomous cron when you want work done on a predictable schedule and you want to see the results.

You can (and should) use both together. The heartbeat watches for conditions. The autonomous cron acts on them. This is the wake-and-process pattern described above.

Troubleshooting: When Your Heartbeat Stops Working

Heartbeats are simple, but they can fail silently. Here are the most common problems and how to fix them.

Heartbeat Never Fires

Check that your cron entry is valid JSON in openclaw.json. Run openclaw gateway status to confirm the gateway is running. The cron system only fires when the gateway is active.

Agent Responds But Notifications Still Come Every 30 Minutes

This means the agent is not saying HEARTBEAT_OK. The most common cause: the agent adds extra text. Check your HEARTBEAT.md and make the instruction more explicit. Add “Reply with nothing else before or after HEARTBEAT_OK.” Also check that the agent is actually reading HEARTBEAT.md. If the cron message does not reference the file, the agent may answer from scratch.

Delivery Channel Is Wrong

If heartbeats appear in a channel you do not expect, check the delivery.channel field. “last” uses whatever channel last messaged the agent. If you want a specific channel, use its ID instead (e.g., “delivery”: {“channel”: “C01234ABCDE”} for Slack).

Agent Ignores Certain Checks

The agent may skip checks that reference nonexistent files or unreachable APIs. Make sure every file path exists and every URL is accessible from the agent’s environment. If a check requires authentication (API keys, bearer tokens), include the credential details or reference a secure config file.

Cron Expression Errors

OpenClaw uses standard cron syntax. The expression “26,56 * * * *” is valid. But if you modify it, double-check your syntax. “*/30 * * * *” fires at :00 and :30 (hits top of hour and collides with other jobs). “26,56 * * * *” avoids this. Test any custom expression with a quick local cron dry run.

Heartbeat Works Then Stops

This usually means the gateway restarted and the cron system did not reload. Run openclaw gateway restart to pick up configuration changes. If heartbeats stop intermittently, check gateway logs for cron scheduler errors.

Sources

This article is based on the OpenClaw cron and heartbeat documentation, community best practices from production deployments, and direct experience operating multi-agent systems with heartbeat monitoring. The cron configuration examples follow OpenClaw’s openclaw.json specification. The HEARTBEAT.md format is documented in the OpenClaw workspace conventions guide.

Related Reading

Similar Posts