它是附加元件，不是另一個要註冊的 App

Pi Agent 的安裝方式跟任何一個 Home Assistant 附加元件一樣。裝完之後，左邊側邊欄會多一個項目。點進去，你就在一個看起來有點像聊天視窗的工作區裡——差別在於這一個讀得到檔案、跑得動指令，而且能真的改動它所在的那台機器。

這也是為什麼它不等於一個你開分頁就能用的聊天網站。住在 Home Assistant 裡面，帶出三件事：

• 它碰得到你的檔案。 工作區裡有檔案總管和終端機，指向 Home Assistant 主機上的一個資料夾。
• 它用你原本的 Home Assistant 帳號。 不用再開第二個帳號。你登入了 Home Assistant，就等於登入了它。
• 你這一側的東西，留在你這一側。 檔案、終端機、工作區都在你自己的硬體上。只有你送出的那段文字會出去給 AI 供應商，而且只在你按下送出的時候。

flowchart LR
  A["你的瀏覽器"] --> B["Home Assistant Ingress"]
  B --> C["附加元件裡的 nginx"]
  C --> D["pi-web，你看到的工作區"]
  D --> E["pi coding agent SDK"]
  E --> F["主機上的檔案與終端機"]
  E --> G["網路上的 AI 供應商"]

整張圖裡真正新的只有最後那一個箭頭。Home Assistant 其他部分跑的都是你自己寫好的規則；這一段則是把你的話送到別處的模型、再把答案帶回來。這就是這筆交換，裝之前值得先知道。

動手前先確認兩件事

大部分條件會自己成立。有兩件不會，而且兩件都很快就能查。

你的 Home Assistant 裝得了附加元件嗎？

只有部分安裝方式的 Home Assistant 裝得了附加元件。到 設定 → 系統 → 關於 看一下安裝類型。

你是管理員嗎？

安裝附加元件需要管理員帳號。如果你的 Home Assistant 是一般使用者，設定裡根本不會出現「附加元件」這一區——這很容易誤判，因為看起來像選單壞了，而不是被藏起來。

其餘的，簡單講

• 處理器： amd64 或 aarch64——涵蓋 x86 小主機、樹莓派 4 與 5，以及大多數 arm64 單板電腦。
• 記憶體： 2 GB 跑得動工作區。開始用影片工具之後，4 GB 以上才算寬裕。
• 硬碟： 留大約 3 GB。這不是官方硬性下限，而是給下載、log、快取和 Home Assistant 備份的餘裕。
• 網路： 主機要連得到 ghcr.io 才抓得下映像檔。

先加倉庫，再裝附加元件

Pi Agent 不在官方的附加元件商店裡。它放在 WoowTech 維護的倉庫，所以你得先告訴 Home Assistant 去哪裡找，才裝得起來。前三個步驟就是在做這件事。

1. 步驟 1

   打開設定，再進附加元件

   到 設定 → 附加元件。如果設定選單裡沒有「附加元件」，回頭確認上一節那兩件事——安裝類型與管理員權限。

2. 步驟 2

   打開商店，再點三點選單

   點右下角的 Add-on store（附加元件商店） ，接著點該頁右上角的三點選單，然後選 Repositories（儲存庫）。

3. 步驟 3

   貼上這個網址，按 Add

   把下面的倉庫網址貼進欄位，按 Add（加入），再按 Close（關閉）。

   https://github.com/WOOWTECH/Woow_ha_pi_agent_add_on

   商店頁會重新載入，並多出一個新的區塊。

4. 步驟 4

   找到 Woow HA Pi Agent 並打開

   往下捲到 WoowTech HA Pi Agent Add-on Repository 這個區塊，點下去。你會進到它的 Info 頁，也就是下面這張圖。

5. 步驟 5

   按 Install，等映像檔下載

   這會拉一個大約 300 MB 的容器映像檔。網路正常的樹莓派上，整段安裝約 4-6 分鐘；x86 小主機或 NUC 約 1-2 分鐘。實際下載時間看你的網路。

6. 步驟 6

   打開 Start on boot、Watchdog 與 Add to sidebar

   有三個開關現在就值得設好。 Start on boot 會在停電後把它帶回來。 Watchdog 會在它掛掉時重啟。 Add to sidebar 才會把項目放進左邊選單——不開它附加元件照常能用，但你每次都得回到這一頁。

   把 Autoupdate 保持關閉。升級值得刻意進行，第 15 篇會講。

7. 步驟 7

   按 Start

   狀態大約 5-15 秒後會變成 Started。多數人就是在這時候直接點進工作區、然後看到一片空白——那是下一節的主題，而且是正常的。

Info 頁步驟 4 到 7 都在這一頁。這張圖是安裝並首次啟動之後拍的，所以底下那排是 Stop 和 Restart，不是 Install。

• Current version: 0.12.0 在標題下方，旁邊有 Changelog 連結。把版本號記下來——你回報問題時，這是任何人都會先問的一件事。
• Ingress 是那個藍色徽章，就在綠色的 Rating 徽章旁邊。有這個徽章，存取權才會跟著你的 Home Assistant 帳號走，而不是另設一組密碼。
• Start on boot, Watchdog and Add to sidebar 在這裡是開啟的，而 Autoupdate 是關閉的。這正是步驟 6 要的組合。
• Add-on CPU usage 與 Add-on RAM usage 在右欄，附加元件閒置時都顯示 0%。記住它們的位置——覺得哪裡不對勁時，這是最快的檢查點。
• Open web UI 是右下角的藍色按鈕，在 Uninstall 旁邊。 Stop 與 Restart 在左下角，第 15 篇你會再回到這裡。

顯示 Started，還不等於準備好

這一段最常讓人誤判，所以值得弄懂，而不是乾等。

當附加元件顯示 Started的時候，工作區本身其實已經跑起來了。但一個叫 video-tools-init 的背景服務還在忙。在它跑完之前，打開工作區可能會看到一片空白、一個轉圈圈，或是連線被拒絕。這些都不代表安裝失敗。

它在卸的是大約 720 MB 的影片工具，分四步：

flowchart TD
  A["附加元件顯示 Started
約 15 秒"] --> B["1 · 建立 Python 環境
約 20 秒"]
  B --> C["2 · 安裝 playwright、edge-tts、
pyyaml、mutagen
約 30-90 秒"]
  C --> D["3 · 下載並解壓 Chromium
最大的一步，2-6 分鐘"]
  D --> E["4 · 寫入完成標記
/data/pi-agent/.video-tools-installed"]
  E --> F["工作區完全就緒"]
  F -.->|"之後每次啟動"| G["找到標記，整欄
在 100 毫秒內跳過"]

官方文件說首次啟動在樹莓派上要 3-8 分鐘、x86 上 1-2 分鐘。這兩個總時間跟「光是第 3 步就要 2-6 分鐘」擺在一起有點矛盾，所以請把 x86 的數字當成下限而不是承諾，判定它出問題之前先多給它一點時間。

你可以直接看它在做什麼，不必用猜的。在附加元件頁面打開 Log 分頁——附加元件的輸出都寫在這裡，首次啟動也不例外；之後有任何問題，這也是第一個該看的地方。

Log 分頁Log 是上排第四個分頁。這張圖來自已經跑了一陣子的附加元件，所以畫面上填滿的是日常的網頁流量，不是首次啟動的輸出。

• Search logs 可以過濾行數。早點知道有這個功能比較好——這個面板一天之內就會長到好幾千行。
• Live在右下角，代表畫面還在跟著新輸出走。首次啟動時你會希望它保持這個狀態。
• 這裡的每一行是 nginx 存取紀錄 ——你的瀏覽器每經由 Ingress 送出一個請求就一行。像這樣穩定的流量代表附加元件很健康，不是故障。
• 這些行裡包含 Ingress 工作階段識別碼。把 log 貼到論壇或 issue 之前，先把這段剪掉。

工作區長什麼樣

點側邊欄新增的那個項目，或是附加元件頁面上的 Open web UI 。兩個都會到同一個地方。

下面這張圖來自一台已經用了一段時間的機器，所以側邊欄裡有對話、檔案總管裡有檔案。全新安裝的擺設一模一樣，只是裡面還沒有東西。用這張圖認位置，你自己看到的會是空的那一版。

一個等你打字的對話拍攝於已在使用中的機器，所以左邊清單不是空的。你自己的會是空的。

• + New在左上角，用來開一個對話。它底下的東西都是歷史紀錄和檔案，不是你需要去設定的項目。
• ~/pi-cwd-20260909 是專案路徑——這個工作區指向的、位於 Home Assistant 主機上的資料夾。你的日期會不一樣。
• 左欄的 對話清單 這裡有三筆，每一筆都標了時間與訊息數。其中兩筆標題是中文：介面是英文的，但你要用什麼語言跟它講都可以。
• EXPLORER在同一欄再往下，列出那個資料夾裡有什麼。這一台裡面有一個先前留下的 notes.md 。
• Models, Skills and Settings 橫排在 左下角，不是上面。第 3 篇會叫你去 Models。
• 左欄的 訊息輸入框 位在中間，這就是整個介面。它下面那一列寫著目前的模型——這台機器上是 GPT-5.6 Sol——旁邊是 auto、default 和 Compact。

那個模型名稱，是全新安裝時圖裡唯一不會有的東西。在你接上一家供應商之前，那顆按鈕後面什麼都沒有，所以現在打什麼字都不會有反應。那是第 3 篇的事。到這一步，唯一需要成立的是：頁面載得出來，而且上面這些部件都在。

真正會出錯的四件事

接下來往哪走