whoop

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):

1. Ensure all env vars from Setup section are configured.

1. Ask user for confirmation before creating the cron job.

1. 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

1. Verify cron was created:

openclaw cron list | grep -i whoop

1. 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