Heartbeat 💓

Build reliable heartbeat playbooks for OpenClaw agents without noisy checks, missed signals, or runaway costs.

Setup

On first use, follow setup.md to capture timezone, active hours, precision needs, and risk tolerance.

When to Use

User wants a better heartbeat file in OpenClaw. Agent audits current heartbeat behavior, designs a safer file, and tunes intervals using real workflow constraints.

Use this for adaptive monitoring, proactive check-ins, and hybrid heartbeat plus cron strategies.

Architecture

Memory lives in ~/heartbeat/. See memory-template.md for the structure and fields.

~/heartbeat/
├── memory.md              # Preferences, cadence profile, and last tuning decisions
├── drafts/                # Candidate heartbeat variants
└── snapshots/             # Previous heartbeat versions for rollback

Quick Reference

Core Rules

1. Scope the heartbeat before writing anything

Define one mission sentence and 1-3 monitored signals first.

If scope is broad, split into explicit sections (critical, important, nice-to-have) and only automate the first two.

2. Keep output contract strict

If nothing actionable is found, heartbeat must return exactly HEARTBEAT_OK.

Do not emit summaries on empty cycles. This prevents noisy loops and keeps heartbeat cheap.

3. Tune cadence with timezone and active hours

Start from OpenClaw defaults and adapt: use a moderate baseline interval, then tighten only during active windows.

Always encode timezone and active hours in the heartbeat file to avoid waking during sleep hours.

4. Use cron for exact timing, heartbeat for adaptive timing

If a task must run at exact wall-clock times, move it to cron.

If a task should react to changing context or event probability, keep it in heartbeat.

5. Add cost guards to every expensive check

Use a two-stage pattern: cheap precheck first, expensive action only on threshold hit.

Never call paid APIs on every heartbeat cycle unless the user explicitly accepts the cost.

6. Define escalation and cooldown rules

Each alert condition must have trigger threshold, escalation route, and cooldown period.

No escalation path means no alert. No cooldown means likely alert spam.

7. Validate with dry runs and rollback path

Before finalizing, run at least one dry simulation against the checklist in qa-checklist.md.

Keep a snapshot of the previous heartbeat so the user can rollback in one step.

Common Traps

• Polling everything every cycle -> high token/API burn with low signal quality.
• Using heartbeat for exact 09:00 jobs -> drift and missed exact-time expectations.
• Missing timezone in heartbeat config -> notifications at the wrong local time.
• No active-hours filter -> overnight wakeups and user fatigue.
• No HEARTBEAT_OK fallback -> verbose no-op loops.
• No cooldown on alerts -> duplicate escalations during noisy incidents.

Security & Privacy

Data that stays local:

• Heartbeat preferences and tuning notes in ~/heartbeat/
• Draft and snapshot files for heartbeat definitions

This skill does NOT:

• Require credentials by default
• Trigger external APIs without user-approved instructions
• Edit unrelated files outside the heartbeat workflow

Related Skills

Install with clawhub install if user confirms:

• schedule - Scheduling patterns for recurring workflows
• monitoring - Monitoring strategies and alert design
• alerts - Alert routing and escalation hygiene
• workflow - Multi-step workflow orchestration
• copilot - Proactive assistant patterns with controlled autonomy

Feedback

• If useful: clawhub star heartbeat
• Stay updated: clawhub sync