把這篇加書籤，不是讀一遍就收起來

問題不會照教學的順序來：一把用了兩個月都沒事的金鑰，某個週二早上突然回傳 401。所以這篇是照症狀來安排的。先跑三項檢查，再跳到跟你螢幕對得上的那一節。

flowchart TD
  A["出問題了"] --> B["三項快速檢查"]
  B --> C{"What is on screen?"}
  C -->|"401 / 402 / 429"| D["金鑰、額度，或速率限制"]
  C -->|"404"| E["Ingress 跟這個 add-on"]
  C -->|"轉圈圈或空白頁面"| F["沒有錯誤代碼"]
  C -->|"Skill 或影片步驟"| G["工作流程各節"]
  C -->|"每分鐘都重啟"| H["Watchdog 迴圈"]
  D --> I["最後 30 行 log"]
  E --> I
  F --> I
  G --> I
  H --> I
  I --> J["GitHub issue"]

不到一分鐘，通常就夠了

1. 檢查 1

   這個 add-on 還在跑嗎？

   打開 Settings → Add-ons → Woow HA Pi Agent。綠色的 Started 代表正在運作。如果顯示 Stopped 或紅色，點 Start，給它 30-60 秒完成初始化，再試一次。

2. 檢查 2

   真的有選好一個供應商嗎？

   看訊息輸入框上方的模型選單。它應該顯示一個供應商跟模型，例如 GLM / glm-4.6。如果它是灰的，或顯示「No model」，打開 Models 面板，輸入金鑰，並確認 Test 成功。

3. 檢查 3

   這個網路連得上網際網路嗎？

   打開 https://www.google.com 在新分頁打開。如果打不開，先修好網路連線。如果一般瀏覽都正常、只有某個供應商連不上，查一下它的官方狀態頁面，並確認你的網路政策允許連到它的 API endpoint。

Info 頁面這裡幾乎每件事都會把你導回這個頁面——查狀態、查版本，或找一個開關。

• 最底下那排按鈕： Stop、 Restart、 Uninstall、 Open web UI。這裡會有 Stop，是因為這個 add-on 正在運作；已停止的話這裡會換成 Start——見上面的檢查 1。
• Current version: 0.12.0 在標題下面，旁邊有個 Changelog 連結。現在就把這個版本號記下來；每個求助請求都會問到它。
• Watchdog，在這張截圖裡是開著的——它會在這個 add-on 不再回應時把它重啟，而診斷重啟迴圈時，你就是要關掉這個開關。
• 側邊欄開關，標示為 Add to sidebar 在這個版本上， Show in sidebar 則是文件裡的寫法。如果 Pi Agent 在跑，但左側選單裡沒有入口，就是這個開關。

401、402、429、404：四種不同的拒絕方式

401 Unauthorized

右上角出現紅色的「401」或「Unauthorized」，而且沒有回覆：供應商拒絕了這組憑證。大約 90% 的情況是金鑰的問題。

402 Payment Required，或 429 Too Many Requests

一個 402，或訊息裡帶著 insufficient_balance、「insufficient balance」、「rate limit」或「quota exceeded」這類字眼。憑證可能是對的；只是這個帳戶沒有可用的額度、撞到配額上限，或正被限速。

insufficient_balance、 credits 跟 quota 指的是帳戶額度。 rate_limit 跟「too many requests」代表暫時性的限制：等一到兩分鐘，等待期間不要重複送出請求。

如果額度是空的，到負責你這條線路的供應商去加值——GLM 在 bigmodel.cn，OpenAI 在 platform.openai.com，Anthropic 在 console.anthropic.com，OpenRouter 在 openrouter.ai。不需要重啟；下一次請求就會用上新的額度。或者切到另一個已經設定並測試過的供應商跟模型，先確認過它的收費跟限制。

404 Not Found

選了側邊欄的 Pi Agent，或按了 Open Web UI之後，出現「404 Not Found」或「Ingress token invalid」。幾乎都跟 Ingress 有關——Home Assistant 用來代理 add-on 網頁介面的機制：它發出的是一張臨時門卡，門卡是會過期的。

側邊欄完全沒有入口

轉圈圈一直轉，卻等不到回覆

沒有任何東西指出問題所在：訊息送出去了，右下角出現轉圈圈，然後什麼都沒回來。照順序檢查四件事。

1. 第一

   確認基本狀況

   有選好模型嗎？ Test 在 Models 面板裡對那個供應商測試成功嗎？只要有一個答案是否，先把設定修好。

2. 第二

   給延遲留一點時間

   有推理能力的模型，可能要 30-60 秒甚至更久才開始回應。沒有一個放諸四海皆準的九十秒門檻——延遲取決於模型、線路、請求大小跟供應商的負載。把同一段提示送給另一個已設定的模型，就能分辨是哪種情況。

3. 第三

   檢查網路是不是擋住了這個 endpoint

   公司的 VPN、學校網路、DNS 過濾，或地區政策，可能擋住了某個供應商的 baseUrl。打開 https://api.openai.com 在瀏覽器裡是基本的連線檢查，不是完整的 API 測試——也要去讀官方狀態頁面，並從發出請求的那台主機測試 DNS 跟 HTTPS。如果真的被擋住了，切換到另一條你的網路跟所在地能支援的線路。

4. 第四

   給 Watchdog 一分鐘的時間

   很少見的情況，pi-web 還在跑，但不再回應。等它自動恢復：v0.10.0 加上的 Watchdog 每分鐘探測一次 /api/home ，並要求 Supervisor 重啟一個沒回應的 add-on。它會在 60 秒內察覺，所以總共給 60-90 秒，再重新打開 Pi Agent，讀一下 log。

如果請求還是一直完成不了，打開 Log 分頁，讀失敗那次嘗試前後的最後 30 行。複製下來，把任何敏感內容遮掉，拿去開一個 GitHub issue。

正常運作長什麼樣跑完的工具卡各自帶著計時跟成本，頂欄有一個 session 總計，Send 的位置換成了紅色的 Stop。

• 每個 工具卡 都帶著它花的秒數—— write notes.md 5 秒， read notes.md 2 秒——底下還有一行 token 跟成本： 1,180 in · 70 out · $0.0080。有新的卡片持續出現，代表工作還在進行。
• Waiting for model… 接在最後一張卡片下面。這一行是轉圈圈的老實版本：這一輪還沒結束，畫面上寫的就是它卡在哪裡。
• session 總計 在頂欄——這裡是 $0.02——會隨著工作進行往上爬。一個還在變動的數字，就是有活動的有用跡象。
• 訊息輸入框變成了 Steer now / queue follow-up ，帶著 Steer、 Follow-up ，跟一個紅色的 Stop。那個 Stop，而不是 Send，才是你想結束這一輪時該按的按鈕。

其他不太明顯的症狀

上面這幾節涵蓋了大約 90% 出錯的情況。剩下的：

失敗發生在一連串工具鏈裡的時候

一次影片工作流串起 5-6 個工具——文字轉語音、Playwright 錄製、ffmpeg 合成、字幕渲染、rclone 上傳——所以問題在於它停在哪個階段。

一個 Skill 裝不上去，或啟動不了

狀態顯示綠色，但 log 卻不斷重新開始

這個 add-on 顯示綠色，但 Log 分頁顯示 video-tools-init 或 pi-web 大約每 60 秒重新啟動一次，對話在回覆到一半時就斷線。Watchdog 正在做它該做的事：它每分鐘探測一次，把沒回應的 add-on 重啟。但當啟動本身每次都失敗時，這個保護機制就變成了一個無窮迴圈。

大約 90% 答案真正藏在的地方

打開 Settings → Add-ons → Woow HA Pi Agent ，選 Log 分頁；面板會自動捲到最新的紀錄。log 可能長達好幾千行，所以先讀剛失敗那件事前後的最後三十行，只有在錯誤指向更早的初始化步驟時，才需要往前翻。

Log 分頁請求紀錄，最新的在最下面，上方有個 Search logs 欄位，還有一個 Live 標記，代表這個畫面還在即時跟隨。

• 大多是請求紀錄。 每一行都帶著客戶端位址、時間戳記、請求內容跟狀態碼—— "GET /api/agent/running/events HTTP/1.1" 200 這裡就是這樣。警告也混在同一串裡，就像 epoll_wait() reported that client prematurely closed connection 這一行，往上幾行就有。bashio 的啟動訊息跟 pi-web 的輸出，都交錯在同一個畫面裡。
• 最新的在最下面。 從那裡開始看——最後 30 行通常就足夠寫一份第一次的回報。
• Search logs在面板上方，是你輸入關鍵字的地方；瀏覽器自己的 Ctrl+F 對畫面上已經顯示的內容也管用。注意那些很長的 hassio_ingress 網址帶著一個 session 識別碼——貼到任何公開的地方之前先遮掉。

值得搜尋的關鍵字，以及對上了通常代表什麼：

想看更詳細的資訊，把 log_level 從 info 成 debug 在 Configuration 分頁上改掉，存檔，Restart。重現一次問題 一次 ——比如那個會回傳 401 的請求——接著設回 info。debug 輸出一分鐘內可能長到幾千行；不要讓 /var/log 被塞爆。

如果還是需要幫忙

到這裡開一個 issue https://github.com/WOOWTECH/Woow_ha_pi_agent_add_on/issues，先搜尋一下既有的 issue——「401」、「video-tools」、「blank iframe」——可能已經有人回報過你遇到的症狀了。有四件事能讓一份回報變得有辦法回答：

• 你的 Pi Agent 版本 從 Info 分頁最上面看，例如 0.13.1。
• 你的 Home Assistant 版本 從 Settings → About 或系統資訊頁面。
• 最後 30 行相關的 log，用三個反引號包起來，這樣 GitHub 才會渲染成程式碼區塊。
• 你已經試過的每一件事 ——「重啟過了、換了金鑰、Test 顯示成功，但送訊息還是回傳 401。」

可以的話用英文寫。維護者看得懂中文，但用英文寫的回報，其他地方可能幫得上忙的人也讀得懂；如果用英文不方便，中文也可以。

接下來往哪走