diegosouzapw WHOOP Health Data
Access WHOOP health metrics: recovery scores, HRV, sleep analysis, workout strain, and physiological cycles.
Setup
Add tokens to ~/.openclaw/openclaw.json:
{
"skills": {
"entries": {
"whoop": {
"enabled": true,
"env": {
"WHOOP_ACCESS_TOKEN": "your-access-token",
"WHOOP_REFRESH_TOKEN": "your-refresh-token",
"WHOOP_CLIENT_ID": "your-client-id",
"WHOOP_CLIENT_SECRET": "your-client-secret"
}
}
}
}
}
| Variable | Required For | Description |
|---|---|---|
WHOOP_ACCESS_TOKEN |
All API calls | Expires hourly |
WHOOP_REFRESH_TOKEN |
Auto-refresh | Long-lived, get from dashboard |
WHOOP_CLIENT_ID |
Auto-refresh | From WHOOP developer app |
WHOOP_CLIENT_SECRET |
Auto-refresh | From WHOOP developer app |
Get tokens from the WHOOP dashboard. See {baseDir}/references/setup-guide.md.
Commands
User Profile
{baseDir}/scripts/whoop-api.sh profile
Returns: User ID, email, first/last name.
Body Measurements
{baseDir}/scripts/whoop-api.sh body
Returns: Height (m), weight (kg), max heart rate.
Recovery Data
{baseDir}/scripts/whoop-api.sh recovery [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--limit N]
Returns: Recovery score (0-100%), HRV (ms), resting heart rate, SpO2.
Example - Last 7 days:
{baseDir}/scripts/whoop-api.sh recovery --start $(date -v-7d +%Y-%m-%d)
Sleep Data
{baseDir}/scripts/whoop-api.sh sleep [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--limit N]
Returns: Sleep stages, duration, efficiency, performance percentage.
Workout Data
{baseDir}/scripts/whoop-api.sh workouts [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--limit N]
Returns: Workout strain, sport type, heart rate zones, calories.
Physiological Cycles
{baseDir}/scripts/whoop-api.sh cycles [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--limit N]
Returns: Daily strain, average heart rate, calories burned.
Interpreting Scores
Recovery Score (0-100%):
- Green (67-100%): Well recovered, ready for strain
- Yellow (34-66%): Moderate recovery, balance activity
- Red (0-33%): Low recovery, prioritize rest
HRV (Heart Rate Variability):
- Higher values generally indicate better recovery
- Personal baseline matters more than absolute numbers
- Trends over time are most meaningful
Sleep Performance:
- Percentage of sleep needed that was achieved
- 100% = optimal sleep duration for your body
Strain Score (0-21):
- 0-9: Light day
- 10-13: Moderate strain
- 14-17: High strain
- 18-21: All-out effort
Auto-Refresh (Cron Job)
Access tokens expire hourly. Set up a cron job to auto-refresh.
Check if cron already exists:
openclaw cron list | grep -i whoop
If output shows "WHOOP token refresh", cron is already set up - skip to Troubleshooting.
Setup (one-time only):
Ensure all env vars from Setup section are configured.
Ask user for confirmation before creating the cron job.
Create the cron job (runs every 55 minutes to avoid expiry edge cases):
openclaw cron add --name "WHOOP token refresh" \
--cron "*/55 * * * *" \
--session isolated \
--message "Run {baseDir}/scripts/whoop-refresh.sh and update BOTH WHOOP_ACCESS_TOKEN and WHOOP_REFRESH_TOKEN in ~/.openclaw/openclaw.json with the new tokens from the output. Both tokens rotate on each refresh." \
--model anthropic/claude-haiku-4-5
- Verify cron was created:
openclaw cron list | grep -i whoop
- Confirm to user: "WHOOP auto-refresh cron job created. Your token will refresh every 55 minutes automatically."
Troubleshooting
"WHOOP_ACCESS_TOKEN not set":
Set your token in ~/.openclaw/openclaw.json - see Setup above.
401 Unauthorized: Token expired. Run the refresh script or get a new token from the dashboard.
No data returned:
- Check date range parameters
- Ensure WHOOP device synced recently
References
{baseDir}/references/api-endpoints.md- Full API documentation{baseDir}/references/data-structures.md- Response schemas{baseDir}/references/setup-guide.md- How to get an access token