Heartbeat Md

HEARTBEAT.md Configuration Guide

HEARTBEAT.md is a minimal checklist for heartbeat runs — periodic background tasks the agent executes automatically. Keep it SHORT to limit token burn (it's loaded on every heartbeat cycle).

Default Template

# Keep this file empty (or with only comments) to skip heartbeat API calls.
# Add tasks below when you want the agent to check something periodically.

An empty HEARTBEAT.md (or comments only) means NO heartbeat API calls — saves tokens.

Heartbeat Mechanics

• Heartbeats run at intervals configured in openclaw.json:

  {
    "agents": {
      "defaults": {
        "heartbeat": {
          "every": "5m",
          "model": "gpt-4o-mini",
          "lightContext": true,
          "isolatedSession": true
        }
      }
    }
  }
  

• Each heartbeat loads HEARTBEAT.md and executes listed tasks
• State tracking via memory/heartbeat-state.json prevents redundant checks
• Use lightContext: true and a cheaper model to minimize token costs

Example HEARTBEAT.md

# Periodic Checks

- [ ] Check email for new messages (inbox only)
- [ ] Check Telegram mentions in monitored groups
- [ ] Check calendar for upcoming events (next 2 hours)
- [ ] Review standing orders due for execution

# Quiet Hours
No checks between 22:00 and 08:00 (user's timezone)

Standing Orders Integration

HEARTBEAT.md triggers standing order execution. Standing orders live in docs/standing-orders/ and are referenced from AGENTS.md. The heartbeat checks which orders are due.

# Standing Orders Check
- [ ] Read docs/standing-orders/ and execute any programs due
- [ ] Log execution results to memory/YYYY-MM-DD.md

See the standing-orders skill for detailed standing order design patterns.

Token-Efficient Heartbeats

Every heartbeat costs tokens. Minimize cost:

1. Use a cheap model — set heartbeat.model to gpt-4o-mini or similar
2. Keep checklist short — 3-5 items max
3. Use lightContext: true — loads minimal context
4. Set appropriate intervals — don't check every minute unless needed
5. Track state — use heartbeat-state.json to skip already-processed items
6. Define quiet hours — no heartbeats during sleep/off hours

What Data Is Needed

Signals That Improve HEARTBEAT.md

• User asks "did anything happen?" → add relevant monitoring
• User wants periodic reports → add to checklist
• Agent burns tokens on useless checks → remove from checklist
• Missed important event → add monitoring for that event type
• Too many notifications → refine filters, add quiet hours

Common Patterns

Minimal (personal assistant)

- [ ] Check email for urgent messages
- [ ] Calendar: next 2 hours

Moderate (team agent)

- [ ] Check email for new messages
- [ ] Check Telegram mentions
- [ ] Review standing orders
- [ ] Calendar: upcoming meetings today
# Quiet: 22:00-07:00

Comprehensive (monitoring agent)

- [ ] Check email inbox
- [ ] Check all monitored channels for mentions
- [ ] Execute due standing orders from docs/standing-orders/
- [ ] Check system health dashboards
- [ ] Review pending approvals
# Quiet: 00:00-06:00

Best Practices

1. Start with an empty file — add only what's needed
2. Keep to 3-5 checklist items
3. Always define quiet hours
4. Use the cheapest model that can handle the tasks
5. Track state to avoid redundant work
6. Review token costs weekly — remove low-value checks