whoop-connect

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: INLINECODE1
• Set env vars: WHOOP_CLIENT_ID, INLINECODE3
• 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: INLINECODE10
• Last night's sleep: INLINECODE11
• Recent workouts: INLINECODE12
• Weekly strain: INLINECODE13
• Multi-day summary: INLINECODE14
• Single metric history: INLINECODE15
• Profile: INLINECODE16
• Body measurements: INLINECODE17
• Force sync: INLINECODE18
• Start auto-sync daemon: INLINECODE19
• Single sync check: INLINECODE20
• Auto-sync with custom interval: INLINECODE21

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, INLINECODE33

Settings

• - Change setting: INLINECODE34
• Show config: INLINECODE35
• Re-run wizard: INLINECODE36

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: INLINECODE52
• Single check: INLINECODE53

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 WHOOPCLIENTID, WHOOPCLIENTSECRET, 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: INLINECODE59
• INLINECODE60: check env vars
• INLINECODE61: INLINECODE62
• INLINECODE63: re-authorize with INLINECODE64
• INLINECODE65: 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
• INLINECODE68 — WHOOP API v2 field documentation
• INLINECODE69 — 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