基于 Omi 的 Whoop 集成插件：OAuth 授权、Chat Tools 部署与健身数据查询实战指南

基于 Omi 的 Whoop 集成插件OAuth 授权、Chat Tools 部署与健身数据查询实战指南【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本文以仓库中的 plugins/omi-whoop-app 插件为核心系统讲解如何构建并部署一个接入 Whoop 开发者 API 的 Omi 聊天工具插件从 Whoop 开发者应用创建、Railway 部署、OAuth2 授权回调到七类 Chat Tools 端点与指标解读的完整实现。读完本文你将掌握 Whoop 数据通过自然语言对话接入 Omi 的完整链路并能基于源码定位每个端点的底层数据流。一、插件定位与功能总览plugins/omi-whoop-app是 Omi 生态中的第三方数据集成插件解决的核心问题是把 Whoop 手环产生的恢复、压力、睡眠与训练数据通过 Omi 的 AI 对话能力直接以自然语言查询。用户在聊天中输入我今天恢复得怎么样Omi 的 Chat Tools 机制即可路由到该插件的 HTTP 端点返回结构化的健身数据摘要。其功能清单在 README 中定义如下Recovery Score恢复评分查询每日恢复分数与 HRV心率变异性Strain Score压力评分查看每日压力水平Sleep Data睡眠数据查看睡眠时长、睡眠阶段与睡眠质量Workouts训练记录回顾最近的训练会话Weekly Summary周度总结获取趋势与平均值Body Measurements身体测量数据查看身高、体重、最大心率Profile个人资料访问 Whoop 账户资料信息从实现角度看这是一个基于 FastAPI 的独立 Web 服务见 main.py通过 OAuth2 授权码模式Authorization Code Flow获取 Whoop 用户授权再用访问令牌调用 Whoop Developer API最终以 Omi Chat Tools Manifest 协议对外暴露能力。二、整体架构与 OAuth 数据流2.1 组件拓扑插件由四个核心文件组成职责清晰文件职责main.pyFastAPI 应用OAuth 路由、Chat Tools 端点、数据格式化、Manifest 生成db.py令牌与用户设置存储层Redis 优先本地 JSON 文件兜底models.pyPydantic 响应模型ChatToolResponserailway.tomlRailway 平台部署配置Nixpacks 构建 uvicorn 启动命令requirements.txt依赖清单fastapi、uvicorn、python-dotenv、requests、pydantic、redis2.2 OAuth2 授权码流程整个授权链路在 main.py 中实现包含三个阶段阶段一发起授权GET /auth/whoop?uiduidstate secrets.token_urlsafe(16) store_oauth_state(state, uid) params { client_id: WHOOP_CLIENT_ID, redirect_uri: WHOOP_REDIRECT_URI, response_type: code, scope: .join(WHOOP_SCOPES), state: state } auth_url f{WHOOP_AUTH_URL}?{urlencode(params)} return RedirectResponse(urlauth_url)服务端生成随机state并与用户uid绑定存储10 分钟过期见 db.py用于回调时校验防止 CSRF 攻击。同时携带七项 scopes 发起跳转read:recovery read:cycles read:sleep read:workout read:profile read:body_measurement offline其中offline作用域用于换取refresh_token保证长期免重新授权。阶段二回调换令牌GET /auth/whoop/callbackresponse requests.post( WHOOP_TOKEN_URL, data{ client_id: WHOOP_CLIENT_ID, client_secret: WHOOP_CLIENT_SECRET, code: code, grant_type: authorization_code, redirect_uri: WHOOP_REDIRECT_URI } )用授权码交换access_token、refresh_token与expires_in计算expires_at后经store_whoop_tokens落库随后展示连接成功页。阶段三令牌自动续期每次访问 Whoop API 前都会先经get_valid_access_token检查过期时间提前 5 分钟触发刷新过期则调用refresh_access_token用refresh_token换取新令牌并回写存储main.py。这就是 README 中只需授权一次的底层保障。2.3 令牌存储的双模式设计db.py 实现了生产/开发双存储策略Redis 模式读取REDIS_URL或REDIS_PRIVATE_URL、REDIS_PUBLIC_URL建立连接令牌以whoop:tokens:{uid}为键存储过期时间 90 天OAuth state 键whoop:oauth_state:{state}过期 10 分钟用户设置以whoop:settings:{uid}存储。文件兜底模式Redis 不可用时自动降级为data/目录下的tokens.json、oauth_states.json、user_settings.json三个 JSON 文件便于本地开发。三、从零部署Whoop 开发者应用 Railway3.1 创建 Whoop 开发者应用打开 Whoop 开发者门户Whoop Developer Portal创建新应用填写应用信息名称如 Omi Integration、描述以及回调地址Redirect URI见下文申请以下 scopesread:recovery、read:cycles、read:sleep、read:workout、read:profile、read:body_measurement、offline复制生成的Client ID与Client Secret。注意Whoop 对state参数有至少 8 个字符的长度要求。源码使用secrets.token_urlsafe(16)生成 16 字节随机串并额外做了state - uid的映射存储db.py 注释明确说明这比直接透传 uid 更安全。3.2 部署到 Railway按 README 的步骤在 Railway 创建新项目连接 GitHub 仓库或直接从插件目录部署为项目添加一个Redis服务设置环境变量WHOOP_CLIENT_IDyour_client_id WHOOP_CLIENT_SECRETyour_client_secret WHOOP_REDIRECT_URIhttps://your-app.up.railway.app/auth/whoop/callback触发部署。Railway 会自动完成三件事依据requirements.txt安装依赖依据 railway.toml 启动服务uvicorn main:app --host 0.0.0.0 --port $PORT并使用/health作为健康检查路径超时 100s失败重启最多 3 次自动注入PORT与REDIS_URL环境变量。部署完成后回到 Whoop 开发者应用后台将 Redirect URI 更新为https://your-app.up.railway.app/auth/whoop/callback3.3 环境变量参考表变量说明是否必填WHOOP_CLIENT_IDWhoop OAuth Client ID是WHOOP_CLIENT_SECRETWhoop OAuth Client Secret是WHOOP_REDIRECT_URIOAuth 回调 URL是PORT服务端口默认 8080否REDIS_URLRedis 连接 URL未设置时降级为文件存储否从源码看PORT默认值 8080 与WHOOP_REDIRECT_URI默认值http://localhost:8080/auth/whoop/callback在 main.py 中定义本地开发无需显式设置。此外 db.py 还会读取REDIS_PRIVATE_URL/REDIS_PUBLIC_URL作为备选连接串兼容不同托管平台的 Redis 注入方式。四、Omi App 配置Chat Tools 接入的关键三 URL在 Omi 后台创建/更新应用时需要把以下三个 URL 填入对应字段来自 README字段值Setup URLhttps://your-app.up.railway.app/?uid{{uid}}Setup Completed URLhttps://your-app.up.railway.app/setup/whoop?uid{{uid}}Chat Tools Manifest URLhttps://your-app.up.railway.app/.well-known/omi-tools.json这三个 URL 的底层语义对应三条 GET 路由/带uid访问时渲染连接/已连接页面无uid时返回 JSON 服务信息见 main.py/setup/whoop?uiduid返回{is_setup_completed: true/false}Omi 据此判断用户是否已完成授权main.py/.well-known/omi-tools.jsonChat Tools ManifestOmi 的 AI 层据此发现可用工具及其参数 schemamain.py。4.1 Manifest 如何驱动对话路由Manifest 中每个工具都声明了name、description、endpoint、method、parameters与auth_required。以恢复评分工具为例{ name: get_recovery, description: Get the users recovery score and metrics from Whoop. Use this when the user asks about their recovery, readiness, HRV, or how recovered they are., endpoint: /tools/get_recovery, method: POST, parameters: { properties: { date: { type: string, description: Date in YYYY-MM-DD format. Defaults to today. } }, required: [] }, auth_required: true, status_message: Getting your recovery data... }description是给 LLM 的意图匹配说明书——它显式罗列了用户说 recovery、readiness、HRV、how recovered they are 时应触发该工具这就是自然语言查询能被正确路由的关键机制。status_message则在工具执行期间向用户展示过程反馈。五、API 端点全览5.1 Chat ToolsPOST供 Omi 调用端点功能可传参数/tools/get_recovery恢复评分与 HRVdateYYYY-MM-DD默认今天/tools/get_strain每日压力评分date/tools/get_sleep睡眠数据date获取该日结束的睡眠/tools/get_workouts近期训练记录days默认 7上限 30、max_results默认 10上限 50/tools/get_weekly_summary近 7 天周度总结无/tools/get_body_measurements身体测量数据无/tools/get_profileWhoop 资料无所有工具端点都遵循统一处理模式读取请求体中的uid→ 获取有效访问令牌未授权则返回Please connect your Whoop first in the app settings.→ 构造 Whoop API 请求 → 格式化结果 → 返回ChatToolResponseresult或error二选一见 models.py。5.2 OAuth 与设置GET端点功能/首页 / 设置 UI带uid时渲染 HTML 页面/auth/whoop?uiduid发起 OAuth 流程/auth/whoop/callbackOAuth 回调/setup/whoop?uiduid检查设置完成状态/disconnect?uiduid解除 Whoop 账号绑定删除令牌并重定向回首页/health健康检查Railway 探活用/.well-known/omi-tools.jsonChat Tools Manifest5.3 底层 Whoop API 映射从工具端点的实现可整理出插件调用的 Whoop Developer API基础地址https://api.prod.whoop.com/developer/v1插件端点Whoop API/tools/get_recoveryGET /recovery/tools/get_strainGET /cycle/tools/get_sleepGET /activity/sleep/tools/get_workoutsGET /activity/workout/tools/get_body_measurementsGET /body_measurement/tools/get_profileGET /user/profile/basic日期过滤统一构造为{date}T00:00:00.000Z至{date}T23:59:59.999Z的时间窗口并设置limit取最新一条记录main.py。六、本地开发按 README 的步骤将.env.example复制为.env并填入凭据设置WHOOP_REDIRECT_URIhttp://localhost:8080/auth/whoop/callback在 Whoop 开发者应用后台的 Redirect URI 列表中加入该地址安装依赖pip install -r requirements.txt启动服务python main.py。python main.py会读取PORT默认 8080与HOST默认0.0.0.0并启动 uvicornreloadTrue便于开发调试见 main.py。本地开发时未配置REDIS_URL会自动走 JSON 文件存储无需额外基础设施。七、示例聊天命令部署并授权完成后可在 Omi 聊天中直接输入Whats my recovery today?How did I sleep last night?Whats my strain level?Show my recent workoutsGive me my weekly summaryWhats my HRV?八、Whoop 指标解读8.1 Recovery Score0-100%区间状态含义67-100%绿色恢复充分可承受训练压力34-66%黄色恢复一般谨慎安排训练0-33%红色恢复不足优先休息源码中的分区间逻辑与文档一致 67绿、 34黄、其余红main.py并在结果中附带hrv_rmssd_milliHRV、resting_heart_rate静息心率、spo2_percentage血氧、skin_temp_celsius皮肤温度。8.2 Strain Score0-21区间等级0-9轻度Light day10-13中度Moderate strain14-17高强度High strain18-21过度训练Overreaching极高对应源码分档 18极高、 14高、 10中、其余低main.py并附带千焦自动换算为 kcal系数 0.239006、平均心率与最大心率。8.3 关键指标HRV心率变异性通常越高越好RHR静息心率通常越低越好Sleep Performance睡眠表现满足睡眠需求的程度Sleep Efficiency睡眠效率实际睡眠时间与在床时间之比睡眠结果中还包含分阶段统计浅睡/深睡/REM单位为小时、呼吸频率等由format_sleep从stage_summary中的毫秒值换算main.py。九、源码中的工程化细节9.1 分页兜底周度总结的完整性保证get_weekly_summary需要聚合近 7 天四种数据源码专门实现了whoop_fetch_all_records分页函数main.py循环跟随next_token/nextToken翻页单集合最多 20 页兜底任一页失败即返回(None, error)使调用方能区分空数据与拉取不完整。对应的回归测试在 test_weekly_summary.py 中验证了三种行为翻页聚合两页 recovery50、70平均为 60%两页 workout73总数为 10无续页令牌即停止单页返回即结束分页失败标记为不可用第二页失败时输出**Workouts:** Temporarily unavailable而非错误的 7 条避免把部分结果当最终结果。9.2 分页失败时的降级表现当某类数据拉取失败时周度总结不会整体报错而是对单项输出Temporarily unavailable其余维度照常汇总main.py提升了对话场景下的容错性。9.3 统一的 API 请求封装whoop_api_request统一注入Authorization: Bearer token头并处理错误main.py任何工具端点都无需重复鉴权逻辑get_valid_access_token的 5 分钟提前刷新窗口则降低了对话过程中令牌过期的概率。9.4 多运动类型映射format_workout内置了常见sport_id到运动名称的映射1Running、16Cycling、32HIIT、33Strength Training、48Swimming、71Walking、82Yoga 等未知 ID 显示为Activity {id}main.py。十、常见问题与排查建议Please connect your Whoop first用户未完成 OAuth 授权。检查get_whoop_tokens(uid)是否返回空引导用户访问/页面完成连接。回调报错 / Token exchange failed核对WHOOP_CLIENT_ID、WHOOP_CLIENT_SECRET与WHOOP_REDIRECT_URI是否与 Whoop 开发者后台配置完全一致含协议与路径。Redis 连接失败服务会打印Redis connection failed: ... falling back to file storage并降级为文件存储Railway 上建议确认 Redis 服务已绑定到应用并注入了REDIS_URL。本地 OAuth 无法回调确认.env中WHOOP_REDIRECT_URI为http://localhost:8080/auth/whoop/callback且该地址已加入 Whoop 后台的 Redirect URI 白名单。结语plugins/omi-whoop-app完整演示了 Omi 第三方集成插件的标准范式OAuth2 授权码 刷新令牌续期、Chat Tools Manifest 声明式工具路由、Redis/文件双模式存储、以及面向对话场景的健壮数据聚合。通过本文的部署步骤与源码对照你可以将同样的模式复用到任意具备开放 API 的可穿戴设备或健康平台让健身数据真正开口说话。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考