#heartbeat.md purpose

1 messages · Page 1 of 1 (latest)

prisma gate
#

what is the purpose of heartbeat.md and why would i want to run it every 30 minutes? how should i think about it separately from crons that i setup?

ornate yewBOT
opaque pilotBOT
#

Let me pull the relevant docs so I can answer this cleanly.

#

Think of them like this:

  • HEARTBEAT.md = a periodic “check if anything needs attention” note
  • Cron = an exact scheduled job

A heartbeat is just a scheduled main-session turn. Every ~30 minutes, OpenClaw wakes up, reads HEARTBEAT.md if it exists, and decides whether there’s anything worth surfacing. If not, it replies HEARTBEAT_OK and that gets dropped, so it stays quiet.

So the point of HEARTBEAT.md is to give the agent a small recurring checklist, like:

  • check inbox for anything urgent
  • look for upcoming calendar events
  • remind me if a task is overdue
  • nudge me only if something actually matters

Why every 30 minutes?

  • it gives you a general awareness loop
#
  • it batches multiple checks into one turn
  • it does not need exact timing
  • it’s good for “keep an eye on things” rather than “do X at 9:00 sharp”

How to separate it from crons:

Use heartbeat when:

  • approximate timing is fine
  • the agent should use full session context
  • you want monitoring / triage / awareness
  • “only tell me if something is worth my attention”

Use cron when:

  • timing matters
  • you want a real scheduled job
  • you want isolated execution
  • you want reminders/reports/tasks with task records
#

Rule of thumb:

  • “Check stuff regularly and tell me if needed” → heartbeat
  • “Run this exact thing at this exact time” → cron

Examples:

  • “Every 30m, see if I have urgent email or an upcoming meeting” → heartbeat
  • “At 7am every day, send a morning brief” → cron
  • “Remind me in 20 minutes” → cron
  • “Periodically glance at my system and only alert on problems” → heartbeat

Also, if HEARTBEAT.md is empty/header-only, OpenClaw skips it, so you don't pay for useless runs. You can also disable heartbeat entirely with every: "0m".

Docs:

prisma gate
#

yes please give me that starter heartbeat.md. also, using checking the inbox as an example, what are the pros and cons of doing that in heartbeat vs doing it via cron?

opaque pilotBOT
#

Yep. I’d start simple.

Starter HEARTBEAT.md:

# HEARTBEAT.md

Use this for recurring awareness checks.
Stay quiet unless something actually needs attention.

## Checks
- Inbox: look for unread or important messages since the last check.
  Only surface items that are urgent, blocking, or need a reply today.
- Calendar: warn me about events coming up in the next 2 hours.
- Follow-ups: remind me if I owe someone a reply or a promised action.
- Automation health: flag failed cron jobs, stuck tasks, or obvious breakage.
# 

## Output
- Be brief.
- Bundle related items into one update.
- If nothing matters, reply HEARTBEAT_OK.

That gives heartbeat a clear job without making it too rigid.

Inbox check: heartbeat vs cron

Use heartbeat if you want:

  • triage, not a fixed report
  • “only tell me if something matters”
  • inbox awareness combined with calendar / tasks / current context
  • fewer separate jobs to manage
#

Pros

  • Context-aware, it can say “this email matters because you have a meeting in 45 minutes”
  • Quiet by default
  • Batches multiple checks into one pass
  • Natural for “keep an eye on things”

Cons

  • Timing is approximate, not exact
  • No task record
  • Can be skipped/delayed if the main queue is busy
  • Lives closer to your main session context, so less deterministic

Use cron if you want:

  • a fixed inbox summary every hour/day
  • exact timing
  • isolated execution
  • a job you can audit and reason about independently
#

Pros

  • Precise schedule
  • Predictable output
  • Creates task records
  • Easy to send a dedicated digest somewhere specific

Cons

  • Less contextual, especially if isolated
  • Can get spammy if nothing interesting happened
  • More jobs to manage if you also want calendar/tasks/etc.

My rule of thumb

  • “Watch my inbox and interrupt me only when needed” → heartbeat
  • “Send me an inbox digest every morning at 8” → cron

One extra note: for inbox specifically, the best solution can be event-driven stuff like Gmail PubSub/hooks, if you want near-real-time reaction. But between heartbeat and cron, that’s the split.