ghealth 详解：Google Health API 官方开源 CLI 工具

Fitbit Web API 即将在 2026 年 10 月 30 日彻底关闭，所有还依赖旧接口的脚本和第三方应用都将停止获取数据。Google 给出的替代方案是 Google Health API，而围绕它还有一个官方开源命令行工具——ghealth。它不只是给开发者用的调试器，更是为 AI 智能体读取健康数据而设计的接口层。

ghealth 是什么，由谁开发？

ghealth 是 Google Health CLI 的简称，属于 Google 官方项目，而非社区作品。根据 Google Health 团队在 2026 年 7 月 1 日发布的公告，它被明确定位为"为智能体使用而设计"。代码托管在 GitHub 的 Google-Health-API 组织下，与 Fitbit 早期开源项目并列，文件带有 Google LLC 版权声明和 Apache 2.0 许可证。

截至 2026 年 10 月 12 日，该仓库有 267 个 star，尚未发布任何 tagged release，代码版本号为 0.1.0，最后一次提交在 7 月 9 日。早期部分报道将其误列为社区项目，鉴别方法很简单：确认仓库路径为 Google-Health-API/google-health-cli。

为什么要用 Google Health API 替代 Fitbit Web API？

Google Health API 于 2026 年 3 月 24 日上线，是 Fitbit Web API 的官方替代品。Google 将其描述为在自有基础设施上重建的旧 Fitbit 服务，两个核心变化值得关注：超过 100 个旧端点被精简为更少的数据类型；登录方式从 Fitbit 自有系统迁移到 Google OAuth 2.0。

旧服务的退役时间表是硬性的：2026 年 9 月 30 日停止支持（仍可运行但不再修复 bug），10 月 30 日正式关闭并停止同步数据。当前和旧款 Fitbit 设备及 Pixel Watch 均支持新 API，唯独 Fitbit Ace 系列除外。

OAuth 2.0 与旧登录体系的区别：Fitbit Web API 使用一套自建的 OAuth 1.0a/2.0 混合鉴权，令牌由 Fitbit 域签发，第三方应用需要单独注册并遵守 Fitbit 的权限模型。迁移到 Google OAuth 2.0 后，授权主体从 Fitbit 账户变成 Google 账户，权限范围（scope）由 Google 统一管理，令牌刷新机制、撤销入口（Google 账号的「第三方应用访问」页面）、以及测试用户名单都走 Google Cloud 项目的标准流程。对用户而言，这意味着不再需要一个独立的 Fitbit 账号授权环节；对开发者而言，则意味着必须自建 Google Cloud 项目、启用 API 并配置 OAuth 客户端，接入门槛从「注册应用」变成「配置云项目」，这也是 ghealth 必须先运行 setup 向导的原因。

daily-rollup 与 list 的语义差异：daily-rollup 返回的是按天聚合的汇总值，Google Health API 在服务端完成天级别归并，适合步数、距离、卡路里这类累积型指标；list 返回的是原始采集点或会话，每个 dataPoint 带有自己的时间戳与元数据，适合心率、HRV 这类高频采样数据。二者并非同一数据的不同视图，聚合口径由 API 侧定义，因此用 list 自行求和可能与 daily-rollup 结果不一致。理解这一区别是避免统计错误的前提。

如何安装 ghealth 并完成登录？

目前没有安装包或应用商店下载，安装意味着从源码构建，再运行配置向导绑定你自己创建的 Google Cloud 项目。需要 Go 1.23 或更高版本以及 Git：

git clone https://github.com/Google-Health-API/google-health-cli.git
cd google-health-cli
go build -o ghealth .

首次运行前需准备三件事：用目标 Google 账号登录 Google Health 移动应用；在 Google Cloud 控制台创建项目、启用 Google Health API、创建桌面应用类型的 OAuth 客户端 ID 并下载 JSON 文件；将自己的邮箱加入项目测试用户列表。

随后运行 ghealth setup 向导，输入项目 ID 和 JSON 文件，选择权限范围，并在浏览器中点击 Allow。默认勾选全部只读范围。凭证文件保存在 ~/.config/ghealth/ 下，其中 credentials.json 以明文存储访问和刷新令牌。

两个关键注意事项：测试状态项目的刷新令牌 7 天后过期，需要每周重新登录；Google 文档中有一条通知称"目前不接受新项目接入"，个人项目是否受影响尚未明确。

主要命令与数据操作

几乎所有命令遵循同一模式：ghealth data + 数据类型 + 操作。结果以 JSON 返回。

ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
ghealth data heart-rate list --from today --limit 10
ghealth data sleep list --limit 5 --detail
ghealth schema types

daily-rollup 返回每天汇总值，适合步数和距离；list 返回单次读数或会话，默认最多 500 行；--detail 为睡眠会话添加分阶段明细；schema types 列出所有数据类型及其支持的操作。

输出可通过 --format table、--format csv 切换格式，-o 将数据写入文件并仅打印摘要，--dry-run 只显示请求而不发送。一个常见陷阱：汇总中缺失的某一天意味着设备未佩戴或未同步，而不是零。

AI 智能体如何调用 ghealth？

ghealth 为智能体设计了三大便利：仓库自带两个 SKILL.md 技能文件，分别覆盖配置登录和 40 种数据类型的坑；所有读取返回统一的 JSON 结构，行数据位于 dataPoints 下，错误也是 JSON，6 个退出码（0-5）标识成功或失败类型；使用 -o 时智能体只看到行数、列名和三行预览，完整数据留在文件中。

npx skills add https://github.com/Google-Health-API/google-health-cli

仓库的智能体指南将 Claude Code 和 Codex 列为主要使用者。模型本身从不直接联系 Google，执行命令和回传结果的是智能体框架。Google 的公告建议了一种日常用途：每日同步睡眠和恢复趋势，这适合带记忆的智能体循环。唯一必须人工介入的环节是浏览器中点击 Allow。

SKILL.md 与 skills 生态：SKILL.md 是智能体技能包的事实描述文件，用自然语言加示例说明某类任务该如何调用工具、有哪些常见错误。ghealth 仓库自带两份 SKILL.md，分别针对「配置与登录」和「40 种数据类型的查询陷阱」，npx skills add 命令会把它们注册进支持该约定的智能体框架（如 Claude Code、Codex）。这意味着模型不需要在提示词里硬编码 ghealth 的用法，而是按需加载技能文件获得上下文，从而降低每次调用的提示开销。

退出码与结构化错误：CLI 的 6 个退出码（0-5）分别代表成功、参数错误、鉴权失败、网络错误、API 返回错误、以及限流等不同失败类型。由于错误也以 JSON 输出，智能体可以同时依据退出码做流程分支、依据 JSON 字段做重试或降级，而不必解析人类可读的报错文本。这种「退出码 + JSON」的双通道设计是 ghealth 面向自动化而非交互式使用的关键特征。

ghealth 能读取哪些数据，不能读取哪些？

ghealth 可访问 40 种数据类型，范围取决于设备已同步到 Google Health 的内容。活动类涵盖步数、距离、楼层、活跃分钟、卡路里和带 GPS 轨迹的运动记录；心脏与生命体征包括心率、静息心率、HRV、血氧、呼吸频率和 VO2 max，ECG 和心律不齐提醒需要单独授权；睡眠包含分阶段会话和夜间温度偏差；身体与营养涵盖体重、体脂、身高、饮食记录、血糖和核心体温。

设备差异显著。Fitbit Air 这款无屏手环的兼容表中列出 23 种数据类型，不含 ECG。五种类型支持写入：运动、睡眠、体重、体脂和身高，但这部分功能尚未完成，内置范围列表仍在用 Google 已于 5 月 26 日替换的写入权限名。

无法访问的内容包括：女性健康类型和预览中的皮肤温度类型、血压（功能请求自 8 月 20 日仍未关闭）、应用功能如准备度评分和 Health Coach 对话、以及超过 90 天的长范围查询（心率等类型限制为 14 天）。如果需要一次性导出 Fitbit Air 数据，Google Takeout 更合适；ghealth 的定位是重复性、自动化访问。

把健康数据交给 AI 智能体前需要确认什么？

三个问题必须提前解决：权限范围、令牌存储位置、以及哪个 AI 模型会看到数据。配置向导默认勾选全部九个只读范围，包括运动 GPS 位置、ECG 和心律不齐提醒，可以手动收窄。启用写入范围后，智能体还能添加或删除记录。

令牌文件需要重点保护：以你的身份运行命令的智能体可以读取 credentials.json，而 ghealth auth export 会直接打印令牌。避免出现在聊天记录、共享文件夹和代码仓库中。

数据流向也需要理清。Google 声明健康数据不用于广告，除非主动选择，也不用于训练其 AI。但这些承诺只覆盖 Google 自身服务。一旦 ghealth 将数据打印进智能体会话，该智能体提供商的条款开始生效，云端模型会在其服务器上接收数据。停止方法：ghealth auth logout 删除本地令牌，也可在 Google 账号中撤销应用访问。

如果目标是让 AI 智能体处理 Fitbit 数据，建议从一个只读类别如睡眠开始，之后再逐步扩大。智能体能总结数字，但它的总结不是医疗诊断。

后续变化值得关注

2026 年 10 月 30 日 Fitbit Web API 关闭后，未迁移的脚本和应用将停止返回数据，ghealth 不受影响因为它已使用新 API。Google 在 10 月 1 日开放了名为 v4beta 的公开预览通道，第四季度路线图列出了更多数据类型包括细粒度皮肤温度。10 月 8 日有人提交了让 ghealth 使用该通道的 pull request，但仓库自 7 月 9 日以来没有新变更，是否合并值得关注。

另外两个观察点：Google 表示将陆续开放 API 给更多开发者，在投入时间配置之前应先确认该通知状态；首个 tagged release 和写入权限名修复也是重要信号。

常见问题

ghealth 是免费的吗？ 是。Apache 2.0 许可证允许任何人免费使用和修改代码。

ghealth 和 Fitbit 官方应用有什么区别？ ghealth 是命令行工具，面向开发者和 AI 智能体的自动化访问，不是面向普通用户的日常应用。

需要什么设备才能使用？ 当前和旧款 Fitbit 设备及 Pixel Watch 均可，Fitbit Ace 系列除外。

数据安全吗？ 令牌以明文存储在本地，任何以你身份运行的进程都可读取。核心风险在于数据一旦进入云端 AI 智能体的会话，就受该提供商条款约束。