核心用法
whoop-cli 是一个非官方命令行工具，用于代理友好地访问 WHOOP 可穿戴设备数据。它提供丰富的健康数据查询、趋势分析和实验管理功能，同时强调安全的凭据处理流程。
认证流程：首次使用需在本地 shell 运行 whoop auth login，支持 macOS Keychain、Linux 1Password CLI 或显式 local-vps 存储。代理场景下优先使用只读命令如 summary、day-brief、health、trend 和 sync pull。
数据查询：每日简报 (day-brief)、健康指标摘要 (summary)、训练负荷计划 (strain-plan)、7 天健康标记 (health flags)；活动分析支持 30 天活动列表、趋势分析及按运动类型过滤；数据导出支持 JSONL 格式时间范围拉取。
实验追踪：完整的实验生命周期管理——experiment plan 创建实验并记录假设与成功标准，experiment context 更新元数据，experiment status 查看状态，experiment report 生成结果报告。实验状态严格存储于 ~/.whoop-cli/experiments.json。
显著优点
- 代理友好设计：原生支持
--json --pretty输出，便于程序化解析 - 跨平台安全存储：macOS Keychain、1Password CLI、显式本地存储三档可选
- 实验驱动健康管理：内置假设验证框架，适合生物黑客和自我量化用户
- 智能活动过滤：区分自动检测的泛化活动与确认训练，避免数据误读
- 技能生态集成：一键安装至
~/.agents、Codex 或 OpenClaw 技能目录
潜在缺点与局限性
- 非官方性质：非 WHOOP 官方产品，存在 API 变更或访问中断风险
- 认证门槛：必须本地交互式登录，无法纯云端完成授权
- 平台依赖：macOS 需 Xcode Command Line Tools；Linux 推荐 1Password 增加配置复杂度
- local-vps 风险：明文存储选项需用户显式确认，VPS 入侵场景下存在泄露风险
- 沙箱限制：部分容器化环境无法访问 macOS Keychain，需回退到普通用户权限
适合人群
- 自我量化 (Quantified Self) 爱好者与生物黑客
- 需要程序化访问 WHOOP 数据的开发者与自动化工作流构建者
- 运行训练实验并需结构化追踪的运动员/教练
- 已使用 Codex、OpenClaw 或类似代理框架的技术用户
常规风险
- 凭据泄露：需严格遵守 "不通过聊天粘贴长期密钥" 原则；Telegram 场景下仅传递短期授权 URL
- 数据误读：泛化活动 (
sport_id=-1) 默认不代表 intentional training，训练建议需用--labeled-only过滤 - API 稳定性：非官方集成依赖 WHOOP 私有 API，存在突发变更可能
- 权限管理：Keychain 访问失败时，禁止以命令行参数传递密钥作为回退方案
- 实验状态漂移：强制单文件状态源 (
experiments.json)，避免多副本同步问题