用 Claude 把 Garmin 健康數據搬回本機：一個非工程師的 AI 專案

前言

Garmin 手錶每天都記錄睡眠、HRV、靜止心率與壓力，但我想看的是更長期的變化。

我不是工程師。2026 年 8 月，我開始用 Claude 當工程夥伴，把 Garmin 的資料同步到自己的 Mac，做長期分析，再讓它每週一自動寄一份週報到我的 Gmail。到現在跑了快三個月，這篇分享整個專案怎麼做、AI 做了哪些事，以及踩過的坑和使用條款的風險。

這篇適合戴 Garmin、想把自己的資料拿回來的人，也適合好奇非工程師怎麼和 AI 一起寫程式的人。HRV 數字怎麼看，我寫在另一篇。

---

這個專案在做什麼

用非官方的 Python 套件 python-garminconnect（另開新視窗），呼叫 Garmin Connect 手機 App 用的同一套介面，把 Garmin 的健康數據同步進本機的 SQLite 資料庫，再做長期分析與每週報告。到 2026 年 11 月 8 日的規模：

• 每日資料：861 天，從 2024 年 7 月 1 日開始。
• 原始資料：17 類指標的原始 JSON 共 14,781 筆，活動 458 筆。
• 程式：Python 約 6,350 行，包括主程式與 17 支分析腳本。

每天怎麼跑

1. 排程：macOS 的 launchd 每天 08:30、13:00、22:00 執行同步腳本。
2. 抓資料：先等網路好了，強制重抓最近 3 天；中間斷線的話，最多自動往回補 30 天。
3. 健康檢查：檢查資料夠不夠新、錯誤是哪一類、有沒有缺口、有沒有警訊，每週做一次備份，有問題就跳 macOS 通知。
4. 週報：同步成功才產生週報。

資料怎麼存

資料庫只有三張表：

• 原始資料：每天、每種指標的原始 JSON，原封不動存下來，之後想分析新的東西不用重抓。
• 每日摘要：每天一列，放睡眠、HRV、靜止心率這些精簡過的指標。
• 活動：每一筆運動紀錄。

分析與週報

• 深度分析：12 個分析模組產生一份 HTML 報告，包括睡眠、HRV、壓力、訓練負荷、旅行、異常偵測，以及睡眠對隔天靜止心率與 HRV 的影響。
• 週報：每週一產生上一週的報告，有睡眠的指標、圖表、警訊，以及只談睡眠的「本週行動」，寄一封到自己的 Gmail；最底下由 Claude Opus 5.5 寫 250 到 450 字的本週分析。

---

時間線

---

AI 怎麼參與

Claude 當工程夥伴

從安裝、回補資料、分析到自動化，都是在和 Claude 的對話裡完成的。我說想要什麼、看它的設計、決定做不做；寫程式、執行、看錯誤訊息、修正，大多是 Claude 做。

• 專案記憶：規則與現況寫在 CLAUDE.md，每次開新的對話都會自動載入（Claude Code 文件（另開新視窗）），完整的歷史另外寫在交接文件，換對話也接得上。
• 人在迴路 (human in the loop)：比較大的改動先提設計，我同意才做；寄信、呼叫要付費的 API、commit 都要我同意；不設遠端、不 push。

Cowork 和 Claude Code

• Claude Cowork：把 Claude Code 的代理能力帶到寫程式以外的工作，預設在雲端執行（另開新視窗）。我一開始在這裡做，但雲端容器的對外連線擋掉了 garmin.com，公開的回報裡也有雲端主機登入 Garmin 失敗的個案，排程沒辦法放在雲端跑（見下面「踩過的坑」）。
• Claude Code：在終端機、IDE、桌面 App 與瀏覽器裡（另開新視窗）讀程式、改檔案、執行指令。10 月搬到本機之後，同步、鑰匙圈與排程都在自己的 Mac 上。

多代理查核

重要的分析與文件改動，我會請 Claude 派好幾個子代理分頭查，再由另一個代理逐條反駁或比對。例如 11 月 4 日的週報檢查派了 8 個代理；11 月 7 日整併文件時，逐條核對約 190 條規則，找出 2 條遺漏、1 條條件寫得太寬。

Opus 寫每週分析

週報最底下的本週分析由 Claude Opus 5.5 寫。它只拿到信裡本來就有的數字，不含敏感的健康資訊；系統提示要求標出樣本數、寫明相關不等於因果、不做診斷。

費用每週約 0.07 到 0.10 美元，一年約 5 美元。Opus 5.5 的價格是每百萬 token 輸入 4 美元、輸出 20 美元，思考用的 token 也按輸出計價（價格（另開新視窗）、thinking 文件（另開新視窗））。

---

踩過的坑

只能在家裡的 Mac 跑

我在 Cowork 的雲端容器遇過對外連線擋掉 garmin.com。公開的回報裡，雲端主機與住家網路都有登入失敗的個案（另開新視窗），Garmin 回 429 也和套件的指紋（另開新視窗）、登入流程少了步驟（另開新視窗）有關，沒有官方說明。結論是排程留在家裡的 Mac；要不怕關機，可以考慮家裡一台常開的 Mac mini，不是搬上雲端。

Mac 闔上螢幕時的 DarkWake

launchd 在睡眠時錯過的排程，喚醒後會補跑一次（另開新視窗）。問題是 Mac 闔上螢幕時，系統會短暫喚醒（DarkWake）7 到 45 秒，排程常在這時候啟動，網路還沒起來就失敗。Apple 沒有說明 DarkWake 期間網路能不能用，開發者論壇的說法（另開新視窗）是喚醒的程式和啟動網路的程式在賽跑。我的解法是：用電池、在 DarkWake 時就先不同步，等打開螢幕再跑，實際驗證過可行。

錯誤分類的順序很重要

網路錯誤的訊息裡，常常夾著「認證失敗」的字樣。先判斷是不是網路的問題，才不會誤報成 token 失效。

排程顯示「成功」，不代表有做事

10 月 26 日，一個排程任務卡在權限詢問 10 個小時，狀態卻一直顯示成功。所以每次同步要自己記錄有沒有真的拿到資料，不能只看排程的狀態。

非官方 API 會突然壞

Garmin 改登入的時候，通常會先在 python-garminconnect 修好，但中間會有空窗：2026 年 3 月（另開新視窗）、6 月（另開新視窗）、9 到 10 月（另開新視窗）都有登入或 token 驗證失敗的回報。0.3.0 版（另開新視窗）改用和官方 App 相同的手機登入流程，並偽裝 TLS 指紋來繞過 Garmin 對程式登入的阻擋。我的做法是鎖定版本，新版先在隔離的環境測過才升級。

---

官方個人 API 與使用條款

Garmin 的官方個人 API

Garmin 在 2026 年 10 月推出個人層級的開發者計畫（另開新視窗），可以用官方的方式拿自己的資料：

• 條件：只限個人使用、只能讀自己的資料（另開新視窗），只能主動拉取。在 Garmin Connect 網頁建立 key，key 只顯示一次。
• 期限：key 可以選 30、90、180 天或一年；換到的 token 有效 24 小時，不支援 refresh token。
• 端點：API 文件（另開新視窗）列了 26 個操作，有 HRV、睡眠、壓力、Body Battery、血氧、每日心率等，但沒有訓練準備度、訓練狀態的端點；VO2max 沒有獨立的端點，每筆活動的資料裡有一個 VO2max 欄位，實際有沒有值我還沒測。
• 官方的 Python 程式：connect-personal-api-python（另開新視窗） v1.0.0（2026-10-21）。

我評估過，少了訓練準備度、訓練狀態與 3 分鐘的壓力明細，先不改接。另外，key 最長一年，自動化的話至少每年要自己重建一次 key，而且 key 要放在排程讀得到的地方。

使用條款

Garmin 網站的使用條款（另開新視窗）（2026 年 4 月 1 日生效）：

• 禁止自動擷取：禁止用「網站沒有刻意提供的方式」存取、複製或擷取內容。
• 禁止偽造標頭：在「不得冒充他人」的舉例裡，列了偽造標頭或操作識別資訊來隱藏來源。
• 可以停權：Garmin 可以暫停或終止帳號，訂閱的服務不退費。
• 沒有點名：條款沒有點名 python-garminconnect 這類非官方套件；套件的討論區有人問過有沒有人被停權，維護者回答他不知道有（另開新視窗），我也沒有找到具體的個案。

所以比較持平的說法是：技術上登得進去，不等於取得官方的授權；不能說個人自用一定沒問題，也不宜說用了就會被停權。這是用非官方 API 要自己承擔的風險。

---

想自己做的話

要準備的東西

• Garmin 帳號與手錶。
• 一台在家、常開的 Mac：要同步的時間點電腦得醒著。
• Claude：寫程式用 Claude Code；要 AI 寫週報分析，另外要 Anthropic 的 API key。
• Gmail：用應用程式密碼要先開兩步驟驗證，或改用 Gmail API。

動手前先決定的事

• 非官方套件還是官方 API：非官方的資料多、會突然壞、有條款的風險；官方的穩定但指標少，key 要定期換。
• 哪些資料會離開電腦：送 API、寄信、AI 開發時讀到的文件，三條路都要算進去。
• 帳密放哪裡：鑰匙圈，並確認每個項目的存取設定；不要放在 AI 會讀到的文件裡。
• 花費上限：替專案的 API key 開一個工作區、設上限。
• AI 能做什麼：哪些動作要先問你（寄信、付費 API、commit），哪些用設定擋掉，而不是只寫在 CLAUDE.md。

我的 CLAUDE.md

我把這個專案的 CLAUDE.md 拿掉個人資料、健康數據與分析結論，做成去識別的版本，給想自己做的人參考寫法：下載 CLAUDE.md（分享版）。程式、README 與交接文件沒有附上，裡面的 <...> 要換成自己的值；交給 AI 之前先讀過一次，確認每一條都適合你的環境。

花費

每週的 AI 分析一年約 5 美元；Claude 的訂閱或 Claude Code 用到的額度另外算。

---

週報長什麼樣

每週一早上，信箱會收到一封這樣的週報。下面這張的版面照實際的週報，數字全部換成假資料：

• 指標表：睡眠週均、7 小時以上與不到 6 小時的夜數、就寢時間，以及 HRV 與靜止心率和自己基線的比較。
• 本週行動：只談睡眠，一次只給一個目標。
• 本週分析：Claude 只根據信裡的數字寫，標出樣本數，不做醫療判斷。

---

總結

整個專案做下來，Claude 幫我做到了以前要找工程師才做得到的事：把 Garmin 的資料拿回來、自動同步、長期分析、每週寄報告。過程中要注意的是，非官方 API 會突然壞，排程顯示成功也不代表真的拿到資料，所以每次同步要自己記錄結果；Garmin 的官方個人 API 目前少了幾項我要的指標，我先不改接，使用條款的風險由自己承擔。

以上經驗提供給想把自己的健康數據拿回來分析的朋友參考，也列出引用的資料來源，有興趣的人可以點連結詳讀。

---

參考資料

20 筆

1. GitHub: cyberjunky/python-garminconnect（另開新視窗）
2. Claude Code: Memory (CLAUDE.md)（另開新視窗）
3. Claude Help Center: Claude Cowork architecture overview（另開新視窗）
4. Claude Code: Overview（另開新視窗）
5. Anthropic: Pricing（另開新視窗）
6. Anthropic: Extended thinking（另開新視窗）
7. GitHub: python-garminconnect issue #337（另開新視窗）
8. GitHub: python-garminconnect issue #444（另開新視窗）
9. GitHub: python-garminconnect releases（另開新視窗）
10. Apple Developer Archive: Scheduling Timed Jobs（另開新視窗）
11. Apple Developer Forums: thread 770262（另開新視窗）
12. GitHub: python-garminconnect issue #332（另開新視窗）
13. GitHub: python-garminconnect issue #369（另開新視窗）
14. GitHub: python-garminconnect issue #453（另開新視窗）
15. Garmin: Connect Developer Program Overview（另開新視窗）
16. Garmin: Personal API FAQ（另開新視窗）
17. Garmin: Personal API Swagger Docs（另開新視窗）
18. GitHub: garmin/connect-personal-api-python（另開新視窗）
19. Garmin: Terms of Use (Effective April 1, 2026)（另開新視窗）
20. GitHub: python-garminconnect issue #362（另開新視窗）