Documentation
Agent Tuning
Heartbeat

Heartbeat

Heartbeat is “periodic awareness”: it runs lightweight routines on a fixed interval in the main session, so the agent can batch small checks into a single turn.

If you need “run at an exact time” (like 9:00 sharp), use Cron instead:

How it works

  • Heartbeat reads HEARTBEAT.md from your workspace (if present) as a short checklist.
  • If there’s nothing to do, the agent should reply with HEARTBEAT_OK (no noise).

Keep HEARTBEAT.md short to avoid wasting tokens every time it runs.

HEARTBEAT.md example

Create or edit ~/.openclaw/workspace/HEARTBEAT.md:

# Heartbeat checklist

- Check for urgent unread messages
- Look for calendar conflicts in the next 2 hours
- If any background jobs finished, summarize in one sentence

Configuration (interval and delivery)

Example config in ~/.openclaw/openclaw.json:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: { start: "08:00", end: "22:00" }
      }
    }
  }
}

If you want heartbeats to include separate Reasoning: output, enable:

  • agents.defaults.heartbeat.includeReasoning: true

Related: /en/docs/tools/thinking/#heartbeats

Memory