garmin-connect-skill

Garmin Connect integration for OpenClaw: sync fitness data (steps, HR, calories, workouts, sleep) using OAuth. Supports China (garmin.cn) and Global (garmin....

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

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

核心变化：

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

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

🚀 2026-03-13 重大升级

问题发现

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

解决方案

1. 数据库Schema升级

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

2. 同步策略优化

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

3. 数据完整度提升

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

关键Bug修复

# 旧逻辑（错误）
body_battery_current = bodyBatteryHighestValue  # 79

# 新逻辑（正确）
body_battery_current = bodyBatteryMostRecentValue  # 29

快速开始

1. 认证（一次性）

中国大陆账号：

cd ~/openclaw/skills/garmin-connect
python3 scripts/garmin-auth.py [e-mail] password --cn

全球账号：

python3 scripts/garmin-auth.py [e-mail] password

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

2. 启动自动同步

systemd timer（推荐）：

# 已自动配置，每1小时同步一次
sudo systemctl status garmin-sync.timer

手动触发：

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

3. 测试数据读取

从数据库读取（快速）：

python3 scripts/garmin_db_reader.py

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

python3 scripts/garmin-sync.py

📊 数据结构

数据库位置

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

包含的数据

每日健康指标 (daily_metrics)：

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

睡眠数据 (sleep_data)：

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

运动记录 (workouts)：

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

🔄 同步触发方式

1. 系统定时（自动）

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

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

查看下次同步时间：

systemctl list-timers | grep garmin

2. 龙虾按需触发

当你问"我刚才跑的咋样？"时：

from scripts.garmin_db_reader import trigger_sync_if_needed

# 如果数据超过5分钟，自动触发同步
trigger_sync_if_needed(max_age_minutes=5)

然后读取数据库回答。

3. 手动触发

# 从命令行
python3 ~/.clawdbot/garmin/sync_all.py --source=manual

# 从网页（前端API）
POST /api/sync

📝 使用示例

在OpenClaw中使用

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

import sys
sys.path.insert(0, '~/openclaw/skills/garmin-connect/scripts')
from garmin_db_reader import GarminDataReader, trigger_sync_if_needed

# 检查数据新鲜度，必要时触发同步
trigger_sync_if_needed(max_age_minutes=5)

# 读取数据
reader = GarminDataReader()
today = reader.get_today_metrics()
print(f"今日步数: {today['steps']}")
print(f"身体电量: {today['body_battery_current']}")

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

from garmin_db_reader import get_daily_summary, get_workouts
# garmin_client 参数会被忽略，直接读数据库
data = get_daily_summary(None, '2026-03-13')

查看同步状态

reader = GarminDataReader()
status = reader.get_sync_status()
print(f"最后同步: {status['last_sync_time']}")
print(f"每日记录: {status['daily_metrics_count']} 条")
print(f"运动记录: {status['workouts_count']} 条")

🔧 故障排除

数据库不存在

# 手动运行一次同步
python3 ~/.clawdbot/garmin/sync_all.py --source=manual

同步失败

检查凭证：

cat ~/.garth/session.json

重新认证：

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

查看同步日志

# systemd日志
sudo journalctl -u garmin-sync.service -f

# 数据库同步日志
sqlite3 ~/.clawdbot/garmin/data.db "SELECT * FROM sync_log ORDER BY sync_time DESC LIMIT 10"

📁 文件结构

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

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

🆕 vs 旧版本

特性	旧版本	新版本
数据存储	无	SQLite数据库
响应速度	API调用（慢）	数据库读取（快）
同步触发	cron（5分钟）	timer（1小时）+ 按需
数据完整性	基础指标	完整（含Body Battery等）
消费者	仅skill	skill + 网页前端

🔗 相关项目

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