Slug Test

Stream and sync iPhone/Apple Watch HealthKit data via a local webhook server for AI analysis, recovery scoring, and health anomaly alerts.

Security Scan

The instructions are internally consistent with streaming Apple Health data, but the skill omits provenance (no source/homepage), instructs you to run npx to fetch and execute a remote package, and recommends exposing sensitive health data via public tunnels — these gaps warrant caution before installing.

Purpose & Capability

The name/description (stream Apple Health data to a local webhook for analysis) aligns with the SKILL.md flow (webhook server, pairing, health-data.jsonl storage). However, the metadata declares no required env vars or install steps while the runtime instructions reference optional env vars (PORT, HEALTHCLAW_DATA_DIR, ADMIN_TOKEN) and an npm package (healthclaw-webhook-server) — that mismatch is an inconsistency in declared requirements vs. runtime needs.

Instruction Scope

The SKILL.md stays on-topic (pairing, sync endpoints, storage, admin API). It does instruct you to expose the server to the public internet (Tailscale Funnel, Cloudflare Tunnel, ngrok) so your device can reach it and to run admin API calls (generate pairing, create users). Those steps are necessary for the stated purpose but increase the exposure of very sensitive health data; the instructions do not provide security defaults (e.g., require ADMIN_TOKEN) nor explicit guidance on safe configuration beyond optional tips.

Install Mechanism

There is no install spec in the registry entry; the instructions tell the user to run `npx healthclaw-webhook-server`, which will download and execute code from the npm registry at runtime. Because no source repository, homepage, release URL, or checksum is provided, there's no provenance or verification step for that code — this is a meaningful installation risk for arbitrary code execution.

Credentials

The skill metadata lists no required environment variables or credentials, but the SKILL.md references optional env vars (PORT, HEALTHCLAW_DATA_DIR, ADMIN_TOKEN) and recommends using third-party tunneling services (Tailscale/ngrok/cloudflared). The lack of declared env vars in the registry combined with runtime reliance on an ADMIN_TOKEN (for admin endpoints) is an inconsistency the user should be aware of. The skill does not request unrelated credentials, but it will require network and tunnel credentials in practice.

Persistence & Privilege

always:false and no code included in the skill bundle mean the skill itself doesn't demand permanent platform-level presence. However, the runtime use-case involves persistent local storage of sensitive health data (health-data.jsonl) and potential continuous services (LaunchAgent/systemd, Tailscale Funnel). Autonomous model invocation is allowed (platform default) — combine that with remote package execution and public exposure raises the blast radius.

What to consider before installing

What to consider before installing or running this: - Provenance: The skill bundle provides no source repository, homepage, or code files; SKILL.md tells you to run `npx healthclaw-webhook-server` which will download and execute code from npm. Before running, find and review the package on npm/GitHub (package name and version), inspect its source, and verify an official author or release artifact. If you cannot verify the upstream source, do not run `npx` on a package handling sensitive health data. - Least privilege and protection: The instructions reference an ADMIN_TOKEN but do not require it. If you run the server, set a strong ADMIN_TOKEN and verify admin endpoints are actually protected. Default or missing admin credentials could allow strangers to pair devices or read users. - Network exposure: The skill recommends exposing your server via Tailscale Funnel / Cloudflare Tunnel / ngrok so an iPhone can reach it. Exposing health data to the public internet substantially increases risk. Prefer Tailscale (authenticated, zero-trust tailnet) over public tunnels; if you must use a tunnel, restrict access, use HTTPS, and rotate pairing tokens frequently. - Sandbox/testing: Run the server in a sandboxed environment (container, dedicated user account, VM) and not on a machine that holds other sensitive secrets. Check what files it writes and what ports it opens before trusting it with real health data. - Data handling: The server stores an append-only JSONL of health records. Ensure filesystem permissions are restricted, encrypt backups if needed, and regularly audit the file for unexpected recipients. Understand how the iOS companion stores/sends tokens. - Things that would increase confidence: a published source repo or GitHub release that you can audit, an official npm package with a known maintainer, checksums/signatures for binaries, or an App Store–published iOS companion app. If the maintainer provides these, re-run the assessment. Given the sensitivity of health data and the lack of provenance for the server code, treat this skill as suspicious until you can confirm the upstream package and review its code/configuration.

HealthClaw Skill

Connect your iPhone/Apple Watch health data to OpenClaw for AI-powered analysis.

HealthClaw streams Apple Health data (heart rate, HRV, sleep, steps, workouts) to your OpenClaw agent via a local webhook server. Once connected, your agent can calculate recovery scores, detect health anomalies, answer questions about your health trends, and proactively alert you when something looks off.

---

How It Works

iPhone / Apple Watch
        ↓  (HealthKit → background sync)
  iOS App (HealthClaw)
        ↓  (HTTPS POST)
  Webhook Server  ←  npx healthclaw-webhook-server
        ↓
  health-data.jsonl  (append-only log)
        ↓
  OpenClaw Agent  (queries, crons, alerts)

Key concepts

Concept	Description
Pairing	One-time setup: server issues a time-limited token (2 min), iOS app scans or opens the deep-link, exchanges it for a permanent API token stored securely on the server
Data sync	iOS app POSTs individual records to /api/health-sync or bulk batches to /api/health-sync/batch. Each record contains a type, value, unit, startDate, endDate, and optional metadata
Deduplication	Every record gets a deterministic ID from (type, startDate, endDate, value). The server keeps a SQLite dedupe index — re-syncing the same data is always safe, duplicates are silently dropped
Storage	All data is appended to health-data.jsonl in a platform-appropriate user directory (~/Library/Application Support/healthclaw-webhook on macOS)

---

Setup

1. Start the webhook server

npx healthclaw-webhook-server

The server starts on port 3000 by default. Keep it running (consider a LaunchAgent / systemd service for persistence).

Optional environment variables:

PORT=3000                         # Server port
HEALTHCLAW_DATA_DIR=~/custom/path # Override data directory
ADMIN_TOKEN=your-secret           # Protect admin endpoints

2. Expose to the internet (for iOS sync)

The iOS app needs to reach your server from outside your local network.

Option A: Tailscale Funnel (recommended)

Tailscale Funnel gives your machine a stable public HTTPS URL tied to your Tailscale domain — no dynamic DNS, no port forwarding needed.

# 1. Install Tailscale and log in (skip if already done)
#    https://tailscale.com/download
tailscale login

# 2. Enable Funnel for port 3000
tailscale funnel --bg 3000

Your public URL will be:

https://<machine-name>.<tailnet-name>.ts.net

To find it:

tailscale funnel status
# or
tailscale status --json | grep DNSName

Note: Funnel runs in the background (--bg). It persists across reboots. To stop it: tailscale funnel --bg --off

Option B: Cloudflare Tunnel

# Install cloudflared: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
cloudflared tunnel --url http://localhost:3000
# Cloudflare prints a randomly-assigned https://xxxxx.trycloudflare.com URL

URLs are ephemeral — you'll need to re-pair the iOS app each time you restart the tunnel.

Option C: ngrok

ngrok http 3000
# ngrok prints a https://xxxxx.ngrok-free.app URL

Same caveat as Cloudflare — URL changes on restart unless you have a paid plan.

Note your public URL — you'll need it in the next step when generating the pairing link.

3. Generate a pairing link

curl -X POST https://your-public-url/admin/generate-pairing

Response:

{
  "pairingToken": "abc123...",
  "deepLink": "healthclaw://pair?url=...&token=...",
  "openUrl": "https://your-public-url/pair/open?token=...",
  "expiresInSeconds": 120
}

Open openUrl on your iPhone, or paste deepLink into Safari. The page has a button that opens the HealthClaw app directly.

Token expires in 2 minutes. If it expires, run the curl command again.

4. Install the iOS app

The HealthClaw iOS companion app handles background HealthKit syncing.

Current status: App is pending App Store review.

TestFlight (beta): https://testflight.apple.com/join/SXDjT6vC

Once installed, open the app and follow the pairing flow. After pairing, the app will sync data automatically in the background — no need to keep it open.

5. Verify the connection

curl https://your-public-url/health
# → { "status": "ok", "paired": true, ... }

Check that data is flowing:

tail -f ~/Library/Application\ Support/healthclaw-webhook/health-data.jsonl

---

Data Format

Each line in health-data.jsonl is a JSON record:

{
  "type": "HeartRate",
  "value": 62,
  "unit": "count/min",
  "startDate": "2025-01-15T07:32:00Z",
  "endDate": "2025-01-15T07:32:00Z",
  "metadata": { "context": "resting" }
}

Common types: HeartRate, RestingHeartRate, HeartRateVariabilitySDNN, StepCount, SleepAnalysis, ActiveEnergyBurned, DistanceWalkingRunning, and more.

---

Use Cases

Example	Description
Recovery Score	Daily HRV + RHR + sleep score with cron job setup
Health Alerts	Proactive anomaly detection with configurable thresholds

---

Multi-User Setup

By default, the server runs in single-user (legacy) mode. To support multiple users (e.g. family members, clients), create users via the Admin API. Each user gets an isolated data directory — no data mixing between users.

Create a user

curl -X POST https://your-public-url/admin/users \
  -H "Content-Type: application/json" \
  -H "x-admin-token: your-secret" \
  -d '{"name": "alice"}'

Response (token is shown once only — save it):

{
  "userId": "usr_a1b2c3d4",
  "token": "64-char-hex-token...",
  "name": "alice",
  "createdAt": "2026-03-14T12:00:00.000Z"
}

List users

curl https://your-public-url/admin/users \
  -H "x-admin-token: your-secret"

Returns [{ userId, name, createdAt }] — tokens are never included in list responses.

Using the token

The returned token is the API key the iOS app uses for syncing. Set it as the x-api-token header when pairing or syncing. Each user's data is automatically routed to their own directory:

{appDataRoot}/users/{userId}/health-data.jsonl
{appDataRoot}/users/{userId}/dedupe.db

Legacy compatibility

The existing single-device permanent token continues to work. Its data stays at the original path ({appDataRoot}/health-data.jsonl). No migration is needed — both modes work side by side.

Reading per-user data (OpenClaw skill integration)

When querying health data for a specific user, read from their per-user path:

# Single (legacy) user — default path
cat ~/Library/Application\ Support/healthclaw-webhook/health-data.jsonl

# Multi-user — per-user path
cat ~/Library/Application\ Support/healthclaw-webhook/users/usr_a1b2c3d4/health-data.jsonl

---

API Reference

Full API spec: webhook-server/docs/API_SPEC.md

Key endpoints:

• GET /health — server status + pairing state
• POST /admin/generate-pairing — create a new pairing link
• POST /api/pair?token=<token> — complete device pairing (called by iOS app)
• POST /api/health-sync — ingest a single record
• POST /api/health-sync/batch — ingest up to 5000 records in one request
• POST /admin/users — create a new user (returns token once)
• GET /admin/users — list all users (no tokens)
• GET /admin/device-info — check paired device metadata