Design Openclaw Heartbeat Files

---
name: design-openclaw-heartbeat-files
description: "Design better OpenClaw HEARTBEAT.md files with adaptive cadence, safe checks, and cron handoffs for precise schedules."
category: "DevOps & Infra"
author: community
version: "1.0.1"
icon: server
---

# 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.

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

## Quick Reference

| Topic | File |
|-------|------|
| Setup interview | `setup.md` |
| Memory schema | `memory-template.md` |
| Production heartbeat template | `heartbeat-template.md` |
| Practical heartbeat use cases | `use-cases.md` |
| Interval strategy reference | `intervals.md` |
| Trigger strategy reference | `triggers.md` |
| Validation checklist before shipping | `qa-checklist.md` |
| Internet research sources | `sources.md` |

## 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 <slug>` 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`