Agent Heartbeat

Unified heartbeat system for OpenClaw agents. Runs parallel health checks, data collectors, and state monitors in one command. Returns a single actionable su...

Security Scan

The skill does what it says (run parallel checks) but it executes arbitrary shell commands with the full environment and writes files — which can read or exfiltrate secrets or host data; the footprint is coherent but materially risky and needs careful review before use.

Purpose & Capability

The name/description match the implementation: the script reads a config and runs configured collectors/health checks in parallel and produces a summary. No unexpected external services, packages, or credentials are declared as required.

Instruction Scope

SKILL.md and the script instruct the agent to read heartbeat.yaml from the workspace and run arbitrary commands (via shell). The script executes those commands with shell: true and inherits process.env, so collectors can call arbitrary network endpoints, run local scripts, read arbitrary workspace files, and include environment variables or inline credentials. The instructions also suggest wiring into cron and running unattended, increasing the blast radius.

Install Mechanism

No install spec — instruction-only with an included Node.js script. Nothing is downloaded from the network by an installer. The risk surface is limited to what the script does at runtime, not an external installer.

Credentials

The skill declares no required env vars but the code runs commands with the full process.env and the docs show examples that use environment variables (e.g., $EMAIL_KEY, $TG_KEY) and header-based API keys. This means the skill can access any secrets present in the agent's environment or config and can send them out via curl or other commands defined in heartbeat.yaml. The lack of declared env requirements is not a protection — it only hides that the script will have access to all env vars.

Persistence & Privilege

always:false (normal). The script writes output and cache files (default research/latest.md and .heartbeat-cache/). Writing to the workspace is expected for a heartbeat, but because collectors are arbitrary commands they could write elsewhere or modify files. The ability for the agent to invoke the skill autonomously (disable-model-invocation:false) combined with cron wiring increases potential for unattended actions; this is expected but relevant to risk.

What to consider before installing

This skill runs whatever shell commands you put in heartbeat.yaml and does so with the agent's full environment and filesystem access. Before installing or scheduling it: 1) audit every heartbeat.yaml you will use — do not include commands that reference unknown URLs or inline keys; 2) remove any sensitive credentials from the agent environment or use dedicated low-privilege service accounts for monitored endpoints; 3) run the script in an isolated environment (container or VM) first to observe behavior; 4) avoid enabling cron/autonomous runs until you trust the config and code; 5) if you must run on a host with secrets, constrain collectors to safe wrappers (or whitelist allowed commands) so they cannot read arbitrary files or exfiltrate data. If you want, I can scan your heartbeat.yaml or the specific collector commands for risky patterns and suggest safer alternatives.

A heartbeat system that runs all your checks in parallel and returns one answer: act or all clear.

Why This Exists

Without a heartbeat system, agents waste tokens gathering information sequentially — checking email, then disk, then uptime, then messages. Each check is a separate tool call, each result needs parsing. Most heartbeats find nothing actionable, but the agent still burns 5-10 minutes every time.

This skill consolidates everything into one 15-second parallel run with a structured summary.

Quick Start

1. Create config

Create heartbeat.yaml in your workspace root:

collectors:
  - name: email
    command: "curl -s https://your-email-api/unread"
    format: json
    alert: ".count > 0"
    summary: "{{.count}} unread emails"

  - name: uptime
    command: "curl -s -o /dev/null -w '%{http_code}' https://your-site.com"
    alert: "!= 200"
    summary: "site returned {{output}}"

health:
  - name: disk
    command: "df -h / | tail -1 | awk '{print $5}' | tr -d '%'"
    warn: "> 80"
    critical: "> 95"

  - name: stale-working
    command: "find WORKING.md -mmin +1440 | head -1"
    alert: "!= ''"
    summary: "WORKING.md not updated in 24h"

settings:
  timeout: 30
  parallel: true
  output: research/latest.md

2. Run heartbeat

node scripts/heartbeat.js

Exit codes:

• 0 — all clear, nothing needs attention
• 1 — error running checks
• 2 — action needed, read the summary

3. Wire into OpenClaw cron

openclaw cron add \
  --name heartbeat \
  --cron "0 * * * *" \
  --message "Run: node path/to/heartbeat.js --brief. If exit 2, read research/latest.md and act on anything flagged. If exit 0, reply HEARTBEAT_OK."

Config Reference

See references/config.md for full config options.

How It Works

1. Reads heartbeat.yaml from workspace root (or path specified with --config)
2. Runs all collectors and health checks in parallel with timeout
3. Evaluates alert conditions against output
4. Writes structured summary to output file
5. Returns exit code: 0 (clear) or 2 (action needed)

The summary is designed for LLM consumption — no logs, no dashboards, just what changed and what needs action.

Adding Custom Collectors

Any command that produces stdout works. The skill evaluates the output against your alert condition:

collectors:
  - name: telegram
    command: "curl -s https://your-logger.workers.dev/messages?unread=true -H 'X-API-Key: secret'"
    format: json
    alert: ".count > 0"
    summary: "{{.count}} new messages in Telegram"

  - name: wallet
    command: "node check-balance.js"
    format: text
    alert: "changed"
    cache: ".heartbeat-cache/wallet.txt"
    summary: "wallet balance changed: {{output}}"

The changed alert type compares current output to the cached previous value — useful for monitoring balances, follower counts, or any value that should trigger on delta.

CLI Options

node scripts/heartbeat.js [options]

  --config <path>    Config file (default: heartbeat.yaml)
  --brief            One-line summary only
  --json             JSON output
  --quiet            Exit code only
  --run <name>       Run single collector by name
  --dry-run          Show what would run without executing