Apple Watch Health Sync
by @lainnet-42
Apple Watch health data sync via Health Auto Export app. Use when querying sleep, heart rate, steps, workouts, or any health metrics. Also use when setting u...
clawhub install apple-watch📖 About This Skill
name: apple-watch description: | Apple Watch health data sync via Health Auto Export app. Use when querying sleep, heart rate, steps, workouts, or any health metrics. Also use when setting up or troubleshooting the health data pipeline. metadata: {"openclaw":{"requires":{"bins":["python"]}}}
Agent Instructions
This skill has TWO parts: PC setup (automated) and Phone setup (requires user action). Do NOT just run setup.py and say "done". You MUST walk the user through the full flow.
Before setup: confirm prerequisites with user
Ask the user to confirm ALL of these before proceeding:
If any is missing, help them resolve it first. Do NOT run setup.py until all are confirmed.
Setup flow
Step 1: Run setup.py
Runpython scripts/setup.py - generates server, dashboard, API key, and phone templates.
setup.py does NOT start the server. You must start it yourself in step 2.Step 2: Start server as a persistent background service
The server MUST run independently of any agent session. Do NOT start it in an exec session that will get killed by heartbeat or session recycling.
Windows - register as a startup task:
$action = New-ScheduledTaskAction -Execute "pythonw.exe" -Argument "server.py" -WorkingDirectory ""
$trigger = New-ScheduledTaskTrigger -AtLogon
Register-ScheduledTask -TaskName "HealthSyncServer" -Action $action -Trigger $trigger -RunLevel Highest -Force
Start-ScheduledTask -TaskName "HealthSyncServer"
macOS - use launchd plist:
cat > ~/Library/LaunchAgents/com.health-sync.server.plist << 'EOF'
Label com.health-sync.server
ProgramArguments
python3 server.py
WorkingDirectory HEALTH_SYNC_DIR
RunAtLoad KeepAlive StandardOutPath HEALTH_SYNC_DIR/server.log
StandardErrorPath HEALTH_SYNC_DIR/server.log
EOF
replace HEALTH_SYNC_DIR with actual path, then:
launchctl load ~/Library/LaunchAgents/com.health-sync.server.plist
Quick start (if you just need it running now, not persistent):
# Windows
start /B pythonw.exe server.py
macOS / Linux
nohup python3 server.py > server.log 2>&1 &
Before starting, kill anything already on port 3001:
# Windows
(Get-NetTCPConnection -LocalPort 3001 -State Listen -ErrorAction SilentlyContinue).OwningProcess | ForEach-Object { Stop-Process -Id $_ -Force }
# macOS / Linux
lsof -ti:3001 | xargs kill -9 2>/dev/null
Verify it's running:
curl.exe -s -H "api-key: " http://localhost:3001/api/summary
curl.exe (not curl which is a PowerShell alias for Invoke-WebRequest).Step 3: Phone side (YOU MUST GUIDE THE USER STEP by STEP，once confirm one step is ready then move on to the another)
After server is running, walk the user through phone configuration. Read the API key from .env.json first - you will need to tell the user. SEND THE FILE TO USER.1. Send the template JSON from templates/ to the user's iPhone. If your IM channel supports file attachments, send the file directly. Otherwise, paste the key settings as text.
2. Tell the user to open the file on iPhone to import into Health Auto Export. SEND tutorial_imgs/step1.png with your message TO USER
- This auto-fills URL, metrics, format, and sync settings.
3. CRITICAL: Tell the user to manually add the API key header after import. SEND tutorial_imgs/step2.png.with your message TO USER
- Open the imported automation -> scroll to Headers -> tap "Add Header"
- Key (left field): api-key
- Value (right field): the API key from .env.json
- Template import does NOT set headers. The user MUST do this step manually.(format: Key：xxx, Value：sk-xxx)
4. Tell the user to tap "Manual Export" to test. SEND tutorial_imgs/step3.pngwith your message TO USER
5. Verify data arrives: check /api/summary or /dashboard.
6. Only after data is confirmed arriving, tell the user setup is complete.
Fallback: if the user is confused by the template import flow, fall back to fully manual setup (Automations -> + -> REST API -> enter URL and header by hand). Only use this fallback when necessary.
If already set up
If server.py and .env.json already exist: 1. Check if server is running on port 3001. 2. If running, check if data is flowing (/api/summary). 3. If yes, skip setup. If no, troubleshoot (server running? correct API key? phone on same WiFi?).Querying health data for the user
When the user asks about their health (sleep, heart rate, steps, etc.):
1. Read the API key from .env.json.
2. Query the API using curl.exe (NOT curl on Windows):
curl.exe -s -H "api-key: " "http://localhost:3001/api/latest/metrics/sleep_analysis?n=3"
curl.exe -s -H "api-key: " "http://localhost:3001/api/latest/metrics/heart_rate?n=5"
curl.exe -s -H "api-key: " http://localhost:3001/api/summary
Dashboard screenshots
When the user wants to see their health stats visually, or you want to proactively show a summary: 1. Open http://localhost:3001/dashboard in a browser or take a screenshot. 2. The dashboard shows cards for each metric with latest values and record counts. 3. Screenshot the dashboard and send it to the user as a visual health summary.
Heartbeat integration
You can use your native heartbeat capability to periodically check the user's health data (e.g. detect wake-up, monitor heart rate). Add health check tasks to HEARTBEAT.md.
Example HEARTBEAT.md entry:
## Health Check
Query: curl.exe -s -H "api-key: " "http://localhost:3001/api/latest/metrics/sleep_analysis?n=1"
Query: curl.exe -s -H "api-key: " "http://localhost:3001/api/latest/metrics/heart_rate?n=1"
If sleep ended within last 2 hours: send wake-up greeting with sleep duration
If no data or server not responding: reply HEARTBEAT_OK (do NOT try to restart server)
IMPORTANT for heartbeat:
curl.exe not curl on Windows (avoid PowerShell alias issues).Health Sync
Sync Apple Watch health data to your PC in real time.
What you need
Hardware:
Software (phone side):
Software (PC side):
How it works
Apple Watch -> iPhone HealthKit -> Health Auto Export app -> HTTP POST -> Python server -> JSONL files
Your iPhone periodically sends health data as JSON to a lightweight Python server running on your PC. The server stores everything as append-only JSONL files, queryable via REST API.
One Click Setup
python scripts/setup.py
No git account needed. No Docker needed. Flask is auto-installed if missing.
Setup will: 1. Auto-install flask (if not already installed) 2. Generate a random API key -> .env.json (gitignored) 3. Download upstream repo (reference + optional Grafana dashboards) 4. Generate lightweight Python server 5. Generate web dashboard 6. Let you pick data types, generate phone automation templates 7. Print step-by-step phone configuration
Phone Setup (after running setup.py)
1. Send the template JSON from templates/ to your iPhone (AirDrop, email, etc.)
2. Open the file on iPhone -> import into Health Auto Export
- This sets URL, metrics, format, sync interval etc. automatically
3. Manually add the API key header (template import does NOT set headers):
- Open the imported automation -> scroll to Headers -> tap "Add Header"
- Key (left field): api-key
- Value (right field): your API key from .env.json (setup.py prints this)
4. Tap Manual Export to test
5. Check http://localhost:3001/dashboard for data
Keep server running
The server must stay running to receive data from your phone.
Windows - scheduled task (survives reboot):
$action = New-ScheduledTaskAction -Execute "pythonw.exe" -Argument "server.py" -WorkingDirectory ""
$trigger = New-ScheduledTaskTrigger -AtLogon
Register-ScheduledTask -TaskName "HealthSyncServer" -Action $action -Trigger $trigger -RunLevel Highest -Force
macOS - launchd (survives reboot):
# create plist at ~/Library/LaunchAgents/com.health-sync.server.plist
see Agent Instructions section for full plist template
launchctl load ~/Library/LaunchAgents/com.health-sync.server.plist
Quick (non-persistent):
# Windows
start /B pythonw.exe server.py
macOS / Linux
nohup python3 server.py > server.log 2>&1 &
Directory Structure
health-sync/
SKILL.md <- this file
scripts/setup.py <- one click setup
server.py <- receiver server (generated)
dashboard.html <- web dashboard (generated)
.env.json <- API key (auto-generated, gitignored)
.gitignore <- ignores .env.json, data/, upstream/
data/ <- received health data
metrics/ <- heart_rate.jsonl, sleep_analysis.jsonl, ...
workouts/ <- workouts.jsonl
templates/ <- phone automation config JSONs (importable)
upstream/ <- original repo (Grafana dashboards, Docker setup)
Server
python server.py
Query data
API key is in .env.json (generated by setup.py). Use curl.exe on Windows:
# get your api key
python -c "import json; print(json.load(open('.env.json'))['api_key'])"summary of all data
curl.exe -s -H "api-key: YOUR_KEY" http://localhost:3001/api/summarylatest N records
curl.exe -s -H "api-key: YOUR_KEY" "http://localhost:3001/api/latest/metrics/sleep_analysis?n=5"
curl.exe -s -H "api-key: YOUR_KEY" "http://localhost:3001/api/latest/metrics/heart_rate?n=10"
curl.exe -s -H "api-key: YOUR_KEY" "http://localhost:3001/api/latest/metrics/step_count?n=10"