Whoop Connect

Connect WHOOP wearable to OpenClaw — fetch and store recovery, sleep, HRV, strain, and workout data locally. Use when: user asks about recovery, sleep qualit...

Connect your WHOOP band to OpenClaw so your agent can fetch your recovery, sleep, HRV, strain, and workout data.

Setup (once)

WHOOP does not have a public API. To access your own data, you need to register a personal developer app (free, takes 5 minutes). This gives you OAuth credentials so the skill can read your data on your behalf. All data stays local in ~/.whoop/whoop.db — nothing is uploaded anywhere.

• Register at https://developer.whoop.com (sign in with your WHOOP account, create an app, get Client ID and Client Secret). Full walkthrough: {baseDir}/references/setup-guide.md
• Set env vars: WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET
• First invocation auto-creates config and runs OAuth

When env vars are missing, explain to the user: "WHOOP requires a free developer account to access your data via API. It takes about 5 minutes — I can walk you through it step by step." Then follow {baseDir}/references/setup-guide.md.

If config missing: python3 {baseDir}/scripts/setup.py --init, then ask user's language and python3 {baseDir}/scripts/setup.py --set language=zh (or en). If token missing: python3 {baseDir}/scripts/whoop_client.py auth. If deps missing: bash {baseDir}/scripts/install.sh.

Common commands

• Today's recovery: python3 {baseDir}/scripts/whoop_client.py recovery --days 1
• Last night's sleep: python3 {baseDir}/scripts/whoop_client.py sleep --days 1
• Recent workouts: python3 {baseDir}/scripts/whoop_client.py workout --days 7
• Weekly strain: python3 {baseDir}/scripts/whoop_client.py cycle --days 7
• Multi-day summary: python3 {baseDir}/scripts/whoop_client.py trends --days 7
• Single metric history: python3 {baseDir}/scripts/db.py trends --metric <name> --days N
• Profile: python3 {baseDir}/scripts/whoop_client.py profile
• Body measurements: python3 {baseDir}/scripts/whoop_client.py body
• Force sync: python3 {baseDir}/scripts/daily_sync.py --days 2
• Start auto-sync daemon: python3 {baseDir}/scripts/auto_sync.py
• Single sync check: python3 {baseDir}/scripts/auto_sync.py --once
• Auto-sync with custom interval: python3 {baseDir}/scripts/auto_sync.py --interval 10

Use --json for raw data when combining multiple queries. Use --days N to match user's time range ("this week" = 7, "this month" = 30).

Available metrics: recovery_score, hrv, resting_hr, spo2, skin_temp, strain, sleep_duration, sleep_efficiency, sleep_performance, respiratory_rate

Settings

• Change setting: python3 {baseDir}/scripts/setup.py --set <key>=<value>
• Show config: python3 {baseDir}/scripts/setup.py --show
• Re-run wizard: python3 {baseDir}/scripts/setup.py

Keys: language (en/zh), detail_level (compact/detailed), units (metric/imperial), push_recovery, push_sleep, push_workout, webhook_enabled (bool), webhook_port (int), sync_interval (int, minutes — polling interval when webhook is off, default 5), sync_interval_webhook (int, minutes — fallback interval when webhook is on, default 20), daily_api_limit (int, default 10000)

Users may change settings in natural language (e.g. "switch to Chinese", "use detailed mode"). Map to --set accordingly.

Auto-sync

The skill supports automatic data syncing with adaptive intervals:

• No webhook: polls WHOOP API every sync_interval minutes (default 5) as the primary data source
• Webhook enabled: webhook delivers real-time events; auto-sync polls every sync_interval_webhook minutes (default 20) as fallback
• Dedup: only new, scored records trigger notifications; already-seen data is silently skipped
• API guard: tracks daily API calls and pauses when daily_api_limit (default 10,000) is reached
• Start daemon: python3 {baseDir}/scripts/auto_sync.py
• Single check: python3 {baseDir}/scripts/auto_sync.py --once

Webhook (optional)

For real-time push, set up webhooks — see {baseDir}/references/setup-guide.md § "Optional: Webhook Setup". Set webhook_enabled=true in config. The webhook server writes a heartbeat file so auto-sync can detect if webhook is healthy and reduce polling frequency automatically.

Notes

• Never fabricate health data. If a command returns empty or errors, say so.
• Never expose WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET, or token contents in output.
• Never delete DB files or config without explicit user confirmation.
• Confirm before changing user settings.
• Respect language and detail_level from config.
• If WHOOP API returns 429, the client auto-retries. Do not flood.

Troubleshooting

• ModuleNotFoundError: bash {baseDir}/scripts/install.sh
• WHOOP_CLIENT_ID must be set: check env vars
• No refresh token: python3 {baseDir}/scripts/whoop_client.py auth
• 401 Unauthorized: re-authorize with auth
• 500 Server Error: transient WHOOP-side issue, retry in a few minutes
• Empty results: widen --days; data may not be scored yet

References

• {baseDir}/references/setup-guide.md — New user onboarding + webhook setup
• {baseDir}/references/api-reference.md — WHOOP API v2 field documentation
• {baseDir}/references/webhook-events.md — Webhook event types and payload format
• WHOOP Developer Docs: https://developer.whoop.com/docs/developing/user-data/recovery
• WHOOP API Reference: https://developer.whoop.com/api