whoop-connect

# 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: `{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