OpenClaw / Heartbeat skills

OpenClaw Heartbeat Skills: Configure Agent Health Checks in 5 Minutes

Name: Delx Recovery Protocol
Author: Delx

Heartbeat skills are reusable config blocks that tell an OpenClaw agent how to check its own health. Define intervals, payload shape, session rules, and failure thresholds once, then attach the skill to any agent.

What are heartbeat skills in OpenClaw?

A heartbeat skill wraps the entire health-check lifecycle into a single configuration object. Instead of scattering cron config, payload formatting, and failure logic across your codebase, you declare everything in one place:

Interval — how often the check fires (seconds or cron expression).
Payload template — what data to send (compact or full context).
Session binding — whether to reuse or rotate session IDs.
Failure action — log, alert, or trigger auto-recovery via Delx.

Skills are portable. You write one, test it, and attach it to multiple agents without duplicating configuration.

Template 1: Basic liveness skill

The simplest heartbeat skill. It pings the agent endpoint on a fixed interval and checks for a 200 response. No session persistence, no payload analysis.

{
  "skill_id": "hb-basic-liveness",
  "type": "heartbeat",
  "interval_seconds": 1800,
  "endpoint": "/api/v1/health",
  "method": "GET",
  "expected_status": 200,
  "failure_action": "log",
  "timeout_ms": 5000
}

Good for: non-critical background agents, dev environments.
Limitation: does not track session state or detect degraded performance.

Template 2: Adaptive cadence skill

This skill adjusts its own interval based on the last response. If the agent reports elevated risk, the cadence shortens automatically.

{
  "skill_id": "hb-adaptive-cadence",
  "type": "heartbeat",
  "interval_seconds": 3600,
  "adaptive": {
    "on_risk_high": { "interval_seconds": 300 },
    "on_risk_medium": { "interval_seconds": 900 },
    "on_risk_low": { "interval_seconds": 3600 }
  },
  "endpoint": "/api/v1/session-recap",
  "method": "GET",
  "headers": { "x-delx-mode": "heartbeat" },
  "failure_action": "alert",
  "timeout_ms": 8000
}

Reads risk_level from the DELX_META block in each response.
Automatically escalates cadence during incidents without manual intervention.
Returns to steady-state once risk drops.

Template 3: Session-aware skill

The most robust template. It persists session IDs across calls, includes outcome payloads, and triggers Delx auto-recovery on consecutive failures.

{
  "skill_id": "hb-session-aware",
  "type": "heartbeat",
  "interval_seconds": 900,
  "endpoint": "/api/v1/session-recap",
  "method": "GET",
  "headers": {
    "x-delx-session-id": "{{session_id}}",
    "x-delx-mode": "heartbeat"
  },
  "session": {
    "persist": true,
    "storage": "redis",
    "ttl_seconds": 86400
  },
  "failure_action": "auto-recover",
  "failure_threshold": 3,
  "recovery_endpoint": "https://api.delx.ai/api/v1/mcp",
  "timeout_ms": 10000
}

Maintains session continuity across agent restarts.
After 3 consecutive failures, sends a structured recovery request to Delx.
Stores session state externally (Redis, Postgres, or file-backed).

Configuration reference

Key fields available in every heartbeat skill config:

interval_seconds — base cadence in seconds. Minimum 60 for production.
endpoint — the URL or path to check. Supports {{variables}}.
headers — custom headers. Always include x-delx-mode: heartbeat for lean responses.
failure_action — one of log, alert, or auto-recover.
failure_threshold — consecutive failures before action fires (default: 1).
session.persist — enable cross-restart session ID persistence.
session.storage — where to store session state: redis, postgres, or file.
adaptive — dynamic interval overrides keyed by risk level.
timeout_ms — max wait per check (default: 5000).

Troubleshooting common heartbeat skill issues

Skill fires but session resets every time — confirm session.persist: true and that the storage backend is reachable.
Adaptive cadence never escalates — check that the response includes DELX_META with a valid risk_level field.
Auto-recovery triggers too often — increase failure_threshold from 1 to 3 or raise timeout_ms for slow endpoints.
Duplicate heartbeat calls — ensure you are not running overlapping cron jobs alongside the skill. Use distinct skill_id values per agent.
Payload too large for high-frequency checks — switch to x-delx-mode: heartbeat header to request compact responses.

FAQ

What is a heartbeat skill in OpenClaw?

A heartbeat skill is a reusable configuration block that defines how an OpenClaw agent performs periodic health checks. It specifies the check interval, payload format, session persistence rules, and failure detection thresholds.

How often should heartbeat skills run?

For steady-state monitoring, 30-60 minute intervals work well. During incident recovery, reduce to 5-10 minutes. Critical systems may use 1-2 minute intervals, but keep payloads compact to avoid overhead.

Can I use multiple heartbeat skills on one agent?

Yes. You can stack skills for different concerns, such as a basic liveness skill at 60-minute cadence and a session-aware skill at 15-minute cadence during active incidents. Use distinct skill IDs to avoid conflicts.

What happens when a heartbeat skill detects a failure?

The skill triggers the configured failure action: log-only, alert, or auto-recover. Auto-recover skills invoke the Delx recovery endpoint with the current session context to initiate a structured recovery loop.

Do heartbeat skills persist across agent restarts?

Only if you use the session-aware template with x-delx-session-id persistence. The basic template does not survive restarts. Configure external session storage or use the Delx session-recap endpoint to restore state.

Next: Heartbeat patterns Integration examples