Using OpenClaw heartbeat.md

OpenClaw works with a HEARTBEAT.md file. OpenClaw uses this file to automatically carry out tasks at regular intervals, without asking what it should do or when. Think of background tasks (e.g. checking your calendar) or checking in on how you’re doing (e.g. can I help you with anything?). 

In this article, we explain what HEARTBEAT.md is, how to use it, and how to modify it.

What is HEARTBEAT.md?

HEARTBEAT.md is a status file that OpenClaw uses as a “heartbeat”. The idea is simple:

• When OpenClaw is running (or doing periodic work), the heartbeat is executed regularly (at the intervals defined in the HEARTBEAT.md file).
• If the heartbeat is in order, OpenClaw responds with ‘HEARTBEAT_OK’.
• The file is deliberately human-readable (Markdown).

Heartbeat quick start

After the onboarding process, OpenClaw asks you various questions. These questions are used to carry out the initial configuration of your agent, including the ‘heartbeat’. OpenClaw uses the ‘heartbeat’ instruction to perform tasks automatically at regular intervals. You can always adjust the heartbeat later directly in a conversation via a communication channel, for example through WhatsApp. So if you use WhatsApp with OpenClaw, you could simply ask, ‘What instructions does HEARTBEAT.md give you?’, and then continue refining them in the conversation, for example:

Me> What does your HEARTBEAT instruct you to do?
OpenClaw> I'm instructed to provide you a weather update at 9AM every morning
Me> Great! Also check my calendar at 9AM every morning and give me an overview of my appointments.
etc

Please note: The LLM you use for OpenClaw determines how literally OpenClaw interprets your instructions. For example, an instruction such as ‘if nothing urgent, return quietly’ may be taken quite literally. If you ask for a weather update every 3 hours, OpenClaw may, depending on your LLM, interpret that as ‘no weather alert (e.g. a storm approaching)? then I won’t provide any weather update either’.

Where can I find HEARTBEAT.md?

The workspace is the OpenClaw agent’s ‘home’ directory. It is the only folder used for tools and for the workspace context. Keep it private and treat it as memory. This folder is separate from ~/.openclaw/, where configuration files, credentials and sessions are stored.

In OpenClaw installations, you’ll find the workspace in the following directory:

~/.openclaw/workspace/

You’ll also find the HEARTBEAT.md file in this directory, for example:

ls -lah ~/.openclaw/workspace | grep HEARTBEAT

If you use multiple workspaces or profiles, the location may differ. In that case, you can also search more broadly:

find ~/.openclaw -maxdepth 4 -name "HEARTBEAT.md" -print

Viewing and editing HEARTBEAT.md

Open the file, for example:

nano ~/.openclaw/workspace/HEARTBEAT.md

The contents have intentionally been kept simple, and it’s advisable to keep them that way. You can also ask OpenClaw to update HEARTBEAT.md in a conversation, for example via WhatsApp.

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it’s daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask <NAME> next time.

Adjusting heartbeat timing and other options

In addition to the heartbeat content itself, you can also adjust options such as how often the heartbeat instruction is checked. To do so, open the file:

nano ~/.openclaw/openclaw.json

Adjust the following options as required; see the explanation below the code. These are the most commonly used options; you can find a full overview here.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        directPolicy: "allow",
        to: "+15551234567",
        activeHours: { start: "08:00", end: "24:00" },
        includeReasoning: true,
        prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        ackMaxChars: 300,
      },
    },
  },
}