Test Skill Xyz999

Connect your iPhone/Apple Watch Apple Health data to OpenClaw via a local webhook to analyze recovery, detect anomalies, and get health alerts.

Security Scan

The skill's instructions generally match its stated purpose (collect Apple Health via a local webhook), but there are notable mismatches and risky operational steps—most importantly it tells you to run npx to fetch/execute a package and references environment/admin tokens that are not declared—so proceed only after verifying the upstream package and the service's code/hosting.

Purpose & Capability

The name/description (connect Apple Health via a local webhook, analyze health data) is consistent with the runtime instructions: running a webhook server, accepting HealthKit POSTs, appending to health-data.jsonl, and letting the agent analyze that file. However, the SKILL.md expects you to run an external npm package (npx healthclaw-webhook-server) and to use admin tokens and tunneling tools; those runtime requirements are not reflected in the skill registry (no required env vars, no install spec).

Instruction Scope

SKILL.md instructs the agent/user to run npx to install/run a server, expose that server to the public internet via Tailscale/Cloudflare/ngrok, generate pairing/admin tokens, and create persistent cron jobs that read health-data.jsonl from the user's Application Support directory. Reading the local health-data.jsonl is coherent with the purpose, but the instructions also assume and instruct access to environment variables (PORT, HEALTHCLAW_DATA_DIR, ADMIN_TOKEN) and to create persistent services and public endpoints — all sensitive operations that extend scope beyond a simple analysis helper. The registry did not declare those env vars.

Install Mechanism

There is no install spec in the registry; instead SKILL.md tells users to run `npx healthclaw-webhook-server`. npx will fetch and execute a package from the npm registry at runtime—this effectively installs/executes third-party code without any supply-chain metadata in the skill. The instructions also recommend installing/using third-party tunneling tools (Tailscale, cloudflared, ngrok). Fetching and running remote packages and enabling public funnels are higher-risk operations and should be justified and audited; the skill provides no upstream repo link or checksum.

Credentials

The registry lists no required env vars, but the instructions reference optional and required values (PORT, HEALTHCLAW_DATA_DIR, ADMIN_TOKEN, per-user API tokens) and describe storing permanent tokens on the server. Requesting and storing admin/user tokens is proportional to a webhook server's operation, but the lack of any declared env requirements in the registry is an inconsistency. Additionally, the instructions imply the use of notification channels (Discord) and creating cron tasks that may require other credentials (Discord webhook/token) which are not described or declared.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. However, SKILL.md encourages making the webhook server persistent (LaunchAgent/systemd), opening a public URL via funnels/tunnels, and storing long-lived API tokens — these are persistent changes to the host environment and increase blast radius if the webhook or its dependencies are compromised. The skill itself does not declare elevated platform privileges, but the recommended operational setup is persistent and network-exposed.

What to consider before installing

Before installing or running this skill: - Do not run `npx healthclaw-webhook-server` unless you inspect the package source and trust its maintainer. npx will fetch and execute code from npm at runtime. - The SKILL.md references ADMIN_TOKEN and other environment variables but the registry declared none — treat admin tokens and stored pairing tokens as sensitive secrets; ensure they are generated and stored securely, and rotate them if you suspect they were exposed. - Exposing your webhook to the public internet (Tailscale Funnel / cloudflared / ngrok) is necessary for mobile sync but increases risk. Prefer Tailscale Funnel (as suggested) or verify TLS and access controls; avoid exposing the server without authentication. - Verify the iOS app provenance (TestFlight/App Store listing and developer identity) before pairing — you will be accepting data from that app. - Review where notifications go (Discord/webhook) and confirm any notification credentials are stored and used safely. - Prefer running the server on a throwaway machine or in an isolated environment until you can audit the upstream package. If possible, request an upstream repository, release hashes, or vendor the code so you can audit it before executing. If you cannot inspect and trust the webhook package and the iOS app, treat this skill as high-risk and do not expose sensitive health data to it.

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