什么是 WHOOP Central？

WHOOP Central 是一项强大的技术集成，旨在直接与 WHOOP v2 API 对接。它允许开发人员和健康爱好者以编程方式检索详细指标，如睡眠阶段、恢复百分比、每日压力和特定锻炼表现。作为 Openclaw Skills 库中的关键条目，它提供了将可穿戴数据转换为个人仪表板或自动记录系统所需的可操作洞察所需的脚本和 OAuth 工作流。

该技能使用 Node.js 构建，专注于为健康数据提供干净、可脚本化的接口。通过使用此类 Openclaw Skills，用户可以超越移动应用程序，将其生物识别数据集成到更广泛的数据科学工作流或私人健康数据库中。

下载入口:https://github.com/openclaw/skills/tree/main/skills/4xiomdev/whoop-central

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

WHOOP Central 应用场景

• 追踪每日恢复评分，以调整训练强度并防止过度训练。
• 分析长期睡眠趋势，包括 REM 和深睡周期，以便更好地管理恢复。
• 将历史锻炼数据导出到自定义分析平台或电子表格。
• 自动检索心率变异性 (HRV) 和静息心率以进行健康监测。
• 基于每日压力和卡路里消耗指标构建自定义通知或仪表板。

1. 用户在 WHOOP 开发者门户上注册开发者应用程序，以获取客户端 ID 和密钥。
2. 使用设置脚本进行初始配置，将凭据存储在本地环境中。
3. 启动 OAuth 2.0 流程，授予该技能访问特定健康范围（睡眠、恢复、锻炼等）的权限。
4. 令牌被安全地存储和管理，该技能提供自动刷新功能以维持连接。
5. 执行特定脚本来查询 API，随后以人类可读的摘要或机器可解析的 JSON 格式返回结构化数据。

WHOOP Central 配置指南

确保您已安装 Node.js 18+ 和 openssl。这是多个需要开发者帐户才能访问 API 的 Openclaw Skills 之一。

# 1. 初始化凭据存储
node src/setup.js

# 2. 通过 OAuth 进行身份验证（Postman 或手动流程）
# 将令牌保存到 ~/.clawdbot/whoop/token.json

# 3. 验证连接
node src/verify.js

# 4. 获取您的第一个数据摘要
node src/summary.js

WHOOP Central 数据架构与分类体系

该技能将数据处理为标准化类别，使其易于与其他 Openclaw Skills 结合使用进行数据可视化。数据点的组织方式如下：

运行批量导入工具时，历史日志存储在 ~/clawd/health/logs/whoop/ 中。

name: whoop
description: WHOOP Central - OAuth + scripts to fetch WHOOP data (sleep, recovery, strain, workouts). Use when user asks about their sleep, recovery score, HRV, strain, or workout data.
version: 1.0.2
metadata:
  clawdbot:
    emoji: "???"
    requires:
      bins: ["node", "openssl"]

WHOOP Central

Access sleep, recovery, strain, and workout data from WHOOP via the v2 API.

Quick Commands

# 1) One-time setup (writes ~/.clawdbot/whoop/credentials.json)
node src/setup.js

# 2) Recommended: Get tokens via Postman (see Auth section), then verify
node src/verify.js
node src/verify.js --refresh

# Prompt-friendly snapshot (includes last workout)
node src/today.js

# Daily summary (all metrics)
node src/summary.js

# Individual metrics
node src/recovery.js
node src/sleep.js
node src/strain.js
node src/workouts.js

# Bulk import to ~/clawd/health/logs/whoop/*
node src/import-historical.js

Data Available

Recovery Score Guide

• ?? 67-100% Green - Ready to perform
• ?? 34-66% Yellow - Moderate readiness
• ?? 0-33% Red - Focus on recovery

Setup

0. Requirements

• Node.js 18+ (this repo uses ESM)
• openssl (only needed for the optional auth.js flow when using https://localhost; Postman auth does not need it)

1. Create WHOOP Developer App

1. Go to https://developer.whoop.com/
2. Sign in with your WHOOP account
3. Create a new App
4. Add these Redirect URIs (exact match; no extra trailing slashes):
   • Postman browser callback (recommended auth path):

     https://oauth.pstmn.io/v1/browser-callback
     

   • Optional local callback (only used by auth.js):

     https://localhost:3000/callback
     

   You can keep both registered at the same time.

5. Copy the Client ID and Client Secret

Team note: this skill does not ship any client credentials. Each user can create their own WHOOP app, or (if you trust each other) a team can share one app's client_id/client_secret and let multiple WHOOP accounts authorize it.

2. Save Credentials (recommended: interactive)

Run:

node src/setup.js

This writes ~/.clawdbot/whoop/credentials.json (and optionally token.json if you paste tokens).

3. Authenticate (Recommended: Postman)

Postman is the most reliable bootstrap for many accounts because WHOOP may block browser-like traffic to the OAuth endpoints (or behave differently depending on headers).

Postman checklist (don’t skip these):

• WHOOP dashboard Redirect URIs include:
  • https://oauth.pstmn.io/v1/browser-callback
• Postman OAuth settings:
  • Scopes include offline (or you won’t get a refresh_token)
  • Client Authentication is Send client credentials in body (client_secret_post)

1. In WHOOP dashboard, ensure you registered the Postman callback Redirect URI:

https://oauth.pstmn.io/v1/browser-callback

2. In Postman:

• Create an Environment and set variables:
  • ClientId = your WHOOP client id
  • ClientSecret = your WHOOP client secret
• Open the WHOOP API collection (or any request), then open the Authorization tab:
  • Type: OAuth 2.0
  • Add auth data to: Request Headers
  • Grant Type: Authorization Code
  • Callback URL: check Authorize using browser
  • Auth URL:

    https://api.prod.whoop.com/oauth/oauth2/auth
    

  • Access Token URL:

    https://api.prod.whoop.com/oauth/oauth2/token
    

  • Client ID: {{ClientId}}
  • Client Secret: {{ClientSecret}}
  • Scope (space-delimited): include offline plus any read scopes you need, e.g.:

    offline read:profile read:sleep read:recovery read:workout read:cycles read:body_measurement
    

  • State: any 8+ chars (e.g. loomingState)
  • Client Authentication: Send client credentials in body

3. Click "Get New Access Token", sign in to WHOOP, and click "Grant".

4. In Postman’s "Manage Access Tokens" modal:

• Click "Use Token" (so requests work)
• IMPORTANT: copy and save both:
  • access_token
  • refresh_token Postman often does not retain the refresh token for you later.

5. Save tokens to ~/.clawdbot/whoop/token.json:

• Use token.example.json as a template
• Set:
  • obtained_at to current time in milliseconds
  • redirect_uri to:

    https://oauth.pstmn.io/v1/browser-callback
    

6. Verify (and test refresh):

node src/verify.js
node src/verify.js --refresh

4. Optional: Authenticate via auth.js (may fail on some accounts)

If you prefer a fully local OAuth loop (and WHOOP allows it), you can use auth.js.

Pre-req: add this redirect URI in WHOOP dashboard:

https://localhost:3000/callback

Run:

WHOOP_REDIRECT_URI='https://localhost:3000/callback' node src/auth.js

If you need to do it from a phone/remote device:

WHOOP_REDIRECT_URI='https://localhost:3000/callback' node src/auth.js --manual

Note: for localhost HTTPS, the script generates a self-signed cert and your browser will show a TLS warning. You must proceed past the warning so the redirect can complete.

4. Verify It Works

node src/verify.js
node src/summary.js

Troubleshooting

Browser shows NotAuthorizedException before the login page

This is a WHOOP-side block on browser User-Agents hitting api.prod.whoop.com OAuth endpoints.

• Use the updated node src/auth.js which bootstraps the login URL and sends your browser directly to id.whoop.com.
• If you still see it, try node src/auth.js --manual and open the printed URL.

"redirect_uri not whitelisted"

1. Go to https://developer.whoop.com/
2. Edit your app
3. Ensure this EXACT URI is in Redirect URIs:

   https://oauth.pstmn.io/v1/browser-callback
   

   If you're using auth.js locally, also add:

   https://localhost:3000/callback
   

4. Save and try again

Token Expired

Tokens auto-refresh on demand (no cron needed). If issues persist:

rm ~/.clawdbot/whoop/token.json
node src/auth.js

"Authorization was not valid"

This usually means your access token is stale/invalidated (common if you re-auth or refresh tokens elsewhere; WHOOP refresh tokens rotate).

• Re-run node src/auth.js, or
• Copy the latest access_token + refresh_token from Postman into ~/.clawdbot/whoop/token.json and update obtained_at.

Auth from Phone/Remote Device

Use manual mode:

node src/auth.js --manual

Open the URL on any device, authorize, then copy the code from the callback URL.

error=request_forbidden / "The request is not allowed"

This is WHOOP rejecting the authorization request after login/consent. Common causes:

• Redirect URI policy (WHOOP docs only mention https:// or whoop:// redirect URIs)
• App/account restrictions (membership/approval/test-user restrictions)
• Scope restrictions (try requesting fewer scopes)

If you suspect redirect URI policy, use an HTTPS tunnel:

# 1) Get a public HTTPS URL that forwards to localhost:3000 (example)
ngrok http 3000

# 2) Add the ngrok HTTPS URL + /callback to WHOOP dashboard Redirect URIs, then run:
WHOOP_REDIRECT_URI=https://YOUR-NGROK-DOMAIN.ngrok-free.app/callback node src/auth.js

If you suspect scope restrictions, try a minimal scope set:

WHOOP_SCOPES="read:profile" node src/auth.js

If your WHOOP Redirect URL is https://localhost:3000/callback

This changes how the local callback server must run: it must be HTTPS (not HTTP).

The script supports this. Run:

WHOOP_REDIRECT_URI=https://localhost:3000/callback node src/auth.js

It will generate a self-signed cert locally and your browser will likely show a warning for https://localhost. Proceed past the warning so the redirect can complete.

JSON Output (for tooling)

These commands support:

• --json (single JSON blob)
• --jsonl (one JSON object per line; useful for piping)
• --limit N (where supported)
• Time filters (where supported): --days N, --since 7d / 12h, --start ISO, --end ISO

node src/summary.js --json
node src/recovery.js --json --limit 1
node src/sleep.js --json --limit 1
node src/strain.js --json --limit 1
node src/workouts.js --json --limit 1

# Examples with filters
node src/sleep.js --json --days 7
node src/workouts.js --jsonl --since 30d
node src/recovery.js --json --start 2026-01-01T00:00:00Z --end 2026-02-01T00:00:00Z

API Notes

• Uses WHOOP Developer API v2
• OAuth 2.0 authentication with refresh tokens
• Scopes: offline, read:recovery, read:sleep, read:workout, read:cycles, read:profile
• Token auto-refreshes when expired