Withings Family技能使用说明

此功能允许您与Withings账户交互，为多位家庭成员获取来自Withings设备（智能秤、睡眠分析仪、活动追踪器等）的全面健康指标。

多用户支持

此功能原生支持多用户，每个用户都有独立的令牌文件：

tokens-alice.json
tokens-bob.json
tokens-charlie.json

每位家庭成员通过OAuth进行一次身份验证。他们的令牌将单独存储并自动刷新。无需复制或切换令牌——只需将用户ID作为第一个参数传递。

python3 scripts/withings.py alice weight
python3 scripts/withings.py bob sleep
python3 scripts/withings.py charlie activity

何时使用此功能

当用户有以下需求时使用此功能：

• 询问其体重或体重历史记录
• 希望查看其身体成分（脂肪百分比、肌肉量、骨量、水分）
• 请求其日常活动数据（步数、距离、消耗卡路里）
• 询问其睡眠数据（时长，质量，深度睡眠，快速眼动睡眠）
• 提及"Withings"或任何Withings设备（Body+、Sleep Analyzer、ScanWatch等）
• 希望追踪他们自己或他们家人的健康状况随时间的变化

设置：创建Withings开发者应用

在使用此技能之前，您需要创建一个免费的Withings开发者应用以获取您的API凭证。

步骤1：创建Withings开发者账户

1. 前往Withings开发者门户
2. 点击注册或登录如果您已有Withings账户
3. 接受开发者服务条款

步骤2：创建您的应用

1. 导航至我的应用→创建应用
2. 填写应用详情：
   • 应用名称：选择一个名称（例如：“我的Moltbot健康”）
   • 描述：简要描述您的用例
   • 联系邮箱：您的邮箱地址
   • 回调URL：http://localhost:18081（OAuth必需）
   • 应用类型：选择“个人使用”或合适的类型
3. 提交应用

步骤3：获取您的凭证

一旦您的应用创建完成：

1. 前往我的应用并选择您的应用
2. 您将找到：
   • 客户端ID→ 设置为WITHINGS_CLIENT_ID环境变量
   • 客户端密钥→ 设为WITHINGS_CLIENT_SECRET环境变量

步骤 4：配置环境变量

将这些添加到您的 Moltbot 环境中：

export WITHINGS_CLIENT_ID="your_client_id_here"
export WITHINGS_CLIENT_SECRET="your_client_secret_here"

或者在~/.openclaw/withings-family/.env（旧路径：~/.moltbot/withings-family/.env）创建一个.env文件：

WITHINGS_CLIENT_ID=your_client_id_here
WITHINGS_CLIENT_SECRET=your_client_secret_here

配置

该技能提供了两个脚本（位于scripts/目录中）：

• scripts/withings_oauth_local.py— 使用本地回调服务器进行自动 OAuth（推荐）
• scripts/withings.py— 主 CLI + 手动 OAuth

凭据存储位置： ~/.openclaw/withings-family/（旧路径：~/.moltbot/withings-family/)

• .env— 客户端ID/密钥（可选，可使用环境变量替代）
• tokens-<用户ID>.json— 每个用户的OAuth令牌（模式600）

在进行任何数据检索之前，请检查用户是否已通过身份验证。如果错误提示"未找到令牌"，请引导该特定用户完成初始身份验证流程。

身份验证方法

方法A：自动OAuth（推荐）

使用本地回调服务器自动捕获授权码：

python3 {baseDir}/scripts/withings_oauth_local.py <userId>

示例：

python3 {baseDir}/scripts/withings_oauth_local.py alice

脚本将：

1. 打印授权URL
2. 在 localhost:18081 启动本地服务器
3. 等待重定向
4. 自动捕获授权码并交换为令牌
5. 将令牌保存至tokens-<用户ID>.json

方法B：手动OAuth

传统的两步流程（请参阅下面的"身份验证"命令）。

可用命令

所有命令遵循以下格式：

python3 {baseDir}/scripts/withings.py <userId> <command> [options]

1. 身份验证

用户首次设置 —— 生成 OAuth URL：

python3 {baseDir}/scripts/withings.py alice auth

用户访问该 URL 并获取授权码后：

python3 {baseDir}/scripts/withings.py alice auth YOUR_CODE_HERE

对每个需要访问权限的家庭成员重复此操作。

2. 获取体重数据

检索最新的体重测量值：

python3 {baseDir}/scripts/withings.py alice weight

以 JSON 格式返回最近的 5 个体重记录。

示例输出：

[
  { "date": "2026-01-17T08:30:00.000Z", "weight": "75.40 kg" },
  { "date": "2026-01-16T08:15:00.000Z", "weight": "75.65 kg" }
]

3. 获取身体成分数据

检索全面的身体指标（脂肪、肌肉、骨骼、水分、BMI）：

python3 {baseDir}/scripts/withings.py alice body

返回最近的 5 次身体成分测量结果。

示例输出：

[
  {
    "date": "2026-01-17T08:30:00.000Z",
    "weight": "75.40 kg",
    "fat_percent": "18.5%",
    "fat_mass": "13.95 kg",
    "muscle_mass": "35.20 kg",
    "bone_mass": "3.10 kg",
    "hydration": "55.2%"
  }
]

4. 获取活动数据

检索每日活动数据（步数、距离、卡路里）：

python3 {baseDir}/scripts/withings.py alice activity

可选指定天数（默认：7）：

python3 {baseDir}/scripts/withings.py alice activity 30

示例输出：

[
  {
    "date": "2026-01-17",
    "steps": 8542,
    "distance": "6.23 km",
    "calories": 2150,
    "active_calories": 450,
    "soft_activity": "45 min",
    "moderate_activity": "22 min",
    "intense_activity": "8 min"
  }
]

5. 获取睡眠数据

检索睡眠数据和质量：

python3 {baseDir}/scripts/withings.py alice sleep

可选指定天数（默认值：7）：

python3 {baseDir}/scripts/withings.py alice sleep 14

示例输出：

[
  {
    "date": "2026-01-17",
    "start": "23:15",
    "end": "07:30",
    "duration": "8h 15min",
    "deep_sleep": "1h 45min",
    "light_sleep": "4h 30min",
    "rem_sleep": "1h 30min",
    "awake": "30min",
    "sleep_score": 82
  }
]

错误处理

常见错误及其解决方法：

注意事项

• 多用户支持：每位家庭成员都有独立的令牌文件（tokens-{用户ID}.json）
• 令牌刷新：令牌过期时会自动刷新
• 授权范围：使用的Withings API授权范围：用户指标、用户活动
• 设备支持：数据可用性取决于用户拥有的Withings设备类型
• 身体成分数据：需要兼容的智能体脂秤（例如Body+、Body Comp型号）