升級 Pi Agent：v0.13.0 API key 搬家踩雷筆記

為什麼升級這件事值得單獨開一章

Home Assistant 生態的 add-on 更新頻率比一般 App 高很多——Pi Agent 從 0.1.0 到 0.13.1 大概半年就出了 20 幾版。多數是幕後修正（Ingress 相關的 nginx 修 bug、log 訊息改得更清楚），你按「更新」直接走人不會有事。但每隔一段時間會出現一種「打破你既有設定」的版本，官方叫它 breaking change。

Pi Agent 目前最有感的一次就是 v0.13.0：本來你在 HA 的 Add-on → 設定分頁能看到「GLM API Key」、「OpenAI API Key」、「Anthropic API Key」……七個密碼欄位，升上去之後整組通通消失。畫面乾淨到讓人以為裝壞了。實際上金鑰沒被刪，只是它們現在住在第 6 章講的那個 pi-web Models 面板裡面，需要你手動再貼一次。

這章想給你三個實用的能力：

• 升級前的固定動作——做一次 HA snapshot（第 20 章教的）、把當下的金鑰複製到密碼管理器，就算升壞了也能 3 分鐘救回來。
• 看得懂 CHANGELOG——每個版本裡面有沒有 Breaking、Migration required 這幾個關鍵字，看到了就要停下來讀完再按更新。
• 降級（downgrade）策略——Pi Agent 沒有一鍵回退按鈕，靠的就是升級前那個 snapshot。這章告訴你怎麼還原、還原後對話會不會不見。

Pi Agent 版本時間軸：你會經過哪些關卡

如果你今天才裝 Pi Agent，直接就是最新版，這節可以當背景知識略讀。如果你是從舊版一路升上來的老用戶，這張時間軸會告訴你「哪幾個版本我升上去要特別注意」。

v0.13.0 breaking 的來龍去脈

這是這章最重要的一節，因為 90% 從舊版升上來的人踩的坑都是這個。

舊版（v0.12.x 及以前）的世界：打開 HA → Add-on → Pi Agent → 設定 分頁，你會看到一整排密碼欄位——

api_key:              <GLM 金鑰>
minimax_api_key:      <MiniMax 金鑰>
openai_api_key:       <OpenAI 金鑰>
openrouter_api_key:   <OpenRouter 金鑰>
anthropic_api_key:    <Anthropic 金鑰>
deepseek_api_key:     <DeepSeek 金鑰>
groq_api_key:         <Groq 金鑰>

你在這裡貼金鑰、按儲存、按重啟，pi-web 就會在開機時把這些 key 寫進 /data/pi-agent/models.json，然後聊天頁就跑得動。

新版（v0.13.0 之後）的世界：那七個密碼欄位整組刪除。設定分頁改成放四個 container 層級的選項：

金鑰的家搬到 pi-web Models 面板——就是你左邊 tab 點「Models」進去、按「+ Add Provider」、填 baseUrl 跟 key 那個地方。

為什麼要動這麼大？官方 CHANGELOG 給的理由很直白：以前有兩個地方都在寫 /data/pi-agent/models.json——HA 的 Configuration 分頁跟 pi-web 的 UI，兩邊會互相蓋來蓋去。你在 pi-web 加了一家新的 provider（例如 xAI Grok），一重啟 add-on，開機腳本又把它拿掉，因為它「不在 HA 設定分頁的白名單」。同一件事只交給一個地方管，是這個 refactor 的動機。

不會自動搬家：CHANGELOG 明講「no auto-migration; hard cut」——升級不會幫你把舊金鑰塞進 Models 面板。舊的 models.json 檔還在，但裡面那些 "$GLM_API_KEY" 這種環境變數占位符會解析成空字串，所以你聊天就會全部 401。這是官方預期的過渡狀態，不是 bug。

從 v0.12.x 升到 v0.13.x 的完整 SOP

下面這一串照著做，就算是完全不敢動系統的人也能安全走過去。

1. 升級前先做 HA snapshot

   第 20 章詳細講過：HA 側邊欄「設定 → 系統 → 備份 → 建立備份」，勾「完整備份」或至少勾 Pi Agent 這個 add-on。取名叫 pre_pi_agent_0.13.0 之類的方便日後找。等它跑完（約 1-3 分鐘），這是你的救命底牌。

2. 複製所有 API 金鑰到密碼管理器

   打開 Add-on → Pi Agent → 設定 分頁，眼睛看到的每一個 *_api_key 欄位都按顯示、複製、貼到密碼管理器。至少要有 GLM、OpenAI、Anthropic、DeepSeek、Groq、OpenRouter、MiniMax 這七個（有填哪幾個就複製哪幾個）。這一步是升級後救回金鑰的唯一路徑。

3. 回 Add-on 頁按「更新」

   Add-on → Pi Agent → 資訊分頁，最上面會顯示新版號跟「更新」按鈕。按下去，Supervisor 會拉新映像、重啟容器，整個過程 2-5 分鐘（首次拉 image 可能長一點）。期間 Logs 分頁會刷過一堆訊息，正常。

4. 升級完成後，先看 Logs 分頁確認沒錯

   看到 pi-web listening on :30141 或類似的訊息代表 pi-web 起來了。同時因為 models.json 裡的 key 都空掉，Logs 可能會有 401 警告——這是預期的，不用慌。

5. 打開 pi-web，把金鑰逐家貼回 Models 面板

   側邊欄按「Pi Agent」進去，左邊 tab 切到 Models。每一家 provider 你會看到 API Key 欄位是空的或標成「未設定」。按下編輯，把剛剛從密碼管理器複製的金鑰貼回去。按 Test，看到綠色勾勾表示連得上，按 Save。七家一次做完。詳細操作跟第 6 章一模一樣。

6. 回主聊天頁開新對話驗證

   主聊天畫面 → 開新 session → 隨便選一家 provider → 送「你好」出去。收到正常回覆就代表升級 + 金鑰搬家全部完成。舊的 session（升級前開的那些）也還會在，直接繼續講也 OK。

7. 順手看看新增的四個 container 選項

   回 Add-on → 設定分頁，看看 log_level、timezone、reset_video_tools、env_vars 這四個新選項。多數人只需要把 timezone 改成 Asia/Taipei——之後 log 的時間戳跟排程都會對到台灣時區。其他三個先不動，用預設就好。

升級後的固定檢查清單（每次都做）

不管是升 v0.13.0 這種大改版還是升 v0.13.1 這種小補丁，養成升完馬上跑一次下面這張清單的習慣。3 分鐘走完，有問題馬上抓到、不會拖到某天要用的時候才發現。

1. HA 側邊欄的 Pi Agent 按鈕還在嗎

   刷新一次 HA 網頁，看左邊側邊欄「Pi Agent」（機器人圖示）還在不在。v0.8.0 之後這個按鈕會在開機時自動被啟用，正常情況不會消失。消失了看下方 troubleshoot 第 3 條。

2. Models 面板每家 provider 都在、都是綠燈

   左邊 tab → Models。你原本設定的 7 家 provider 應該一家不漏地列在那裡。每一家按一下 Test，全部綠燈才算數。有紅叉的通常是金鑰失效或該家 baseUrl 改了名字（極少見）。

3. Session 列表歷史對話都在

   主聊天畫面 → 側欄的 Sessions 列表。你升級前有的每一個對話應該都還列在那，點進去內容也還在。少了要立刻 restore snapshot（見下方降級章節）。

4. Skills 列表沒少

   左邊 tab → Skills。以前裝過的 skill 應該都還列在那。v0.12.0 之後有 git + openssh-client 撐著，重灌 skill 也不會壞。

5. 開新對話送一句，收到回覆算完成

   開新 session、選一家 provider、送「hello」。3 秒內看到回覆＝一切 OK。收到 401＝金鑰沒貼；收到 timeout＝該家 peak 時段擁塞或 VPN 斷；收到 404＝模型名寫錯（少數狀況新版可能改了 default 模型清單）。

降級（downgrade）怎麼做

Pi Agent 本身沒有「一鍵回退到舊版」的按鈕——這是所有 HA add-on 的通性，不是 Pi Agent 特別壞。要回舊版有兩條路，第一條是主流做法，第二條是進階解法。

1. 主流做法：從 snapshot restore

   HA 側邊欄「設定 → 系統 → 備份」，找到你升級前建立的那個 snapshot（就是 SOP 第 1 步做的那個），按「還原」→ 選「只還原 Pi Agent 這個 add-on」，等 3-5 分鐘 Supervisor 重新裝一次舊版映像檔＋還原舊 /data/pi-agent/ 目錄。做完之後 add-on 就完全回到升級前的狀態，包括版本、金鑰、Session、Skills。這是為什麼第 20 章一直強調「升級前備份」不是可有可無的建議。

2. 進階做法：安裝指定版本

   Add-on → Pi Agent → 資訊分頁右上角的三點選單（不同 HA 版本 UI 位置略有差異，有的在資訊分頁右上、有的要先開「進階模式」才會出現）通常會有「Install a specific version / 安裝特定版本」選項。填舊版號（例如 0.12.0），Supervisor 會去 GHCR 拉那個 tag 重新裝一次。但——你的 /data/pi-agent/ 目錄不會變，還是新版寫進去的狀態，可能有相容性問題（新版寫的 models.json schema 舊版讀不動之類）。這條路只推薦給熟系統的人，一般人優先走 restore snapshot。

3. 還原後新對話會不會不見？

   會。snapshot 是「時光機」——還原之後你在升級後開的那幾個 session、貼的新金鑰、裝的新 skill，全部回到升級前那一刻的狀態，之後做的東西全部消失。所以還原前要想清楚：如果你升級後已經開了重要對話，考慮先把那些 session 的 .jsonl 檔手動 export 出來（第 8 章教過怎麼找 session 檔），還原完再手動貼回 /data/pi-agent/sessions/。

4. 還原之後最好也把新版更新按鈕先關掉

   不然過幾天你不小心按了「更新」，又升上去一次。HA 沒有「暫停這個 add-on 的更新提醒」的正式開關，但你可以在 Add-on 頁把「Auto update」關掉（如果之前不小心打開了），並在心裡標記「這個版本我暫時不要升」，等原廠出下一版修好 breaking 影響的問題再考慮。

升級後常見症狀對照表

升完發現不對勁的時候，先看這張表比對你的症狀，多數狀況對得上。對不上再往下翻 troubleshoot 一節。

怎麼看發布說明（CHANGELOG）

Pi Agent 的每一版都會把「改了什麼、為什麼改、有沒有 breaking」寫在同一個 CHANGELOG.md 檔案裡，公開在 GitHub 上：

https://github.com/WOOWTECH/Woow_ha_pi_agent_add_on/blob/main/CHANGELOG.md

不會看 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.」，直接告訴你搬家怎麼做。

要不要打開自動更新

HA 的 Add-on 資訊分頁上通常有一個 Auto update / 自動更新 開關（新版 HA 在資訊分頁頂端；舊版 HA 或未啟用「進階模式」時可能不會顯示，需要到「使用者設定」把進階模式打開才會出現），打開之後 Supervisor 會自己去拉新版裝上。理論上很方便，但對 Pi Agent 這種還在快速演進（0.x）的 add-on，不建議——原因三個：

建議的節奏：手動更新，一週一次或有空的週末去 Add-on 頁看一眼有沒有新版。有的話先讀 CHANGELOG 決定要不要升。不趕的話讓子彈飛一週再說。急的（例如你正好被某個 bug 卡到，看 CHANGELOG 剛好在新版修）就升。

升級過程常見卡關

1. 按下「更新」之後 add-on 起不來、Logs 全是紅字

   先別急著重灌。開 Logs 分頁往下滑找第一個「Error」或「Fatal」訊息（後面的多半是連鎖反應）。常見原因：（a）Docker 拉映像檔失敗——網路問題或 GHCR 暫時掛掉，等 5 分鐘按重啟；（b）設定分頁的欄位格式變了——例如 v0.13.0 之前 api_key: "xxx" 是字串，如果你自己手動改過 options.json 格式錯了，schema 驗證會 fatal；（c）你在 env_vars 打了不合法的變數名（不能以數字開頭、不能有連字號），CHANGELOG 說會在 set -e 階段停下來。找到第一條錯就八九不離十。

2. Add-on 頁面找不到「更新」按鈕

   兩種可能：（a）你已經在最新版了——上面小字會顯示 Current version: 0.13.1 (latest) 之類；（b）Supervisor 的 add-on 倉庫還沒重新整理索引——去 設定 → 附加元件商店 → 右上三點 → 「重新載入」，等 30 秒回來看。都不是的話重啟 HA Supervisor（設定 → 系統 → 重啟 Supervisor），通常就會抓到新版。

3. 更新跑到一半卡住不動

   不要重啟 HA！等它自己跑完。Docker 拉大 image（Pi Agent 因為含 Chromium + ffmpeg 有數百 MB）第一次可能拉 5-10 分鐘、慢一點的網路 15 分鐘都可能。如果超過 20 分鐘還沒動，去 Logs 分頁看有沒有錯誤訊息。真的完全卡死才考慮重啟 Supervisor 讓它重來，那之前的下載會作廢從頭來過。

4. 更新後金鑰貼回，但還是 401

   可能性：（a）貼的時候多按了一個空白或換行——回去密碼管理器複製時避開前後空白；（b）你把 GLM 的金鑰貼進了 OpenAI 那家 provider——金鑰不會通用，每家對得上才行；（c）新版預設模型名改了，例如 gpt-4o 已經沒有你要的變體了。開 Pi Agent 的 session log（在 第 8 章有教怎麼找 .jsonl）看實際的錯誤訊息，多半直接告訴你是哪家哪個模型 401 / 404。或直接參考第 22 章的整套錯誤代碼對照。

5. 更新後 video-tools 一直在跑，聊天很慢

   v0.11.0 或 v0.13.0（其中一次你觸發了 reset_video_tools）之後首次開機都要重新下載 720MB 的 Chromium + venv。這期間 pi-web 本身可以用（聊天不會壞），但影片管線相關功能會等到裝完。Logs 分頁裡搜 video-tools-init 看進度。裝完會建一個 sentinel 檔 /data/pi-agent/.video-tools-installed，之後每次開機它看到 sentinel 就 100 毫秒內結束不會再拖。詳細在第 18 章。

6. Watchdog 一直重啟 add-on

   v0.10.0 之後有 Supervisor watchdog 探 /api/home，pi-web 如果一直回 5xx 或不回，Supervisor 就會依 watchdog 探測週期反覆重啟。你在 Logs 分頁會看到「Watchdog restart of add-on pi-agent」不斷刷。這代表 pi-web 開機真的有問題（不是網路），跟第 1 條一起看第一個 error 訊息。無限重啟的解法：先把 add-on 手動關掉（Add-on 資訊分頁），再從第 1 條的方向 diagnose。

常見問題