設定參數速查

什麼時候會來翻這頁

平常你根本不需要打開 Pi Agent 的 Add-on 設定分頁。裝好之後（第 2 章）、金鑰貼進去（第 6 章），就直接從側邊欄用起來，一年不用碰 Configuration。

但下面這幾個情境會逼你打開它：

• Log 找 bug：想看更詳細的訊息、把 log_level 調到 debug。
• 時區跑掉：發現 Logs 的時間比實際早 8 小時、想把 timezone 設成 Asia/Taipei。
• 影片管線壞了：Chromium 或 venv 環境爛掉，要重灌 video-tools（第 18 章會解釋為什麼）。
• 環境變數逃生口：家裡走公司 proxy、或想改 Chromium 下載鏡像，得塞 env_vars。

四個開關對應這四種情境，一個 section 講一個，格式一致：作用 / 預設 / 合法值 / 什麼時候動 / 踩雷 / 範例。

最重要的觀念：所有 API 金鑰都不在這裡

這是升級到 v0.13.0 之後最容易踩的坑。Add-on 的 Configuration 分頁沒有任何 API key 欄位——所有 provider（GLM、OpenAI、Anthropic、DeepSeek、Groq、MiniMax、OpenRouter）的金鑰全部搬到 pi-web 內建的 Models 面板裡管理（第 6 章教過），詳細版本變更記在第 21 章。

這附錄講的四個選項是「Add-on 容器層」的設定——影響的是整個 add-on 怎麼跑、log 長怎樣、時區怎麼算、影片工具要不要重灌，跟「哪家 AI、用哪把 key」完全兩碼事。

選項 1：log_level——訊息詳細度

什麼時候該調

• 日常：保持 info，該有的訊息都在，也不會太吵。
• 找 bug：調 debug——每一次 HTTP 請求、每一個 skill 掃描、每一個 provider 呼叫都會印出來。抓完 bug 記得調回去。
• 只想看警告：warn——只印 warning 以上，適合系統跑穩之後日常巡檢。
• 極簡：error——真的只留錯誤。不建議長期用，因為 warning 常常是「快壞掉了」的預兆。

範例

log_level: debug

用途：專門開來找「為什麼影片管線失敗」，可以看到 Playwright 啟動每一步、ffmpeg 每一個參數。找完之後改回：

log_level: info

選項 2：timezone——時區

為什麼台灣使用者一定要設

不設的話 Logs 分頁時間會是 UTC，比台灣時間早 8 小時。你晚上 8 點按了個操作、去 Logs 找對應紀錄，會看到「中午 12 點發生」——很容易以為 log 掉了。設成 Asia/Taipei 就跟你腦袋裡的時間對得起來。

Session 檔案的日期也會受影響——不設時區的話，深夜 11 點開的 session 檔名日期可能已經跳到「隔天」（因為 UTC 已經過午夜），對照起來很混亂。

常用 IANA 字串速查

範例

timezone: Asia/Taipei

選項 3：reset_video_tools——重灌影片工具

什麼時候該開

• 影片管線一直失敗、但看 log 看不出根本原因（第 18 章教過 video-tools 是什麼）。
• Chromium 版本太舊，某些網站截圖失敗（例如需要新版才能跑的網站）。
• venv 裡的 Python 套件跟 add-on 主程式對不起來（升級後偶爾會發生）。
• 一年一次的「大掃除」——就算沒事，趁著低峰時段跑一次順便升級 Chromium 也 OK。

範例（一次性使用）

reset_video_tools: true

儲存 → 等 Supervisor 自動重啟 → Logs 出現 video-tools-init 開始下載 → 完成後 Configuration 分頁重新載入，會看到這個值已經自己變回 false。之後不用管它。

選項 4：env_vars——環境變數逃生口

常見用途

範例

走公司 proxy：

env_vars:
  - name: HTTP_PROXY
    value: http://192.168.1.1:8080
  - name: HTTPS_PROXY
    value: http://192.168.1.1:8080
  - name: NO_PROXY
    value: 127.0.0.1,localhost,homeassistant.local

不需要就留空 list：

env_vars: []

完整設定範例

台灣一般家庭用戶最典型的設定長這樣，直接複製貼上就能用：

log_level: info
timezone: Asia/Taipei
reset_video_tools: false
env_vars: []

如果你在追蹤某個 bug、想開詳細 log 又要走公司 proxy：

log_level: debug
timezone: Asia/Taipei
reset_video_tools: false
env_vars:
  - name: HTTP_PROXY
    value: http://192.168.1.1:8080
  - name: HTTPS_PROXY
    value: http://192.168.1.1:8080

v0.13.0 之前的舊選項在哪裡（歷史參考）

從舊版升上來的老用戶會發現：Configuration 分頁少了一堆欄位。這不是壞掉——是搬家了。詳細的升級注意事項在第 21 章，這裡放對照表方便速查：

常見卡關

1. 改了設定完全沒反應

   Configuration 分頁改完之後要按最下方的「儲存」按鈕。有些 HA 版本按鈕會被浮動元件擋住，往下捲一點就會看到。儲存後 add-on 才會重啟套用；沒按等於白改。

2. Add-on 重啟後選項變回預設值

   通常是 YAML 格式錯——例如 timezone 少了引號、env_vars 的縮排不對。打開 Logs 分頁，往上滾找 parse error 或 invalid config 這類字串，會有一行指出是哪個欄位壞了。改完再儲存。

3. env_vars 加了但 pi-web 完全沒讀到

   三種可能：（1）名稱有非法字元（含連字號、開頭是數字、有中文）；（2）你設的環境變數不是 pi-web 會讀的——不是每個 OPENAI_* 或 ANTHROPIC_* 都有效，pi-web 只讀特定幾個（proxy 系列、Playwright 系列、少數 SDK 的 baseUrl）；（3）你想設的是 API 金鑰——那個永遠不會生效，回 Models 面板貼。

4. reset_video_tools 開了但 video-tools 沒重下載

   正常流程是勾 true → 儲存 → Supervisor 自動重啟 → video-tools-init 檢查旗標 → 開始下載。如果儲存後沒動靜，先確認：（1）Configuration 分頁真的按到了「儲存」按鈕（有時被浮動元件擋住，往下捲）；（2）打開 Logs 分頁看 video-tools-init 那幾行——如果只看到「exit <100ms」代表旗標沒被讀到；（3）真的都沒觸發時再從 add-on 頁面手動按「重新啟動」補一次。下載成功後回 Configuration 分頁重新載入，這個選項會自己翻回 false。

5. timezone 設了 Taipei 但時間還是 UTC

   IANA 格式一定要寫完整——Asia/Taipei，不是 Taipei、不是 CST、不是 +08:00。寫錯了系統會 fallback 回 UTC 而且不報錯，很容易誤判「已經設了」。改成正確字串、儲存、等 add-on 重啟完，再回 Logs 看時間戳是否對上。

6. debug log 太多，硬碟空間吃緊

   把 log_level 調回 info 或 warn。HA OS 通常會自動輪替 log 檔，但如果你在 Supervised／Container 安裝上手動看 /var/log，需要自己清一下舊檔。不要長期開 debug，只在排錯時開。

常見問題