成品自動傳 Google Drive：rclone 一次設好

為什麼要花時間設這個

第 17 章講完了「AI 幫你寫腳本、配音、抓畫面、剪接、燒字幕」，最後產出一個乾淨的 MP4。第 18 章解釋了工具放在哪、為什麼首次要下載那麼久。但這個 MP4 現在還躺在 HA host 的 /data/pi-agent/ 底下的某個資料夾——你手機看不到、平板看不到、想傳給朋友還得 SSH 進去用 scp 拉出來，累。

• 不設 rclone 的日常：影片跑完 → 你打開電腦 → SSH 進 HA → 找到影片路徑 → scp 拉出來 → 傳 LINE 或上 Drive。每一步都在勸退你，久了就懶得做影片。
• 設完 rclone 的日常：影片跑完 → 手機叮一聲（Google Drive App 通知有新檔）→ 點開 → 分享。整段從電腦拿掉了。

Pi Agent 已經把 rclone 打包在 add-on 容器裡，你什麼都不用裝。你要做的只有一件事：跑一次 OAuth 授權精靈，告訴 rclone 你的 Google 帳號是哪一個。這件事第一次要在 terminal 做（因為 Google 的 OAuth 需要你手動貼一個驗證碼），但只要做一次，token 會存到 /data/pi-agent/rclone/rclone.conf，之後就永遠自動了——連 HA 整台重灌 restore 回來，token 也會跟著回來（第 20 章的 HA snapshot 有帶）。

rclone 是什麼、為什麼要用它

rclone 是一個檔案同步工具，你可以把它想成「命令列版本的 Google Drive App」。差別是它支援 40 多家雲端硬碟：Google Drive、OneDrive、Dropbox、Box、iCloud Drive、Amazon S3、阿里雲 OSS、SFTP、WebDAV……你講得出來的雲端儲存服務幾乎都在裡面。用法都長得一樣：rclone copy 本地路徑 遠端名稱:遠端資料夾。

Pi Agent 為什麼選 rclone 而不是自己刻一個 Google Drive 上傳器？三個理由：

• 成熟穩定：rclone 開發超過十年，token 續期、斷線重試、大檔分片上傳這些細節都處理好了。自己刻大機率會踩到你想不到的坑。
• 不綁一家雲端：今天你選 Google Drive，明天想改 OneDrive 或 Dropbox，只是多跑一次 rclone config 的差別，Pi Agent 這邊的設定改一行字就能切換。
• 離線就是離線：rclone 純粹在你自己的 HA host 上跑，Pi Agent 本身沒有任何「雲」在中間中轉。你的檔案從家裡直接上傳到你 Google 的儲存空間，中間沒有第三方看過。

Pi Agent 內建 rclone 的意思是：你不用另外 apt install rclone、也不用煩惱版本相容性。add-on 容器裡已經放好了一份，跑起來就能用。你要做的只有「告訴它你的 Google 帳號是哪一個」——這件事就是 OAuth 授權。

為什麼要 OAuth，不是貼帳號密碼

你可能會想：「幹嘛搞這麼麻煩，rclone 讓我填 Google 帳號密碼不就好了？」——這個問題非常好，因為答案牽動整個網路 App 的安全設計。

Google 早就不接受這種做法了。原因很簡單：如果第三方軟體收得到你的 Google 密碼，它就能拿去做任何事——收你信、清你 Drive、關你 YouTube 頻道、盜刷你綁的信用卡。你信任 rclone 不代表你信任 rclone 一輩子不會被駭、也不代表你信任 rclone 開發者未來不會變壞。給密碼等於給整個帳號的鑰匙。

OAuth（Open Authorization）就是為了解決這個問題設計出來的。整個流程長這樣：

1. rclone 給你一個 URL

   那個 URL 是 Google 官方的授權頁，不是 rclone 自己刻的假冒頁面。你打開 URL 之後看到的是你熟悉的 Google 登入介面——密碼你是打進 Google 自己的頁面，不是打進 rclone。

2. Google 問你「要不要讓 rclone 存取你的 Drive」

   你按同意（就跟你第一次讓 Notion 讀 Google Calendar 是一樣的畫面）。Google 幫你判斷：這個 App 想要什麼權限、你確認才給。

3. Google 發給 rclone 一張 token

   token 就是一張「代幣」，長得像一串亂碼。它只能拿來做你剛才同意的那件事（存取 Drive），不能拿去做其他事（比如寄信）。而且 token 隨時可以撤銷——你到 Google 帳號 → 安全性 → 第三方 App 授權，把 rclone 從清單裡踢掉，token 立刻失效。

4. 之後 rclone 拿 token 傳檔，不再需要你的密碼

   rclone 每次上傳都是「帶著這張代幣」跟 Google 說「這是我的授權，可以放檔案進來嗎」。你的 Google 密碼從頭到尾沒離開過 Google 自己的伺服器。

前提：你要能 SSH 進 HA

rclone config 精靈是互動式的（會一步步問你答），必須在 terminal 裡跑。這代表你要能 SSH 進 HA host、然後再進去 Pi Agent 的 add-on 容器裡。如果你從來沒 SSH 過 HA，先把這個環境準備好：

1. 裝 Advanced SSH & Web Terminal add-on

   HA 側邊欄 → 設定（Settings）→ 附加元件（Add-ons）→ 附加元件商店 → 搜「Advanced SSH & Web Terminal」→ 安裝。這是官方推薦的最簡單方式，安裝完在 add-on 頁面按「開啟網頁 UI（Open Web UI）」就是一個瀏覽器裡的 terminal。你不需要在筆電裝什麼 SSH 客戶端。

2. 進去之後你在 HA host

   打開之後看到黑底白字的畫面，這時候你是站在 HA host 上（可以看到 /config/、/mnt/ 這些 HA 系統目錄），但你還沒進到 Pi Agent 的 add-on 容器裡。想確認自己在哪，跑 ls /data/pi-agent/——會顯示「No such file or directory」，因為 /data/pi-agent/ 是容器裡面的路徑，HA host 上看不到。

3. 先查你自己的 add-on slug（最保險的一步）

   Pi Agent 容器名字長成 addon_<slug>，而 slug 前面會帶一段八位英數 repo hash（例如 b9cf5676_woow_ha_pi_agent）——這段 hash 是 HA 依你加的 add-on repository URL 算出來的，每個人裝的都不一樣。最不會錯的查法：HA 側邊欄 → 設定 → 附加元件 → 點 Woow HA Pi Agent → 上方「資訊（Info）」分頁往下捲，會看到 Hostname 或 Slug 欄位（例如 b9cf5676_woow_ha_pi_agent），這就是你要用的 slug。抄下來備用。

4. 用 docker exec 進 Pi Agent 容器

   在 terminal 裡把剛才那段 slug 套進去：docker exec -it addon_<你的slug> bash，例如 docker exec -it addon_b9cf5676_woow_ha_pi_agent bash。跑完你會看到 shell prompt 換了樣子（通常變成 root@某串英數字:/#），這代表你已經在容器內。這時候再跑 ls /data/pi-agent/ 就會看到 sessions、models、rclone 這些子資料夾。

5. 接下來所有指令都在容器內跑

   後面章節的 rclone config、rclone lsd、rclone config reconnect 這些指令，都必須在容器內執行——因為 HA host 上根本沒有 rclone 執行檔。跑錯地方會顯示「rclone: command not found」，記得先確認你的 prompt 有沒有換過來。

rclone config 精靈：一步一按 Enter

準備好之後，在 add-on 容器裡跑 rclone config。精靈會問一連串問題，看起來嚇人但其實大部分都是按 Enter 走預設。下面每一步我把「螢幕會顯示什麼、你要打什麼」都寫清楚：

1. 選 n）新增遠端

   精靈開場會列你已經有的 remote（第一次是空的），然後問你 e/n/d/r/c/s/q>。打 n 再按 Enter，代表「new remote（新增一個）」。

2. Name 取個好記的名字

   問 name>。這個名字之後 Pi Agent 設定會用到，建議取簡短好記的 gdrive。它跟 Google 帳號沒關係、純粹是給你自己認的。以後你多加一個 Dropbox 就叫 dropbox、多加一個 OneDrive 就叫 onedrive。

3. Storage 選 drive

   精靈會列 40 幾家雲端讓你選，每一家有一個編號。找到 drive（Google Drive）打它的編號，或直接打 drive 也可以。按 Enter。

4. client_id / client_secret 空著按 Enter（見警告）

   問 Google Application Client Id>。個人一次性用，直接按 Enter 走 rclone 內建的 client_id 就夠。client_secret 同樣空白按 Enter。但看下面那個警告方塊——rclone 官方預告「內建 client_id 會在 2026 年期間停用（will stop working during 2026）」，重度使用者建議現在就自己申請一組。

5. Scope 選 1（完整存取）

   精靈會列五個選項，選 1：Full access all files, excluding Application Data Folder（完整存取除了 App 資料夾以外的所有檔案）。這個是最常用的權限，讓 rclone 可以在你 Drive 的任何資料夾放檔案、也能讀既有檔案。想更保守可以選 3（只能碰 rclone 自己建立的檔案），但這樣你手機的 Drive App 就看不到影片，失去意義。

6. service_account_file 空著按 Enter

   問你有沒有 service account JSON 檔。個人用途沒有，空白按 Enter。

7. Edit advanced config? 選 n

   問要不要改進階設定（傳輸 chunk 大小、代理、SSL 什麼的）。第一次用選 n，預設值對 99% 的家庭場景都夠。

8. Use auto config? 選 n（HA 沒瀏覽器）

   問 Use web browser to automatically authenticate rclone with remote?。這是整個流程最容易錯的一步。y 是給筆電、桌機這種「本機就有 Firefox / Chrome」的環境用的——rclone 會自動開瀏覽器。但 HA host 是伺服器、沒有 GUI、開不了瀏覽器，選 y 會卡住在 waiting for code...。選 n，走 headless 手動模式。

9. 螢幕會印出一段 URL，用你自己的電腦或手機打開

   精靈會印出類似 https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=...&scope=...&response_type=code 這樣一長串。整段複製（含中間的 :、_、&），貼到你手機或筆電的瀏覽器打開。這時候你會看到熟悉的 Google 登入頁。

10. Google 登入 → 授權 → 拿到驗證碼

    用你要接的 Google 帳號登入。可能看到「Google 尚未驗證此應用程式」的警告——這是因為 rclone 用的是共用 client_id，不是每個使用者都幫它「認證」過。點「進階」→「前往 rclone（不安全）」→ 繼續。授權完 Google 會顯示一段驗證碼（Verification code），複製那段驗證碼。

11. 驗證碼貼回 terminal

    回到你的 terminal，rclone 這時候在等 Enter verification code>。把剛才那段驗證碼貼進去按 Enter。看到 Got code 就代表 OAuth 完成、token 已存進 rclone.conf。

12. Configure this as a Shared Drive (Team Drive)? 選 n

    rclone 原話是 Configure this as a Shared Drive (Team Drive)?——問你要不要接你公司的共用雲端硬碟（原本叫 Team Drive、現在改名 Shared Drive）。個人 Google 帳號沒有這種東西，選 n。

13. 看到摘要，選 y 存檔

    精靈會秀你剛才填的所有值（type = drive、scope = drive 之類），問 Keep this "gdrive" remote?，選 y（keep）。回到主選單後打 q（quit）離開精靈。

驗證：真的能通了嗎

精靈跑完你可能還是不放心「這樣就好了？」，來確認一下。在 add-on 容器裡跑：

rclone lsd gdrive:

這個指令的意思是「列出（ls）gdrive 這個 remote 根目錄的資料夾（d = directories only）」。跑完應該會列一堆你 Google Drive 首頁看到的資料夾——「我的雲端硬碟」、「共用檔案」、你自己建的資料夾都會出現。長這樣：

          -1 2024-03-15 08:22:14        -1 相簿
          -1 2025-06-20 14:11:03        -1 工作備份
          -1 2026-01-08 22:45:56        -1 家裡影片

看到列表 = 成功。如果什麼都沒印出（空的但沒錯誤訊息），代表你的 Drive 根目錄真的沒東西，也算成功——去建個資料夾再試就會看到。

如果看到錯誤訊息，對應解法看下面「常見卡關」那節。最常見的兩種：

還想更確定？跑一個測試上傳：

echo "hello from pi agent" > /tmp/test.txt
rclone copy /tmp/test.txt gdrive:

跑完打開手機的 Google Drive App，最上面「最近」那個分頁應該就看到 test.txt。看到就是穩了，這個測試檔可以直接在手機 Drive 上刪掉。

把 gdrive 接進 pitch_video 管線

rclone 設好只完成一半——Pi Agent 還不知道「影片跑完要傳去哪」。你要告訴 pitch_video skill 的 config：把成品送去 gdrive:某某資料夾。實作細節每個 skill 版本不太一樣，這一節講最常見的三種寫法。

先在 Google Drive 手動建一個資料夾當家（比如 PiAgent/Videos）。你也可以省略這步，rclone 上傳的時候會自動建，但先建好可以順便設分享權限、加上 icon 認明。

然後打開 pitch_video skill 的 SKILL.md 或它自己的 README 找 upload_to 或 output_upload 之類的欄位。三種常見寫法：

三種寫法的結尾都要有斜線 /——沒斜線 rclone 會把 gdrive:PiAgent/Videos 當成「叫 Videos 的檔案」而不是資料夾，會踩雷。

改完之後跑一次完整影片管線（第 17 章教過），最後一個階段你會看到類似這樣的 log：

[push_drive] Uploading final.mp4 (42MB) to gdrive:PiAgent/Videos/
[push_drive] Transferred: 42.1 MiB / 42.1 MiB, 100%, 3.2 MiB/s
[push_drive] Uploaded final.mp4 successfully in 13s

沒看到 push_drive 的 log？代表 skill 沒讀到你的設定，或設定寫在錯的地方。回頭確認 upload_to 那欄有沒有存到、有沒有拼錯 remote 名字（大小寫敏感）。

token 存哪、跟 HA snapshot 什麼關係

做完 OAuth 之後，你剛才辛苦換來的 token 存在這個位置：

/data/pi-agent/rclone/rclone.conf

這個檔案長這樣（截取重點）：

[gdrive]
type = drive
scope = drive
token = {"access_token":"ya29.a0Af...","token_type":"Bearer","refresh_token":"1//0e...","expiry":"2026-08-14T15:30:00.000000Z"}
team_drive =

看到那段 refresh_token 沒有？那段就是靈魂——rclone 拿它去跟 Google 續期短期的 access_token，讓你不用每天重跑 OAuth。這也是為什麼「rclone.conf 不要外流」——refresh_token 等於長期通行證，被別人拿到就能持續用你帳號傳檔（除非你在 Google 那邊撤授權）。

然後看它的路徑：/data/pi-agent/ 是 Pi Agent add-on 的持久儲存區。這個資料夾符合兩個條件：

1. add-on 升級不會清掉

   你升級 Pi Agent 到新版（第 21 章會教），add-on 本身的檔案系統會換一份新的，但 /data/ 底下的東西會保留。所以升級後不用重跑 OAuth。

2. HA snapshot 會備份到

   HA 的整機備份（第 20 章）會把 add-on 的 /data/ 一起打包。所以你哪天 HA 主機壞了、換 SD 卡從 snapshot 還原，rclone.conf 會跟著回來——不用重跑 OAuth，你重新開機 Pi Agent 影片就繼續傳。

那什麼時候會需要重跑 OAuth？三種情況：

想改用 Dropbox / OneDrive / S3

rclone 支援 40 幾家，換一家的成本是「多跑一次 rclone config」。你甚至可以同時保留多家——把最重要的 Google Drive 傳一份、順便備份一份到 Dropbox 當異地備援，兩個 remote 並存。步驟一樣：

1. 再跑一次 rclone config

   選 n（new）加一個新 remote，name 取好記的 dropbox / onedrive / s3。

2. Storage 選對應的家

   Dropbox 選 dropbox、OneDrive 選 onedrive、S3 選 s3（再選 provider AWS 或 CloudFlare R2）。每一家的欄位略有不同，但精靈都會幫你走：

   • Dropbox：跟 Google Drive 幾乎一樣，OAuth 流程一樣要選 n（headless）拿 URL 貼驗證碼。
   • OneDrive：多一步問你是 personal 還是 business 帳號（onedrive.com vs Microsoft 365）。個人選 personal，公司帳號選 business。
   • S3：不用 OAuth，改成貼 access_key_id 跟 secret_access_key（去 AWS Console → IAM 建）。適合已經有 AWS 帳號的人。

3. pitch_video 的 upload_to 改對應的 remote

   把 gdrive: 改成 dropbox: 或 onedrive: 或 s3:mybucket/。設完照樣可以跑 rclone lsd dropbox: 確認。

4. 想兩家一起傳？寫兩段 rclone copy

   Skill 的 push script 裡加兩行：rclone copy final.mp4 gdrive:PiAgent/Videos/ 跟 rclone copy final.mp4 dropbox:PiAgent/Videos/。兩家 quota 都會消耗，但你多一份備援。

常見卡關

1. 授權 URL 太長打不開、貼到瀏覽器變成搜尋

   rclone 印出的 URL 有 200-400 個字元、中間充滿 &、:、_ 這些符號，很多人在 terminal 裡「反白到一半」漏掉了尾巴。做法：（a）在瀏覽器 terminal（比如 Advanced SSH Web UI）直接三擊全選那一整行、Ctrl+C 複製。（b）貼到瀏覽器的網址列，不是搜尋列——貼進 Google 首頁的搜尋框會被當關鍵字。（c）如果你用手機瀏覽器貼，長按網址列選「貼上並前往」，別按錯選成「搜尋」。實在不行，把 URL 用電子郵件寄給自己，在信裡點連結。

2. Google 顯示「Google 尚未驗證此應用程式」不敢按繼續

   這是預期的畫面、不是 bug。因為 rclone 用的 client_id 是所有人共用的，Google 沒辦法「認證」rclone 這個 App（畢竟每個使用者的用途都不同）。做法：點畫面下方的「進階（Advanced）」展開 → 點「前往 rclone（不安全）」連結 → 繼續授權。這只是 Google 的保守警告，你信 rclone 就繼續。想避免看到這個畫面，就是前面提過的「自己去 Google Cloud Console 申請 client_id」，申請完把自己的 App 標成 verified 就不會跳警告。

3. 上傳失敗顯示 quota exceeded

   Google Drive 個人免費空間 15 GB（跟 Gmail、Google Photos 共用），影片吃很兇很快就爆。做法（優先順序）：（a）先手動去 Drive 清一波用不到的舊檔（Gmail 的大信件附件是常見大宗）。（b）改傳到 上一節提到的 Dropbox、OneDrive 分散 quota。（c）長期方案是 Google One 升級（100 GB 一年約 700 台幣、200 GB 約 900 元），或改用 S3 / R2 這種以量計價的雲儲存（每 GB 幾分錢）。（d）在 skill 的 push script 加個「傳完就刪本地檔」的邏輯，至少 HA host 上不會累積。

4. token 過期 / 好久沒用之後上傳報 401

   refresh_token 一般可以續期很久（Google 官方說「不會過期」但實際上有些邊角情況會失效——例如你長期沒用、Google 帳號改過密碼、或 Google 判定異常）。錯誤訊息通常是 oauth2: token expired 或 401 Unauthorized。做法：在 add-on 容器裡跑 rclone config reconnect gdrive:，會走一次快速版的 OAuth（跟精靈一樣印 URL 貼驗證碼，但省掉前面那些選項）。跑完 token 就更新了。

5. rclone lsd 一直很慢 / 卡住不回應

   兩個常見原因：（a）你家網路對 Google 不順（有些 ISP 對 accounts.google.com 有降速）。跑 ping accounts.google.com 看有沒有丟包，有的話重開路由器、或換 Google DNS 8.8.8.8。（b）rclone 在做「列出整個根目錄」，你 Drive 檔案超多（幾萬個）時，第一次 lsd 會慢好幾十秒。這是正常的。改用 rclone lsd gdrive:PiAgent/ 只列子資料夾會快很多。

6. docker exec 進去之後 prompt 沒變、指令一樣說 command not found

   你可能連 docker exec 都沒跑成功（HA 有些版本沒有 docker command，是用 ha CLI 或直接 podman）。做法：先跑 docker ps --format '{{.Names}}' | grep pi_agent 直接印出真名（例如 addon_b9cf5676_woow_ha_pi_agent）；沒有 docker 就換 ha addons info <你的slug>（slug 從 HA 附加元件 → Pi Agent → Info 分頁抄）；再不行去 add-on 頁面右上角看有沒有「開啟網頁終端機」按鈕，有些 add-on 內建 shell，點下去就直接在容器內、免 docker exec。

7. 影片跑完 push_drive 那一段整個沒執行

   可能三個原因：（a）你 upload_to 沒設對，回上一節檢查。（b）你的 pitch_video skill 版本太舊還沒支援自動上傳。看 skill 的 CHANGELOG，如果沒 upload_to 這個欄位就是版本太舊，去 GitHub 拉新版。（c）skill 的 push_drive.sh 因為 rclone 沒設好整個被 skip 掉——去看 skill 的執行 log，會告訴你它為什麼跳過。

8. OneDrive 傳到一半失敗 / 有些檔名 Google Drive 可以但 OneDrive 不行

   OneDrive 對檔名的限制比 Google Drive 嚴（:、?、*、<、>、| 這些字元都不能用）。你的影片檔名如果含這些字元（例如「客廳：先開燈？」）OneDrive 會拒收。做法：在 rclone 那邊加 --onedrive-server-side-across-configs 或在檔名生成時就用底線代替特殊字元。最簡單的做法是叫 pitch_video skill 產生檔名時就走英數限制（例如 living_room_lights_20260814.mp4）。

常見問題