Garmin Connect 技能

将您的佳明手表数据同步到 OpenClaw，支持中国大陆和全球账号。

🎯 新架构（2026-03-13 更新）

核心变化：

• - ✅ 单一 SQLite 数据库存储所有数据
• ✅ 三种同步触发方式（定时/按需/手动）
• ✅ 龙虾直接读取数据库（快速响应）
• ✅ 完整数据支持（身体电量、HRV、最大摄氧量等）
• ✅ 数据库字段从 26 个扩展到 58 个（2026-03-13 下午重大升级）
• ✅ 时序数据表支持（心率曲线、身体电量曲线等）

佳明服务器 → 统一同步脚本 → SQLite 数据库
├─ 龙虾技能（读取）
└─ 网页前端（读取）

🚀 2026-03-13 重大升级

问题发现

用户发现身体电量显示不一致（服务器 79 vs 手表 28），发现数据库同步不完整。

解决方案

1. 数据库 Schema 升级

• - 新增 35 个字段：时长类、压力详细值、呼吸/血氧详细值、wellness 字段等
• 修复关键字段：bodybatterycurrent 从存储最高值改为存储最新值
• 创建 5 个时序数据表：心率、身体电量、步数、压力、呼吸率曲线
• 创建 1 个动态反馈事件表
• 运动记录新增 15 个高级指标字段

2. 同步策略优化

• - 完整版（syncall.py v2.0）：包含所有字段和时序数据，适合手动完整同步
• 简化版（syncdaily.py）：只同步核心每日指标，适合定时任务

3. 数据完整度提升

• - 标量字段：26% → 95%+
• 核心指标：100% 完整
• 时序数据：表已创建，待后台同步

关键 Bug 修复

python

旧逻辑（错误）

bodybatterycurrent = bodyBatteryHighestValue # 79

新逻辑（正确）

bodybatterycurrent = bodyBatteryMostRecentValue # 29

快速开始

1. 认证（一次性）

中国大陆账号：

bash
cd ~/openclaw/skills/garmin-connect
python3 scripts/garmin-auth.py your-email@qq.com password --cn

全球账号：

bash
python3 scripts/garmin-auth.py your-email@gmail.com password

认证成功后，凭证会加密保存到 ~/.garth/session.json。

2. 启动自动同步

systemd 定时器（推荐）：

bash

已自动配置，每 1 小时同步一次

sudo systemctl status garmin-sync.timer

手动触发：

bash
python3 ~/.clawdbot/garmin/sync_all.py --source=manual

3. 测试数据读取

从数据库读取（快速）：

bash
python3 scripts/garmindbreader.py

从 API 读取（慢速，用于测试）：

bash
python3 scripts/garmin-sync.py

📊 数据结构

数据库位置

/home/roots/.clawdbot/garmin/data.db

包含的数据

每日健康指标 (daily_metrics)：

• - 基础：步数、距离、卡路里、活动时长、爬楼
• 心率：静息/最低/最高
• 身体电量：当前/最高/最低/充电/消耗
• 压力：平均/最高
• HRV：昨晚 HRV
• 呼吸率
• 最大摄氧量
• 健身年龄

睡眠数据 (sleep_data)：

• - 时长、睡眠分数、质量百分比
• 深睡/REM/浅睡、清醒时间
• 午睡详情

运动记录 (workouts)：

• - 时间戳、类型、名称、距离、时长、卡路里、心率

🔄 同步触发方式

1. 系统定时（自动）

每 1 小时自动同步一次（systemd 定时器）：

bash
sudo systemctl start garmin-sync.timer
sudo systemctl enable garmin-sync.timer

查看下次同步时间：

bash
systemctl list-timers | grep garmin

2. 龙虾按需触发

当您问“我刚才跑的咋样？”时：

python
from scripts.garmindbreader import triggersyncif_needed

如果数据超过 5 分钟，自动触发同步

triggersyncifneeded(maxage_minutes=5)

然后读取数据库回答。

3. 手动触发

bash

从命令行

python3 ~/.clawdbot/garmin/sync_all.py --source=manual

从网页（前端 API）

POST /api/sync

📝 使用示例

在 OpenClaw 中使用

方式 1：从数据库读取（推荐）

python
import sys
sys.path.insert(0, ~/openclaw/skills/garmin-connect/scripts)
from garmindbreader import GarminDataReader, triggersyncif_needed

检查数据新鲜度，必要时触发同步

triggersyncifneeded(maxage_minutes=5)

读取数据

reader = GarminDataReader() today = reader.gettodaymetrics() print(f今日步数: {today[steps]}) print(f身体电量: {today[bodybatterycurrent]})

方式 2：直接 API 调用（兼容旧代码）

python
from garmindbreader import getdailysummary, get_workouts

garmin_client 参数会被忽略，直接读取数据库

data = getdailysummary(None, 2026-03-13)

查看同步状态

python
reader = GarminDataReader()
status = reader.getsyncstatus()
print(f最后同步: {status[lastsynctime]})
print(f每日记录: {status[dailymetricscount]} 条)
print(f运动记录: {status[workouts_count]} 条)

🔧 故障排除

数据库不存在

bash

手动运行一次同步

python3 ~/.clawdbot/garmin/sync_all.py --source=manual

同步失败

检查凭证：

bash
cat ~/.garth/session.json

重新认证：

bash
cd ~/openclaw/skills/garmin-connect
python3 scripts/garmin-auth.py your-email password

查看同步日志

bash

systemd 日志

sudo journalctl -u garmin-sync.service -f

数据库同步日志

sqlite3 ~/.clawdbot/garmin/data.db SELECT * FROM synclog ORDER BY synctime DESC LIMIT 10

📁 文件结构

~/.clawdbot/garmin/
├── data.db # SQLite 数据库
├── sync_daemon.py # 数据库管理
└── sync_all.py # 完整同步脚本

~/openclaw/skills/garmin-connect/
├── scripts/
│ ├── garmindbreader.py # 数据库读取（新增）
│ ├── garmin-auth.py # 认证
│ ├── garmin-sync.py # API 获取（兼容）
│ └── ...
└── SKILL.md # 本文件

🆕 与旧版本对比

特性	旧版本	新版本
数据存储	无	SQLite 数据库
响应速度

API 调用（慢） | 数据库读取（快） | | 同步触发 | cron（5 分钟） | 定时器（1 小时）+ 按需 | | 数据完整性 | 基础指标 | 完整（含身体电量等） | | 消费者 | 仅技能 | 技能 + 网页前端 |

🔗 相关项目

• - 佳明健康仪表盘：/home/roots/garmin-dashboard/
• 数据库：~/.clawdbot/garmin/data.db