Garmin Connect

核心用法

Garmin Connect Skill 是一款专为 Clawdbot 设计的本地健身数据同步工具。用户通过 OAuth 一次性认证后，系统每 5 分钟自动拉取 Garmin Connect 的全量健康数据，包括日常活动（步数、静息心率、卡路里、活动时长）、睡眠分析（时长、质量分数、深浅REM睡眠阶段）以及近期运动记录（类型、距离、时长、心率区间）。数据以 JSON 格式本地缓存，提供 Python API 供 Clawdbot 调用。

显著优点

1. 隐私优先设计：OAuth 认证替代密码存储，session 文件仅存于本地 ~/.garth/session.json，无云端传输风险
2. 数据完整性：覆盖 Garmin 生态核心指标，睡眠阶段细分到 deep/REM/light，运动记录包含心率极值
3. 自动化程度高：cron 定时任务实现准实时同步，无需手动干预
4. 扩展友好：模块化架构（auth/sync/formatter 分离），支持多用户场景

潜在局限与风险

• 2FA 冲突：官方明确建议禁用双因素认证或使用应用专用密码，对安全敏感用户存在张力
• 无官方 API：依赖非官方库（推测为 garth/garminconnect-ha），存在服务协议灰色地带及接口变更风险
• 本地单点故障：缓存文件损坏或 cron 失效时无告警机制
• 频率限制未量化：仅提示"wait 5 minutes"，缺乏具体限流策略文档

适合人群

Garmin 设备长期用户、自建量化健康系统的极客、对厂商云同步有隐私顾虑的数据主权倡导者，以及需要结构化健康数据输入 AI 工作流的 Clawdbot 用户。

常规风险提示

OAuth token 虽本地存储，但明文 JSON 文件需配合文件系统权限管控（建议 600）。cron 脚本路径硬编码为 /home/user，多用户部署需手动调整。依赖第三方库的安全更新需人工跟踪。

核心用法

Garmin Connect Skill 是一款面向 Clawdbot 用户的健身数据同步工具，通过 OAuth 安全认证实现与 Garmin Connect 的深度集成。用户只需一次性完成邮箱密码认证，即可建立本地会话并开启每 5 分钟自动同步。支持三大核心数据维度：日常活动（步数、静息心率、卡路里、活跃时长、移动距离）、睡眠分析（总时长、质量评分、深睡/REM/浅睡各阶段占比、清醒时长）、运动记录（最近活动类型、距离、时长、消耗、平均/最大心率）。数据默认缓存至本地 JSON 文件，Python 模块提供格式化输出与原始字典两种调用方式，便于二次开发。

显著优点

安全架构领先：采用 OAuth 2.0 流程，不存储明文密码，会话令牌仅存于本地 ~/.garth/session.json，配合 TLS 1.2+ 加密传输，符合 GDPR 数据最小化原则。数据维度完整：覆盖 Garmin Connect 几乎所有核心健康指标，远超一般运动 API 的单一数据类型。自动化程度高：原生支持 cron 定时任务，5 分钟级实时同步，无需手动触发。集成门槛低：提供标准化 Python 接口，可直接嵌入 Clawdbot 工作流，也支持命令行独立运行。隐私优先设计：所有敏感数据本地缓存，无证据表明存在非 Garmin 服务器的外传行为。

潜在缺点与局限性

来源可信度限制：维护者为个人开发者（rayleigh3105），属 T3 级别，虽无恶意代码但缺乏企业级背书。第三方依赖风险：核心依赖 garminconnect 为社区非官方维护库，非 Garmin 认证 SDK，存在 API 变更导致兼容性问题或维护中断的潜在风险。功能边界明确：仅支持单向数据拉取，无法写入或控制 Garmin 设备；同步粒度受限于 Garmin Connect 云端同步延迟（设备→云端→本工具存在 2-3 分钟滞后）。运维细节待完善：日志未配置轮转、会话文件权限建议手动加固至 600、依赖版本较旧（≥0.3.2）需人工关注更新。2FA 兼容限制：官方建议禁用双因素认证或使用应用专用密码，对安全敏感用户不够友好。

适合人群

• 量化健康管理者：需要整合多源数据构建个人健康仪表板的极客用户
• Clawdbot 深度用户：已构建自动化工作流，希望将 Garmin 数据作为触发条件或状态输入
• 隐私优先的健身爱好者：拒绝商业健身平台数据托管，坚持本地-first 的数据主权主张者
• 开发者与研究者：需要结构化健身数据进行算法训练、可视化分析或 API 接口学习的技术人群

常规风险

会话凭证泄露：若 ~/.garth/session.json 权限配置不当（默认未强制 600），多用户系统存在横向读取风险。Cron 任务堆积：网络异常时同步脚本可能挂起，虽配置 30 秒超时但仍需监控 /tmp/garmin-sync.log。Garmin API 变更：非官方 SDK 可能因 Garmin 接口调整突然失效，需关注社区动态。数据准确性依赖：工具本身不验证传感器数据，睡眠阶段算法、心率异常值等以 Garmin 原始输出为准。