clawhealth：本地化Garmin健康数据同步与自动化分析工具实践

1. 项目概述打造你的本地健康数据中心如果你和我一样手腕上常年戴着一块Garmin手表每天看着它记录步数、心率、睡眠但总觉得这些数据只是躺在Garmin Connect的云端自己没法真正“拥有”和分析那么clawhealth这个项目可能就是你在找的答案。简单来说clawhealth是一个Python工具包它干了一件很酷的事把你Garmin账户里的健康数据一股脑儿同步到你电脑本地的SQLite数据库里然后通过一个简洁的命令行接口CLI或者JSON格式的数据让你能自由地查询、分析和使用这些数据。这不仅仅是简单的数据备份。它的核心设计理念是“CLI优先”和“数据层稳定”。这意味着它首先是一个强大的命令行工具你可以用clawhealth garmin sync这样的命令轻松同步数据用clawhealth daily-summary快速查看某一天的汇总报告。更重要的是它构建了一个稳定、结构化的本地数据层为后续的自动化分析、智能体Agent调用甚至是集成到其他个人数据系统中打下了坚实的基础。想象一下你可以写个脚本每天自动拉取前一天的睡眠和运动数据生成一份个性化的健康简报或者把这些数据喂给本地的大语言模型LLM让它给你一些健康建议——clawhealth就是实现这些想法的桥梁。1.1 核心价值与适用人群这个工具主要解决几个痛点数据自主权、自动化集成和离线分析。Garmin Connect的API虽然强大但直接调用相对复杂且数据分散在各个端点。clawhealth帮你封装了这一切提供了一个统一的、面向自动化的接口。它非常适合以下几类人数据极客和开发者希望将健康数据集成到自己的数据分析流水线、个人仪表盘或自动化脚本中的人。OpenClaw用户如果你已经在使用OpenClaw这个开源AI助手框架clawhealth提供了现成的技能Skill让你能通过聊天界面如Telegram直接查询健康数据。注重隐私的用户所有数据同步和处理都在本地完成你的Garmin凭证和健康数据无需经过任何第三方服务器。希望进行长期趋势分析的用户将数据持久化存储在本地SQLite中方便你使用SQL或其他工具进行跨月、跨年的深度历史分析。接下来我将从一个实际使用者的角度带你从零开始深入clawhealth的配置、核心使用、高级功能并分享一些我踩过坑才总结出来的实操经验。2. 从零开始环境配置与初次登录万事开头难但只要把初始配置理顺了后面的使用就会一马平川。clawhealth的安装非常简单真正的挑战在于如何安全、顺畅地完成与Garmin Connect的首次认证。2.1 安装与基础验证首先确保你的Python版本在3.10或以上。我强烈建议在虚拟环境中操作以避免依赖冲突。# 创建并激活虚拟环境以venv为例 python -m venv .venv source .venv/bin/activate # Linux/macOS # 或 .venv\Scripts\activate # Windows # 升级pip并安装clawhealth python -m pip install --upgrade pip python -m pip install clawhealth安装完成后直接在终端输入clawhealth --help你应该能看到如下输出这证明安装成功usage: clawhealth [-h] {garmin,daily-summary} ... Health data bridge for OpenClaw (CLI-first Garmin hub) positional arguments: {garmin,daily-summary} garmin Garmin-related commands daily-summary Show a summarized view of health metrics for a given date options: -h, --help show this help message and exit2.2 凭证配置安全第一的哲学clawhealth需要通过你的Garmin账号密码来访问数据。如何管理这些敏感信息是关键。项目文档提到了环境变量和密码文件两种方式我这里强烈推荐并详细解释密码文件环境变量的组合方案这是兼顾安全与便利的最佳实践。为什么是密码文件直接在命令行中输入密码--password your_pass会留下历史记录不安全。环境变量CLAWHEALTH_GARMIN_PASSWORD虽然可行但有时在脚本或终端会话中容易意外泄露比如ps aux命令可能看到。将密码存放在一个受权限保护的文件里是最安全的方式之一。实操步骤创建密码文件echo 你的Garmin密码 ~/.config/clawhealth/garmin_password.txt注意请务必将你的Garmin密码替换为真实密码。这里我假设将文件放在~/.config/clawhealth/目录下你可以选择任何你喜欢的、安全的路径。设置严格的文件权限这是至关重要的一步确保只有你能读取这个文件。chmod 600 ~/.config/clawhealth/garmin_password.txt这个chmod 600命令意味着文件所有者拥有读写权限而组用户和其他用户没有任何权限。配置环境变量我们可以将用户名和密码文件路径设为环境变量这样每次运行命令时就不需要重复输入。export CLAWHEALTH_GARMIN_USERNAMEyour_emailexample.com export CLAWHEALTH_GARMIN_PASSWORD_FILE$HOME/.config/clawhealth/garmin_password.txt为了方便你可以将这两行添加到你的shell配置文件如~/.bashrc或~/.zshrc中然后执行source ~/.zshrc使其生效。2.3 首次登录与MFA挑战Garmin Connect默认启用了双因素认证MFA这增加了安全性也使得首次登录clawhealth变成一个两步过程。第一步发起登录请求如果你已经按照上面配置了环境变量登录命令变得极其简单clawhealth garmin login --json如果没有配置环境变量则需要显式指定clawhealth garmin login --username your_emailexample.com --password-file ~/.config/clawhealth/garmin_password.txt --json--json参数让输出格式化为JSON便于机器解析对于自动化脚本非常有用。执行这个命令后clawhealth会尝试登录。由于MFA的存在登录会暂停并在输出中提示你输入MFA验证码。同时你的邮箱或认证APP会收到一个6位数的验证码。第二步提交MFA验证码收到验证码后在另一个终端窗口或同一个会话中运行clawhealth garmin login --mfa-code 123456 --json请将123456替换为你收到的真实验证码。实操心得这里有一个常见的“坑”。clawhealth的登录状态session token会被缓存到本地的一个配置目录下通常是~/.cache/clawhealth/或类似路径。只要这个token有效后续的所有同步、查询命令都无需再输入密码或进行MFA验证。这个token的有效期取决于Garmin的服务端设置可能几天也可能几周。如果某天你发现命令报错提示需要重新登录只需重复上述两步即可。因此在自动化脚本中你需要考虑处理“token过期”的异常情况。登录成功后JSON输出中会包含一个session_file路径这就是缓存的token文件位置。至此最复杂的配置阶段就完成了。3. 核心工作流数据同步与日常摘要查询配置好之后clawhealth的核心价值就体现在两个高频命令上garmin sync同步数据和daily-summary查询摘要。这是你将云端数据“搬”到本地并加以利用的主干道。3.1 数据同步将Garmin数据落地到SQLiteclawhealth garmin sync命令是数据流的起点。它的作用是指定一个日期范围从Garmin Connect下载该范围内所有可用的健康数据并存储到本地的SQLite数据库中。基本用法# 同步最近3天的数据 clawhealth garmin sync --since 2024-05-01 --until 2024-05-03 --json # 同步特定某一天的数据 clawhealth garmin sync --date 2024-05-01 --json # 同步从某天到今天的所有数据慎用数据量可能很大 clawhealth garmin sync --since 2024-01-01 --json命令输出解析执行成功后你会看到一个JSON格式的响应其中几个关键字段需要了解ok:true表示同步成功。synced_dates: 一个数组列出了实际成功同步了数据的日期。这里有个重要细节如果某天你在Garmin上没有数据比如没戴设备这个日期可能不会出现在数组中或者相关字段为null。db: 本地SQLite数据库文件的绝对路径。这是你所有健康数据的“仓库”默认路径通常类似/home/username/.local/share/clawhealth/data/health.db。数据库探秘你可以使用任何SQLite工具如sqlite3命令行、DB Browser for SQLite等打开这个数据库文件。clawhealth使用了名为“UHM”的数据库模式来组织数据。虽然项目文档没有详细展开表结构但通过简单的查询你能发现它按日期、按指标类型睡眠、心率、压力等分表存储结构非常清晰。例如你可以运行sqlite3 ~/.local/share/clawhealth/data/health.db .tables来查看所有表名然后用SELECT * FROM daily_summary LIMIT 1;来查看每日摘要的原始数据格式。这为你后续进行自定义SQL分析打开了大门。3.2 每日摘要为自动化而生JSON接口如果说sync命令是把原材料搬进仓库那么daily-summary命令就是从仓库里取出并打包好的“成品菜”。它针对给定的日期从本地数据库中提取关键健康指标生成一个结构稳定、字段明确的JSON对象。使用方法clawhealth daily-summary --date 2024-05-02 --json输出示例与字段解读{ ok: true, date: 2024-05-02, sleep_total_min: 403, rhr_bpm: 58, steps: 4237, distance_m: 3299.0, calories_total: 1746.0, stress_avg: 42, stress_max: 96, body_battery_start: 43.0, body_battery_end: 5.0, spo2_avg: 98.0, mapping_version: uhm_v1 }这个JSON结构是clawhealth设计的精髓非常适合自动化处理sleep_total_min: 总睡眠时长分钟。403分钟约合6.7小时。rhr_bpm: 静息心率Resting Heart Rate。这是早晨醒来时的心率是心血管健康的重要指标58次/分钟属于较好的范围。steps,distance_m: 步数和距离米。3299米约3.3公里。stress_avg,stress_max: 全天压力分数的平均值和最大值。Garmin的压力分数基于心率变异性HRV数值越高表示压力越大。body_battery_start/end: 身体电量百分比。这是一个综合指标早上数值表示恢复程度晚上数值表示消耗程度。从43到5说明这一天消耗很大。spo2_avg: 平均血氧饱和度。98%是很好的数值。注意事项并非所有设备都支持所有指标。例如血氧SpO2需要特定型号的Garmin设备如Venu系列、Fenix 6/7等并开启该功能。如果你的设备不支持对应字段可能为null或默认值。clawhealth会忠实地反映Garmin Connect提供的数据。自动化脚本示例你可以轻松地写一个Python脚本定期调用这个命令并将结果存储或发送到别处。import subprocess import json from datetime import datetime, timedelta # 获取昨天的日期 yesterday (datetime.now() - timedelta(days1)).strftime(%Y-%m-%d) # 调用clawhealth命令 result subprocess.run( [clawhealth, daily-summary, --date, yesterday, --json], capture_outputTrue, textTrue ) if result.returncode 0: data json.loads(result.stdout) if data.get(ok): print(f昨日({yesterday})健康报告) print(f 睡眠: {data[sleep_total_min]//60}小时{data[sleep_total_min]%60}分钟) print(f 步数: {data[steps]}) print(f 压力平均分: {data[stress_avg]}) # 可以在这里添加将数据写入数据库、发送到通知服务等逻辑 else: print(获取数据失败) else: print(f命令执行错误: {result.stderr})4. 高级功能挖掘超越每日摘要clawhealth的魅力远不止于每日摘要。它提供了一系列“高级命令”让你能获取更原始、更细粒度的数据满足深度分析的需求。这些命令同样遵循--json输出的模式。4.1 睡眠阶段深度分析clawhealth garmin sleep-dump命令可以获取某一天详细的睡眠阶段数据这比daily-summary里的总时长要有用得多。clawhealth garmin sleep-dump --date 2024-05-02 --json这个命令的返回数据量会大很多通常会包含一个sleep_stages数组里面按时间顺序记录了浅睡、深睡、REM快速眼动睡眠和清醒阶段。你可以利用这些数据绘制自己的睡眠阶段图或者计算深睡/REM睡眠的比例这些都是评估睡眠质量的关键。4.2 活动与训练详情对于运动爱好者活动数据是宝藏。clawhealth garmin activities --since ... --until ...列出指定时间范围内的所有活动跑步、骑行、游泳等返回包括活动ID、类型、开始时间、时长、距离、卡路里等基本信息。clawhealth garmin activity-details --activity-id 123456789通过上一步获取的活动ID查询某次活动的详细数据。这可能包含每秒/每米的GPS轨迹、心率、配速、海拔等海量数据是进行运动技术分析的基础。4.3 HRV与身体成分数据HRV数据心率变异性是评估身体恢复状态和压力的黄金指标。clawhealth garmin hrv-dump可以获取某天的HRV详细读数通常是全天或睡眠期间的。身体成分如果你的Garmin智能秤如Index S2并关联了账户clawhealth garmin body-composition可以获取体重、体脂率、肌肉量、骨量等数据。这对于长期追踪健身效果至关重要。4.4 实战技巧组合使用与数据拼接真正的力量来自于组合。例如你可以写一个脚本每周一执行以下操作用sync同步上周的数据。用activities获取上周的所有运动记录筛选出跑步活动。遍历每个跑步活动的ID用activity-details获取详细数据计算平均配速、平均心率等。用daily-summary获取每天的静息心率和身体电量。将运动表现配速与身体状态静息心率、身体电量关联起来分析“身体状态好时是否跑步表现也更好”这样的问题。所有这些操作都基于本地数据库没有API调用次数限制速度也很快。5. 集成与扩展OpenClaw技能与未来展望clawhealth不仅仅是一个独立的CLI工具它还被设计为OpenClaw生态系统中的一块积木。5.1 作为OpenClaw技能使用OpenClaw是一个开源的、可扩展的AI助手框架。clawhealth项目内包含了一个skills/clawhealth-garmin/目录这就是一个现成的OpenClaw技能。安装这个技能后你可以在Telegram等聊天界面中直接与你的健康数据对话。例如你可以对OpenClaw助手说“我昨天的睡眠怎么样” 或者 “帮我查一下上周的平均步数”。助手在背后调用的就是clawhealth daily-summary等命令并将结果以友好的格式回复给你。这对于不习惯命令行的用户来说是一种非常便捷的交互方式。安装通常通过ClawHub进行npx clawhublatest install clawhealth-garmin --force安装后需要在OpenClaw的技能配置目录中按照SKILL.md文件的指引配置好Garmin的凭证同样是密码文件的方式。5.2 架构思考与自定义扩展clawhealth的架构非常清晰数据抓取层对接Garmin API -数据存储层UHM SQLite Schema -数据服务层CLI命令/JSON输出。这种设计使得它具有良好的可扩展性。支持新设备厂商项目路线图ROADMAP.md中提到未来可能支持Huami华米、Xiaomi小米等。从架构上看只需要为新的厂商实现类似garmin模块的数据抓取逻辑并将其数据适配到UHM数据库模式中即可。自定义数据管道本地SQLite数据库是你的。你可以用任何喜欢的工具Python的pandas, R, Jupyter Notebook, Grafana等连接这个数据库进行可视化或复杂分析。clawhealth负责稳定地提供干净的数据。构建自动化健康看板结合cron定时任务定期执行clawhealth garmin sync和数据分析脚本你可以轻松构建一个运行在本地服务器或树莓派上的个人健康数据看板完全私有化。6. 常见问题与故障排查实录在实际使用中你可能会遇到一些问题。以下是我遇到的一些典型情况及其解决方法。6.1 登录与认证问题问题执行clawhealth garmin login时长时间无响应或报错“Login failed”。排查检查网络确保能正常访问Garmin Connect网站。验证凭证确认用户名和密码正确。可以尝试在浏览器中登录Garmin Connect以验证。MFA处理确保你完成了两步登录流程先login再login --mfa-code。有时MFA代码过期很快收到后需尽快输入。清除缓存如果怀疑缓存的session token有问题可以手动删除它。token文件路径通常在JSON登录输出的session_file字段里或位于~/.cache/clawhealth/目录下。删除后重新登录。问题一段时间后同步命令失败提示需要重新认证。解决这是正常的。Garmin的会话令牌会过期。只需重新运行clawhealth garmin login可能需要再次MFA验证即可刷新令牌。6.2 数据同步问题问题clawhealth garmin sync执行成功但synced_dates列表为空或缺少某些日期。排查确认Garmin有数据登录Garmin Connect网页或App检查对应日期是否有数据记录。设备同步确保你的Garmin设备已通过蓝牙或Wi-Fi将数据同步到Garmin Connect云端。clawhealth只能获取云端已有的数据。日期格式确保--since和--until参数的日期格式是YYYY-MM-DD。问题同步速度很慢。解决同步大量历史数据如一年时速度取决于网络和Garmin API的响应。建议初次使用时先同步最近几天数据测试后续可以编写脚本增量同步例如每天凌晨同步前一天的数据。6.3 数据库与数据查询问题问题daily-summary返回的某些字段是null。排查设备支持确认你的Garmin设备是否支持该指标如血氧、身体成分。功能开启在Garmin Connect的设备设置或用户设置中确认相关监测功能已开启例如“脉搏血氧”监测需要在设备上设置为“全天候”或“睡眠期间”。数据完整性有时设备当天未能成功记录某项数据如心率传感器佩戴不良也会导致字段为null。问题我想进行更复杂的查询超出了daily-summary的范围。解决直接使用SQLite客户端连接health.db文件进行查询。首先用.schema命令查看表结构然后编写你自己的SQL语句。例如查询过去7天的平均静息心率SELECT date, rhr_bpm FROM daily_summary WHERE date date(now, -7 days) ORDER BY date;6.4 在自动化脚本中的最佳实践错误处理一定要检查命令的返回值ok字段和标准错误输出stderr。在Python的subprocess.run中检查returncode和解析stderr。日志记录将同步操作、获取摘要的操作记录到日志文件中便于追踪和排错。增量同步不要每次都全量同步。可以记录上次同步的日期每次只同步从那之后的新数据。例如在数据库中记录一个last_sync_date每次同步时--since这个日期。令牌管理在长期运行的自动化服务中需要处理会话过期。一个简单的策略是捕获“需要认证”的错误然后自动触发重新登录流程这可能需要一个安全的MFA代码输入机制对于全自动化有一定挑战。clawhealth项目为我们提供了一个极其优雅且强大的本地健康数据解决方案。它将数据控制权交还给用户并通过精心设计的CLI和JSON接口让自动化变得触手可及。无论是用于简单的每日数据回顾还是作为复杂个人健康分析系统的基石它都表现得游刃有余。我最欣赏的是它“做一件事并做好”的哲学以及清晰的分层架构。如果你对量化自我感兴趣并且不满足于仅停留在智能手表的App界面上那么花点时间折腾一下clawhealth绝对会为你打开一扇新的大门。