先消除一个误解：WHOOP 没有"开发者账号"这种东西。开发者后台用的就是你现在的
会员账号——登录时会跳到
id.whoop.com，输你平时登 WHOOP App 的邮箱和密码。
你要做的不是"注册"，而是登记一个应用，换回一对钥匙（Client ID / Client Secret）。
暂时没有会员账号？先不用管这里。看板不登录也能用——打开就是演示数据，
所有卡片、词典、运动对照表都能点。等你有了会员账号再回来做下面 7 步，登录永远是可选项，不是门槛。
1登录开发者后台
浏览器打开 developer-dashboard.whoop.com，点 Log in，用会员账号登录（会跳到 id.whoop.com）。
✅ 完成标志：进入后台首页，能看到 Apps、Team 这类菜单。
2建一个 Team（只有第一次要）
第一次进来会提示先建团队：输入团队名（随便写，例如 my-team）→ 点 Create Team。
3创建应用
后台上的英文看不懂？看 开发者后台对照：每个词的中文解释、每个框填什么、哪些按钮别点。
左侧 Apps → 右上角 Create App；或直接打开 apps/create。然后填表：
| 字段 | 填什么 |
|---|---|
| App Name | 随便，例如 whoop-cn，只有你自己看得到 |
| Contact Email | 你的邮箱 |
| Privacy Policy URL | 一个能打开的网页地址。个人自用填你的 GitHub 主页即可；没有就填 https://www.whoop.com/privacy/ |
| Description（如有） | 例如「个人使用的 WHOOP 数据中文看板」 |
4勾选 Scopes（重点）
Scopes 决定能读到哪些数据。至少勾一个，建议下面 6 个全勾：
| 勾 | Scope | 对应页面上的哪块 |
|---|---|---|
| ☑️ | offline | 必须勾。不勾拿不到刷新令牌，一小时后要重新登录 |
| ☑️ | read:profile | 昵称、邮箱 |
| ☑️ | read:recovery | 恢复分数、心率变异性、静息心率、血氧、皮温 |
| ☑️ | read:cycles | 日间负荷、步数、能量消耗 |
| ☑️ | read:sleep | 睡眠时长与四段分期 |
| ☑️ | read:workout | 训练记录 |
⚠️ 少勾一个，对应那张卡片就会是空的，而且不会报错——所以一次勾齐。
5填 Redirect URI（最容易错）
在 Redirect URIs 里填（一个字符都不能差）：
http://localhost:5180/auth/callback它必须和 config.json 里的 redirectUri 完全一样；改过端口的话两边都要改。填完点底部 Create。
✅ 完成标志：页面显示 Client ID 和 Client Secret（Secret 可能要点击"显示"才看得见）。
6把钥匙填回本机
推荐：在网页里直接填 —— 打开 /setup.html，粘贴两个值、点保存即可，不用改文件、不用重启。
也可以手动改项目根目录的 config.json（改完会在下次请求时自动重新读取）：
{
"clientId": "你的 Client ID",
"clientSecret": "你的 Client Secret",
"redirectUri": "http://localhost:5180/auth/callback",
"port": 5180,
"timezone": "Asia/Shanghai",
"scopes": ["offline", "read:profile", "read:recovery", "read:cycles", "read:sleep", "read:workout", "read:body_measurement"]
}
🔒 Client Secret 相当于密码，只放在本机这个文件里。
.gitignore 已经排除了它，别截图发群、别提交到 Git。
7重启 + 连接
- 关掉正在跑服务的黑色窗口（或按
Ctrl + C） - 双击 start.cmd 重新启动
- 打开 看板首页，右上角按钮从「登录（需先配置）」变成「用 WHOOP 账号登录」
- 点 「用 WHOOP 账号登录」
- 在 WHOOP 授权页核对权限 → 点 同意 / Authorize
- 自动跳回，数据就变成你自己的了
✅ 完成标志：右上角徽章变成绿色「已连接 WHOOP」，黄色提示条消失。
多人使用说明：每个浏览器会话各自存自己的令牌，谁也看不到别人的数据。 同一个电脑上换个人用，点「退出登录」再让下一个人用自己的会员账号授权即可。
🤔卡住了看这里
| 现象 | 原因 / 怎么办 |
|---|---|
| 后台说 Redirect URI 无效 | 改成 http://127.0.0.1:5180/auth/callback 再试，同时同步改 config.json |
提示 not_configured | config.json 还是占位符，或改了没重启服务 |
| 提示「state 校验失败」 | 授权页停留超过 10 分钟，重新点连接 |
| 提示 401 / 授权已失效 | 点「断开连接」再连一次 |
| 某个卡片是空的 | 对应 scope 没勾。补勾后要断开重连（scope 在授权那一刻确定） |
| 不是演示数据但没内容 | 新账号在校准期，或那几天没戴设备；睡眠要有过夜佩戴记录 |
👥关于给别人用
- 别人用的也是他们自己的会员账号授权，你的 Client Secret 不会离开你的电脑
- 但当前 App 是 Sandbox 档，最多 10 个会员
- 要接更多人，去后台 Open Request 申请升档（Build 100 → Growth 1000 …），从 Build 起要求当前档位至少 50% 的会员已连接
官方参考：Getting Started · OAuth 2.0 · App Approval