你已經讀過的兩件事，其實是同一件事

第 1 篇告訴過你，首次啟動要花 3-8 分鐘，過程中工作區可能看起來像壞掉了。第 11 篇告訴過你，影片管線得先有一整套工具，才能錄畫面、配音或上字幕。

這不是兩件事。這是同一件事被講了兩次。那頭 3-8 分鐘 就是 工具正在到貨。

想通這一點之後，那些開頭是 video-tools-init: 的 Log 分頁裡的訊息，看起來就不再像錯誤，而像一條進度條。

三組工具，你會下載其中兩組

video-tools 不是一個程式。它是三組東西的統稱，而大家常說的那個數字，只包含前兩組。

所以真正落在 /data/pi-agent/ 裡的，是首次啟動時的前兩排，加起來大約 600-700 MB。精確數字會隨 Playwright 跟 pip 版本浮動，這也是為什麼這份教學把它概略講成 720 MB。第三排早就到了，包在那個大約 300 MB 的映像檔裡。

如果你永遠不做影片，能跳過這次下載嗎？

沒有任何官方支援的設定能做到。三個理由，沒有一個讓人滿意：

• 沒有關閉開關。 這個初始化程序是跟工作區一起啟動的服務。Configuration 分頁裡沒有能停用它的選項。
• VIDEO_PIPELINE_ENABLED=false 沒有用。 這個變數關不掉 add-on 的初始化程序。這是常見的錯誤猜測。
• 要避開它，代表你得自己編譯。 你得 fork 這個 add-on 的倉庫、拿掉那個服務、自己建映像檔再發布——比在硬碟上留著那 720 MB 麻煩得多。

以 Home Assistant 建議的最低 32 GB 硬碟來算，720 MB 大概佔 2%，而且正常情況只會發生一次。如果這 2% 是關鍵，那你的儲存空間大概本來就不夠 Home Assistant 舒服地用。

兩件事同時啟動，只有一件是慢的

當你點下 Start，會有兩個程序同時開始跑。工作區是一個 Node.js 應用程式，維持對話既不需要 Chromium 也不需要 Python，所以幾秒鐘就緒。工具下載在它背後進行。

flowchart TD
  S["你點下 Start"] --> W["pi-web 就緒
幾秒鐘——你就能開始聊天"]
  S --> V{"Sentinel file present
and venv/bin/python3 runnable?"}
  V -->|"是，之後每次啟動都一樣"| K["跳過。幾乎立刻結束"]
  V -->|"否，首次啟動"| A["1 · 建立 Python 環境
大約 10 秒"]
  A --> B["2 · pip 安裝 playwright、edge-tts、
pyyaml、mutagen
大約 30 秒到 2 分鐘"]
  B --> C["3 · Playwright 下載 Chromium
大約 2-6 分鐘，佔了大部分等待時間"]
  C --> D["4 · 寫入標記檔
/data/pi-agent/.video-tools-installed"]

這個檢查測試的是兩件事，不是一件：標記檔必須存在 而且 venv/bin/python3 必須能執行。只還原貼紙、不還原箱子，是騙不過它的。

這也回答了那 720 MB 什麼時候會回來。重啟這個 add-on、重啟 Home Assistant、正常升級，都不會動到這兩樣東西，所以什麼都不會下載。只有三種情況會讓它回來：你解除安裝時沒保留資料、你在新硬體上還原快照，或你刻意用了重置開關。

親眼看著它發生

打開這個 add-on 的 Log 分頁。正常跑起來會像這樣：

分頁本身如下圖。這張截圖來自一個已經跑了一段時間的工作區，所以安裝的那幾行早就被捲上去了，畫面裡填滿的是普通的流量紀錄——這也正是下載結束之後，同一個分頁該有的樣子。

Log 分頁唯一能告訴你下載有沒有在動的地方。其他任何地方，不管它在不在跑，看起來都一樣。這是啟動完成後的截圖，不是啟動當下

• Log 分頁在 add-on 頁面最上方，跟 Info、Documentation、Configuration 並排。日後出任何問題，這裡也是第一個該查的地方。
• Search logs，在輸出上方的那個欄位，是在忙碌的 log 裡找到你要的那幾行的方法。輸入 video-tools-init ，就只會留下安裝相關的訊息。
• 畫面主體 是網頁伺服器的存取紀錄——重複出現的 GET /api/agent/running/events 請求，來自你自己的瀏覽器，各自帶著時間戳記跟瀏覽器字串。這是例行的，不是錯誤。
• 那些請求那幾行帶著一個 session= 這樣的識別碼，代表你的連線 session。貼到任何公開的地方之前先把它剪掉。
• Live，在右下角，代表這個畫面正跟著新輸出即時更新。首次啟動時你可以開著它盯著看。

你的快照刻意不帶走那 720 MB

Pi Agent 會告訴 Home Assistant 把某些檔案排除在快照之外，影片工具就在那份清單裡。這是刻意的，不是疏漏。

兩個理由。大小：每份快照多加大約 700 MB，光是這一個 add-on，一年 12 份月快照就要多耗掉大約 12 GB。還有需要性：還原之後，那個檢查會因為 Python 環境不見而失敗，工具會自己重新安裝。還原多花大約五分鐘，換來每份快照少 700 MB。

reset_video_tools，以及什麼時候別去動它

Configuration 分頁裡有一個開關叫 reset_video_tools。它只做一件事：在下一次啟動時，刪掉標記檔、Python 環境跟 Chromium 快取，讓那整個 720 MB 乾乾淨淨地重新下載。

這是容器層級的選項，所以它放在這個 add-on 自己的 Configuration 分頁裡，不在 Home Assistant 設定的任何地方。那個分頁長這樣：

Configuration 分頁Options 面板，捲到清單最上面幾個關鍵欄位。重置開關就在同一份表單裡，在畫面下方，截圖沒拍到。

• Configuration 是 add-on 頁面最上方四個分頁之一——Info、Documentation、Configuration、Log——不在 Home Assistant 設定的任何地方。路徑： Settings → Add-ons → Woow HA Pi Agent → Configuration。
• Options 是裝著每一項容器設定的單一表單，一行一個欄位。截圖只拍到一半，剩下的要往下捲。
• 眼睛圖示 在每個已填欄位旁邊，能顯示原本用點點遮起來的值。用來檢查貼上的金鑰很方便，但這也是為什麼不該在數值展開時截這個分頁的螢幕截圖。

往下捲那份表單，會看到 reset_video_tools，一個 true/false 的開關，頁面最下面是 SAVE 按鈕。

1. 步驟 1

   打開 Configuration 分頁

   前往 Settings → Add-ons → Pi Agent → Configuration。

2. 步驟 2

   把 reset_video_tools 從 false 改成 true，再按 SAVE

   這時候還什麼都沒被刪掉。這個開關只是留給下次啟動的一張便條。

3. 步驟 3

   回到 Info 分頁，點 RESTART

   重啟時，這個 add-on 會執行 rm -rf /data/pi-agent/.video-tools-installed /data/pi-agent/venv /data/pi-agent/playwright-cache 並記錄 reset_video_tools=true — clearing venv + playwright-cache + sentinel。接著那 3-8 分鐘的下載就會重新開始。

4. 步驟 4

   檢查 log，如果跳過了就再重啟一次

   重置跟初始化程序是並行執行的，所以初始化程序有可能在重置刪掉舊標記檔的前一刻讀到它。如果 log 顯示跳過、後面也沒接著安裝流程，就再重啟一次。

5. 步驟 5

   之後就別再去動這個開關

   從 v0.13.0 開始，這個 add-on 會自己把它關回去，並記錄 reset_video_tools auto-reverted to false。只有在你看到 Could not auto-revert reset_video_tools時，才需要手動關掉它。舊教學說永遠要手動關，那個建議已經過時了。

這真的是你的問題嗎？

這個開關是逃生門，不是例行保養。規則很簡單：工具壞了才重置，不是為了讓它感覺比較乾淨才重置。

分辨下載是慢，還是已經死了

如果某個階段超過十分鐘沒有新的 log 輸出，也沒顯示任何錯誤，先檢查兩件事。打開 Settings → System → Network 確認主機真的有網路。接著看這個 add-on 的 Info 分頁裡的 CPU 跟記憶體——那裡有活動就代表還在運作，繼續等就好。

接下來往哪走