Device Heartbeat Monitor

Monitor device online status using heartbeat pings to healthchecks.io (free tier).

Architecture

Device → every N min → curl GET → healthchecks.io → missed? → alert user
User asks "device online?" → agent reads state file or queries API → answer

Security Warning

Never share the full ping URL (https://hc-ping.com/UUID) in any chat message. Messaging platforms (Feishu, Slack, etc.) auto-fetch URLs for link previews, which creates false heartbeat pings. Only pass the UUID portion separately.

Quick Commands

Check local status (no API key needed):

bash scripts/status.sh

View recent logs:

tail -20 ~/.openclaw/logs/heartbeat.log

Read state file directly:

cat ~/.openclaw/logs/heartbeat-state.json

Setup

1. Create a Check on healthchecks.io

Register at https://healthchecks.io, create a Check. Set Period = 3 min, Grace = 5 min. See references/healthchecks-setup.md for details.

2. Install heartbeat service

bash scripts/setup.sh "https://hc-ping.com/UUID" 180

• Arg 1: Full ping URL
• Arg 2: Interval in seconds (default 180 = 3 min)
• Installs as macOS LaunchAgent (auto-start on boot, auto-restart on crash)
• Low priority background process, minimal CPU/battery

3. Verify

bash scripts/status.sh

Remote Status Check (from another device)

bash scripts/check.sh "READONLY_API_KEY" "CHECK_UUID"

Response fields: status (up/down/grace), last_ping (timestamp).

Multi-Device Setup

Create a separate Check per device on healthchecks.io. Each device gets its own UUID. Run setup.sh on each device with its unique URL.

Uninstall

bash scripts/uninstall.sh

Features

• Log rotation: Auto-truncates at 500 lines
• State file: ~/.openclaw/logs/heartbeat-state.json for quick local queries
• Recovery detection: Logs "RECOVERED after N failures" on reconnect
• Fail counter: Tracks consecutive failures in state file

Troubleshooting

• Service not running: bash scripts/setup.sh "URL" 180 to reinstall
• Ping failing: Check network; verify URL with curl -v "URL"
• Logs: ~/.openclaw/logs/heartbeat.log and heartbeat-error.log
• False pings from chat platforms: Regenerate UUID, never share full URL in chat