Withings Family

此技能允许您与 **多个家庭成员** 的 Withings 账户交互，以便从 Withings 设备（智能秤、睡眠分析器、活动追踪器等）检索全面的健康指标。

## Multi-User Support

此技能通过面向用户的令牌文件原生支持多用户：

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

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

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

## 何时使用此技能

当用户出现以下情况时使用此技能： - 询问他们的 **体重** 或体重历史 - 想要查看他们的 **身体成分**（体脂率、肌肉量、骨量、水分） - 请求他们的 **每日活动**（步数、距离、消耗卡路里） - 询问他们的 **睡眠数据**（时长、质量、深睡眠、REM） - 提到 “Withings” 或任何 Withings 设备（Body+、Sleep Analyzer、ScanWatch 等） - 想要追踪他们或其 **家人** 随时间推移的健康进展

## 设置：创建 Withings 开发者应用

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

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

1. 前往 [Withings Developer Portal](https://developer.withings.com/) 2. 点击 **Sign Up** 或 **Log In**（如果您已有 Withings 账户） 3. 接受开发者服务条款

### 步骤 2：创建您的应用程序

1. 导航至 **My Apps** → **Create an Application** 2. 填写应用程序详细信息： - **Application Name**（应用名称）：选择一个名称（例如 “My Moltbot Health”） - **Description**（描述）：简要描述您的用例 - **Contact Email**（联系邮箱）：您的电子邮件地址 - **Callback URL**（回调 URL）：`http://localhost:18081`（OAuth 必需） - **Application Type**（应用类型）：选择 “Personal Use”（个人使用）或适当的类型 3. 提交应用程序

### 步骤 3：获取您的凭证

创建应用程序后： 1. 前往 **My Apps** 并选择您的应用程序 2. 您将找到： - **Client ID** → 设置为 `WITHINGS_CLIENT_ID` 环境变量 - **Client Secret** → 设置为 `WITHINGS_CLIENT_SECRET` 环境变量

### 步骤 4：配置环境变量

将这些添加到您的 Moltbot 环境中： ```bash export WITHINGS_CLIENT_ID="your_client_id_here" export WITHINGS_CLIENT_SECRET="your_client_secret_here" ```

或在 `~/.openclaw/withings-family/.env` 中创建一个 `.env` 文件（旧版路径：`~/.moltbot/withings-family/.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/密钥（可选，可以使用 ENV 变量代替） - `tokens-<userId>.json` — 每个用户的 OAuth 令牌（模式 600）

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

## 身份验证方法

### 方法 A：自动 OAuth（推荐）

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

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

示例： ```bash python3 {baseDir}/scripts/withings_oauth_local.py alice ```

该脚本将： 1. 打印授权 URL 2. 在 localhost:18081 上启动本地服务器 3. 等待重定向 4. 自动捕获代码并交换令牌 5. 将令牌保存到 `tokens-<userId>.json`

### 方法 B：手动 OAuth

传统的两步流程（请参阅下方的 “Authentication” 命令）。

## 可用命令

所有命令均遵循以下格式： ```bash python3 {baseDir}/scripts/withings.py <userId> <command> [options] ```

### 1. 身份验证

用户的首次设置 — 生成 OAuth URL： ```bash python3 {baseDir}/scripts/withings.py alice auth ```

用户访问 URL 并获取授权代码后： ```bash python3 {baseDir}/scripts/withings.py alice auth YOUR_CODE_HERE ```

为每个需要访问权限的家庭成员重复此步骤。

### 2. 获取体重

检索最新的体重测量数据： ```bash python3 {baseDir}/scripts/withings.py alice weight ```

以 JSON 格式返回 5 条最新的体重记录。

**示例输出：** ```json [ { "date": "2026-01-17T08:30:00.000Z", "weight": "75.40 kg" }, { "date": "2026-01-16T08:15:00.000Z", "weight": "75.65 kg" } ] ```

### 3. 获取身体成分

检索全面的身体指标（脂肪、肌肉、骨骼、水分、BMI）： ```bash python3 {baseDir}/scripts/withings.py alice body ```

返回 5 条最新的身体成分测量数据。

**示例输出：** ```json [ { "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. 获取活动

检索每日活动数据（步数、距离、卡路里）： ```bash python3 {baseDir}/scripts/withings.py alice activity ```

可选择指定天数（默认：7）： ```bash python3 {baseDir}/scripts/withings.py alice activity 30 ```

**示例输出：** ```json [ { "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. 获取睡眠

检索睡眠数据和睡眠质量： ```bash python3 {baseDir}/scripts/withings.py alice sleep ```

可选择指定天数（默认：7）： ```bash python3 {baseDir}/scripts/withings.py alice sleep 14 ```

**示例输出：** ```json [ { "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 } ] ```

## 错误处理

常见错误及其解决方法：

| 错误 | 原因 | 解决方案 | |-------|-------|----------| | "No token found" | 用户未通过身份验证 | 运行 `python3 scripts/withings.py <userId> auth` 并按照 OAuth 流程操作 | | "Failed to refresh token" | 令牌已过期且刷新失败 | 使用 `python3 scripts/withings.py <userId> auth` 重新进行身份验证 | | "API Error Status: 401" | 凭证无效或已过期 | 检查您的 CLIENT_ID 和 CLIENT_SECRET，重新进行身份验证 | | "API Error Status: 503" | Withings API 暂时不可用 | 请稍后重试 | | 数据为空 | 所请求期间内无测量数据 | 用户需要同步其 Withings 设备 |

## 备注

- **多用户：** 每位家庭成员都有自己的令牌文件 (`tokens-{userId}.json`) - **令牌刷新：** 令牌过期时会自动刷新 - **范围：** 使用的 Withings API 范围：`user.metrics`、`user.activity` - **设备支持：** 数据的可用性取决于用户拥有哪些 Withings 设备 - **身体成分：** 需要兼容的智能秤（例如 Body+、Body Comp）