大部分版本你直接安裝就好。有一個不行。

Pi Agent 大約半年內從 0.1.0 出到 0.13.1，跨了超過二十個版本。幾乎全部都是你根本不用去想的修正：Ingress 背後的 nginx 表現得更好、log 訊息更清楚。安裝，繼續過日子。

但每隔一陣子，會有一個版本改動了你已經設定好的東西。這叫做 breaking change（破壞性變更），目前為止最大的一次就是 v0.13.0。

三個習慣能帶你安然度過任何版本，這篇文章就是圍繞著它們寫的。按 Update 之前先備份、複製好你的金鑰。讀更新說明時留意 Breaking 跟 Migration。在你需要之前，先搞懂回頭路怎麼走。

七個密碼欄位，搬家沒留轉寄地址

在 v0.12.x 以前， Add-on → Pi Agent → Configuration 顯示七個密碼欄位，一個供應商一個：GLM、MiniMax、OpenAI、OpenRouter、Anthropic、DeepSeek 跟 Groq。你在那裡貼上金鑰，點 Save，重啟。啟動時 pi-web 會把它們寫進 /data/pi-agent/models.json，聊天功能就能用了。

從 v0.13.0 開始，那一整組欄位不見了。取而代之的是四個容器層級的選項：

金鑰現在只住在一個地方： Models 面板，在 pi-web 裡，就是你在第 3 篇用過的那個畫面。

flowchart TD
  A["Configuration 分頁
七個密碼欄位"] --> C["/data/pi-agent/models.json"]
  B["pi-web 裡的 Models 面板"] --> C
  C --> D["兩個寫入者，一個檔案。
在 pi-web 裡加的供應商，
可能在下次重啟時被移除。"]
  D --> E["v0.13.0 讓 Configuration 分頁
完全不再寫入這個檔案"]
  E --> F["一個寫入者，不會互相覆蓋——但也
沒有路能把你的舊金鑰帶過去"]

沒有自動遷移這回事。CHANGELOG 講得毫不客氣： no auto-migration; hard cut。你舊的 models.json 還在硬碟上，但裡面的佔位符—— "$GLM_API_KEY" 跟它另外六個同類——現在都解析成空字串。每個請求都會回傳 401，直到你重新輸入金鑰為止。這是預期中的狀態，不是壞掉了。

升級之前的 Configuration 分頁v0.13.0 移除的那七個金鑰欄位。從 Add-on → Pi Agent → Configuration 進去。

• 七個欄位，一個供應商一個 —— api_key、 minimax_api_key、 openai_api_key、 openrouter_api_key、 anthropic_api_key、 deepseek_api_key、 groq_api_key。這就是消失的那一組。
• 眼睛圖示 在每一列右側，能顯示存起來的值。這就是升級前把金鑰複製出來的方法，這一步沒有任何替代方案。
• 四個填了，三個空著 ，這裡很正常——你只會填你真正在用的供應商。把填了的複製出來；其他的沒東西好複製。

從 v0.12.x 升級到 v0.13.x，按順序來

1. 步驟 1

   建立一份 Home Assistant 備份

   前往 Settings → System → Backups → Create backup。選完整備份，或至少要包含 Pi Agent 這個 add-on。取一個你之後認得出來的名字，例如 pre_pi_agent_0.13.0。通常 1-3 分鐘，這就是你的復原點。

2. 步驟 2

   把每一把 API 金鑰複製進密碼管理器

   打開 Add-on → Pi Agent → Configuration。展開並複製每一個有值的 *_api_key 欄位。升級之後，這是你唯一能找回那些值的方法。

3. 步驟 3

   在 Info 頁面點 Update

   打開 Add-on → Pi Agent → Info。新的版本號跟 Update 按鈕在最上面。Supervisor 會下載新的映像檔並重啟容器，通常 2-5 分鐘。 Log 分頁上跳出一連串訊息是正常的。

4. 步驟 4

   檢查 log，確認乾淨啟動

   看到一行寫著 pi-web listening on :30141 ，就代表 pi-web 正在運作。你可能也會看到 401 的警告，因為金鑰現在是空的。這個時間點，那些警告是對的。

5. 步驟 5

   在 Models 面板裡重新輸入每一把金鑰

   從側邊欄打開 Pi Agent，接著點 Models 分頁。每個供應商的 API Key 欄位都會是空的，或標示「Not set」。點 Edit，貼上金鑰，點 Test，等綠色勾勾出現，然後 Save。你用的每個供應商都重複這個流程。

6. 步驟 6

   送一則訊息證明它能用

   開一個新 session，選一個供應商，送一句「你好」。正常的回覆代表兩件事都成功了——升級跟金鑰。之前的 Session 應該還在清單裡。

7. 步驟 7

   順便設一下你的時區

   回到 Add-on → Configuration，設定 timezone 成你的 IANA 識別碼——台灣的話， Asia/Taipei。這樣 log 的時間戳記才會跟你的時鐘對得上。其他三個別去動。

步驟 3 從這裡開始0.12.0 版的 Info 頁面——這次遷移的起點版本。

• Current version: 0.12.0 在標題下面，告訴你目前站在遷移的哪一邊。在 0.12.0，就像這裡一樣，那七個金鑰欄位還在 Configuration 分頁上等著。
• Changelog 是個連結，就在版本號旁邊。點開它就是這篇文章最後一節要你讀的那份文件。
• Autoupdate 是四個開關裡的第三個，在這張截圖裡是關閉的。就讓它保持關閉；最後一節會解釋原因。

任何一次升級之後，該看的五件事

每次升級之後都跑這個檢查，不管是不是破壞性變更。這樣問題會現在被抓出來，而不是在某件重要的事情進行到一半時才發現。

• 側邊欄按鈕。 重新整理 Home Assistant。Pi Agent 應該還在左側邊欄裡。
• 供應商。 打開 Models。你設定過的每個供應商都應該還在清單裡，而 Test 在每一個上都該變綠。紅色叉叉通常代表金鑰無效。
• 你的對話。 檢查 Sessions 清單。舊對話應該都在，也應該還打得開。如果有不見的，就還原備份。
• 你的 Skill。 打開 Skills。之前裝過的每一個都應該還在清單裡。
• 一則新訊息。 開新 session，選一個供應商，打聲招呼。大約三秒內收到回覆就算通過測試。

如果最後這項失敗了，錯誤代碼會指出方向： 401 代表金鑰不見了或錯了， timeout 暗示供應商壅塞或 VPN 斷線，而 404 通常代表一個已經不存在的模型名稱。

不然的話，把症狀對應到背後的版本：

沒有回退按鈕，所以才有備份

Pi Agent 沒有一鍵還原的按鈕——這是 Home Assistant add-on 普遍的情況，不是這個 add-on 特有的缺陷。它留下兩條回頭路。

標準路徑：還原備份

前往 Settings → System → Backups ，找到步驟 1 做的那一份。點 Restore，選擇只還原 只還原 Pi Agent 這個 add-on，等 3-5 分鐘，讓 Supervisor 重新安裝舊的映像檔，把之前的 /data/pi-agent/放回去。你會回到原本的狀態：版本、金鑰、Sessions、Skills。

進階路徑，以及為什麼它排第二

Info 頁面的三點選單可能會提供 Install a specific version，讓你指定一個較舊的版本標籤，例如 0.12.0。有些版本的 Home Assistant 只有在開啟 Advanced Mode 時才會顯示這個選項。問題在於：你的 /data/pi-agent/ 會維持在較新版本留下的狀態，而較舊的版本可能讀不懂較新的 models.json 結構。有疑慮的話，還是還原備份。

不管走哪條路，確認 Autoupdate 在你離開之前是關閉的。不然過幾天你會不小心把這整套流程再走一遍。

一個月三分鐘的閱讀

每個版本改了什麼、有沒有破壞性變更，都記錄在 GitHub 上的一個檔案裡：

你不需要懂 GitHub 才能讀它。打開這個網址；最新的版本在最上面。你要掃視找的是五個關鍵詞：

v0.13.0 那條說明就示範了這有多好讀。它的第一行：「BREAKING: AI provider API keys moved out of the addon Configuration tab into the pi-web UI.」再往下：「Migration: after upgrade, open pi-web and re-enter each key inside the Models panel.」這篇文章大部分的內容，其實就藏在這兩句話裡。

flowchart TD
  A["出現一個新版本"] --> B{"Does the entry say
BREAKING or Migration?"}
  B -->|"是"| C["備份、複製好金鑰、
讀完整條更新說明"]
  B -->|"否"| D{"Does it fix something
that is blocking you?"}
  C --> E["安裝，接著跑
三分鐘的檢查"]
  D -->|"是"| E
  D -->|"否"| F["等一週；讓早期使用者
先踩過那些粗糙的地方"]

對一個更新速度這麼快的 0.x add-on 來說，讓 Autoupdate 保持關閉。三個理由：

• 它會跳過你的備份。 Supervisor 一看到新版本就會安裝。它不會停下來提醒你先做一個復原點。
• 它沒辦法幫你做遷移。 沒有任何自動化程序會幫你把金鑰複製進 Models 面板。你會在事情發生的好幾天後，某個早上，迎面撞上滿螢幕的 401。
• 剛出的版本總有些粗糙的地方。 等一週，讓別人先踩過雷，維護者也能發一個 x.y.1——就像 v0.13.1 修掉那個 413 上傳問題一樣。

反過來，一週看一次 add-on 頁面，或找個空閒的週末看。大約一個月會累積出一次該裝的更新；備份跟安裝同一天做，這兩件事就會變成一個習慣。如果你要照顧兩個地方的 Home Assistant，兩邊間隔一週再升級，這樣就算遇到爛版本，你手上還有一套能用的系統。

接下來往哪走