Heartbeat

Design better OpenClaw HEARTBEAT.md files with adaptive cadence, safe checks, and cron handoffs for precise schedules.

Security Scan

This is an instruction-only skill whose requirements, behavior, and storage are coherent with its stated purpose of helping design HEARTBEAT.md files; it writes local files under ~/heartbeat and does not request credentials or external installs, though some instructions are somewhat open-ended about what to 'audit' which could lead to broader file access if not constrained by user prompts.

Purpose & Capability

The name/description (heartbeat design and templates) match the delivered artifacts (templates, QA checklist, setup flow, memory schema). No unrelated binaries, env vars, or external services are required.

Instruction Scope

SKILL.md and supporting files primarily limit actions to creating and maintaining heartbeat artifacts in ~/heartbeat and running dry-run/checklist validations. However, the instructions say the agent should 'audit current heartbeat behavior' and 'capture current state' if an existing heartbeat file exists — this is reasonable but somewhat open-ended and could be interpreted to read more files or system state if the agent implementation is too permissive. The skill explicitly says it won't call external APIs without user approval.

Install Mechanism

Instruction-only skill with no install steps or downloads; nothing is written to disk by an installer. Low install risk.

Credentials

No required environment variables, no credentials, and no config paths beyond creating/reading ~/heartbeat as documented. Requested scope is proportional to the stated purpose.

Persistence & Privilege

The skill persists data to ~/heartbeat (memory.md, drafts, snapshots) which is expected for this kind of skill. It is not always-enabled and does not declare broader system privileges, but users should be aware it will create and read files in their home directory.

Assessment

This skill appears coherent for building and tuning HEARTBEAT.md files. Before installing: (1) acknowledge that the skill will create and store files under ~/heartbeat (memory, drafts, snapshots); (2) confirm any automatic 'audit' or 'dry run' actions only operate on the existing heartbeat file and not unrelated directories or services; (3) require explicit approval before the agent connects to external systems (inbox, CI, paid APIs, etc.) during validation or simulation; and (4) review the first draft and the QA checklist outputs before enabling any automation or escalation routes. If you want stricter limits, ask the agent to only simulate using synthetic/sample data and to prompt you before reading or writing any files outside a single explicit path.

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

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