打開工作區，先認清楚每個地方在哪，再開始打字
Home Assistant 側邊欄多了一個機器人圖示。這篇講這個圖示證明了什麼、為什麼家裡其他人看不到，以及圖示背後的工作區怎麼擺——這樣之後看到「打開 Models 面板」這種指示，你才知道要看畫面的哪裡。這篇還不設金鑰、還不傳訊息，先認位置。
側邊欄那一行，證明了什麼
Pi Agent 沒有桌面捷徑、沒有自己的網址，也沒有登入畫面。它只有 Home Assistant 側邊欄裡帶著機器人圖示的一行。這一行其實是三件事同時成立的證明：附加元件正在跑、它的 Ingress 面板已經註冊、而且你的帳號是管理員。三件事只要有一件不成立，這一行就不會出現。
把側邊欄往下捲過你原本就有的那些內建項目，找那個機器人圖示 mdi:robot。旁邊的文字來自附加元件自己的 config.yaml，裡面設定的是 panel_title: Pi Agent ——除非有人改過名字，不然就是找這個字樣。
-
步驟 1
用管理員帳號登入 Home Assistant
在電腦瀏覽器打開你平常用的 HA 網址——在家裡的區網通常是
http://homeassistant.local:8123或http://家裡IP:8123——用管理員帳號登入。 -
步驟 2
在側邊欄點 Pi Agent
工作區會在主畫面打開。第一次載入可能要 5-10 秒，因為請求要先經過 Ingress、到 nginx、再到 pi-web。之後再開會快一些。
-
步驟 3
記住「在新分頁開啟」的位置
它會用獨立分頁打開同一個工作區——適合把 Home Assistant 跟 Pi Agent 並排看。兩邊用的是 同一個 pi-web 執行個體 ，資料也是同一份。
-
步驟 4
手機或平板上用 Companion App
用管理員帳號登入官方的 Home Assistant Companion App，打開導覽選單，點 Pi Agent。功能一樣，只是小螢幕上有些控制項會收起來。
http://homeassistant.local:8123/hassio/ingress/woow_ha_pi_agent。Home Assistant 是那個櫃檯
想像一棟只有一個櫃檯的辦公大樓。附加元件在裡面有間辦公室，但沒有自己對外的大門。你在櫃檯出示證件，櫃檯再把你的訊息送到對的辦公室。這個櫃檯，就是 Home Assistant Ingress。
附加元件裡面，真正做事的程式是 pi-web，監聽的內部埠是 30141。它前面擋著 nginx，用的是附加元件宣告的 ingress 埠 30142。沒有 Ingress 的話，你得自己連到這個埠，網址大概長這樣 http://家裡IP:30142，這樣會多出四件麻煩事：在路由器上轉發 30142 這個埠、另外保護一組登入、出門在外要記得家裡的 IP，還要搞定手機的存取方式。
Ingress 把這四件事全部拿掉：你登入 Home Assistant，它自己做完驗證與管理員身分檢查後，把工作區嵌進畫面裡。
flowchart LR A["你的瀏覽器
網址還是 HA 那個"] --> B["Home Assistant
登入 session 與管理員檢查"] B --> C["Ingress proxy"] C --> D["附加元件裡的 nginx
埠 30142"] D --> E["pi-web
內部埠 30141"]
| 對照 | Ingress（Pi Agent 用的方式） | 直接開放的服務 |
|---|---|---|
| 路由器要改的地方 | Pi Agent 這邊不用改 | 通常要設定連接埠轉發 |
| 要不要另設密碼 | 不用；沿用 HA 帳號 | 通常需要，而且要另外保護 |
| 遠端存取 | 沿用你原本 HA 的遠端連線方式 | 得自己弄 VPN、Tunnel 或 DDNS |
不管你原本用什麼方式從外面連回 Home Assistant——Nabu Casa、Cloudflare Tunnel、VPN——Pi Agent 都直接沿用。不用多設定什麼，也不用多開一個對外的入口。
這一行故意藏起來，不讓其他人看到
附加元件宣告了 panel_admin: true，所以 Home Assistant 把這個面板註冊成「只有管理員能看」。一般使用者看到的不是變灰的項目——是根本沒有這一行。
這個面板背後藏著三樣東西，每一樣都是限制存取的理由：
- 你的 API 金鑰，這些金鑰可能授權了供應商那邊要付費的用量。
- 對話紀錄，裡面可能夾雜裝置 ID、位置，或其他偏私密的家庭細節。
- Skills，視權限與你的核准而定，Skill 可能真的會執行 shell 指令、改動 Home Assistant 的檔案與設定。
你可以讓家裡其他人也能用，官方支援的做法很直接： 設定 → 人員 → 使用者，選那個使用者，開啟管理員權限。他們重新登入一次，那一行就會出現。
但這等於因為對方想開一個抽屜，就把整串鑰匙都交出去。當上管理員的人拿到的不只是 Pi Agent——是所有附加元件、系統設定、開發者工具、備份，還有重新啟動的按鈕。
五個你該認得出來的區塊
圖示背後的工作區是 pi-web，它不是換了一層皮的 Home Assistant 儀表板。
把它想成瀏覽器分頁裡開的一個文字編輯器。分頁屬於 Home Assistant，但裡面跑的程式是它自己的東西，有自己的選單、自己的檔案。你的儀表板讀取與切換裝置的資料放在 /config/。而它把自己的資料放在 /data/pi-agent/ ，除非有工具被要求、也被允許動手，否則不會改動 Home Assistant 裡的任何東西。
在寬螢幕上，它會分成左欄、中間主區跟一條細細的頂部工具列；螢幕窄的話有些部分會收進選單裡。把游標一個個移過去看，現在還不用點。
- + New 在左欄最上面，下面接著工作目錄
~/pi-cwd-20260909。每個獨立任務開一個對話；這個路徑就是 agent 的檔案工具會落地的地方。 - 對話清單 在它下面——這裡有三筆之前的對話，各自標著相對時間與訊息數，例如 36 分鐘前 · 8 則訊息。全新安裝的話這裡是空的；這台機器不是全新的。
- EXPLORER 在清單下面，顯示那個工作目錄裡有什麼——這裡有一個檔案，
notes.md。這是看 agent 實際寫了什麼最快的方法。 - Models, Skills 、 Settings 這三顆按鈕橫排在 左欄最下面 （這個版本是這樣）。這些面板就是從這裡打開的。
- 訊息輸入框 在中間，寫著 Message… Type / for commands, @ for files，右端有一顆 Send 按鈕。它下面那一列寫著目前的模型名稱， GPT-5.6 Sol，接著是 auto, default 、 Compact。 System 、 Tools 則在最上面那條工具列。
訊息框下面那個模型名稱，是最值得盯著看的東西，因為它告訴你設定進度走到哪：
glm-4.6 ——代表這個模型會回答你下一則訊息。每個面板都是蓋在對話上面的一個抽屜
這裡講的「面板」是蓋在工作區上面的一個抽屜——不是 Home Assistant 側邊欄那種面板，也不是你要導覽過去的一個頁面。關掉它，你就回到原本的對話。上圖這個版本裡，Models、Skills、Settings 從左欄最下面的按鈕打開，System 跟 Tools 從頂部工具列打開。
| 面板 | 做什麼用 | 詳見 |
|---|---|---|
| Models | 新增供應商、輸入 API 金鑰、按 Test 測試、設定要用哪些模型 | 第 3 篇 |
| Skills | 從 GitHub 網址或 owner/repo | 第 9-10 篇 |
| Plugins | 擴充功能；日常使用大部分人都用不到 | — |
| System | 讀取這個 session 目前實際跑的 system prompt | 第 5 篇 |
有兩個現在就值得打開看看，純粹看看就好。先看工具清單——這是 agent 實際能碰到的範圍。
- read、bash、edit、write 列在左欄——這些就是動詞，也是「它到底碰得到什麼」最誠實的答案。值得先認識，因為對話裡的工具呼叫卡片，標的就是這幾個名字之一。
- 點選 read ，右欄就會填出： path 是必填，吃一個字串， offset 、 limit 是選填的數字。模型工作時看到的就是這種細節程度。
- 參數底下，面板會接著一段 Prompt guidelines ——這是模型自己讀到、關於怎麼用這個工具的文字說明。
第二個是 system prompt：agent 帶進每一則訊息的固定指令，包含已載入的 Skill 說明。
外觀跟舒適度設定跟上面那些是分開的。
- Light／Dark／System 是 pi-web 自己的主題設定，這裡設成 System 。Home Assistant 的主題是在你的 HA 個人檔案裡設的，不會跟著帶過來。
- 預設展開思考塊 在這個版本是關的，所以模型的思考過程會以收合狀態出現。先保持關閉，等第 5 篇解釋你看到的到底是什麼。
- Chat content width 設成 820px 、 Chat font size 設成 14px ，這兩個是讓長回答在寬螢幕上讀起來舒服的關鍵設定。
- 頂部那排分頁—— General、Models、Skills、Sub-agents、Plugins ——上面表格提到的那些面板，這裡就是從這幾個分頁進去。
剛好有 兩個 全域快捷鍵： Esc 會停掉正在跑的 agent，而 Ctrl+Alt+N 會在目前的工作目錄開一個新 session。沒有指令面板，也沒有 Cmd+K。在訊息框裡，Enter 送出，Shift+Enter 換行。
設定 → 附加元件 → Woow HA Pi Agent → Configuration 控制的是容器本身： log_level, timezone, reset_video_tools, env_vars。從 v0.13.0 起，供應商金鑰放在 pi-web 的 Models 面板，不是放在這裡。大家實際會卡住的地方
側邊欄沒有 Pi Agent 這一行
設定 → 人員 → 使用者，選你的帳號，看 Administrator 那個開關。第二， 設定 → 附加元件 → Woow HA Pi Agent → Info，看 Show in sidebar 有沒有開。第三，用 Ctrl+Shift+R，或是 Cmd+Shift+R 在 macOS 上，強制重新載入前端頁面。主畫面一片空白
F12 ，看 Network 跟 Console 分頁。如果好幾個 _next/… 或 /api/… 的回應都是 404 ，代表 Ingress 的路徑前綴沒套上；去看附加元件的 Log 分頁，然後重啟它。如果是 403，有時候還帶著 Untrusted API request，先重啟一次看看——如果官方步驟有要求，就跑 ha core restart，讓 Supervisor 重新註冊一次乾淨的面板 session。打字區按不下去，打不出字
對話清單不見了
電腦跟手機能同時用嗎？
接下來往哪走
你現在什麼都找得到了。接下來讓它開口回答。
第 3 篇會申請一支 OpenRouter 金鑰，貼進 Models 面板——就是這篇故意沒打開的那個面板。貼完，打字區就會醒過來。
打開完整教學手冊《Pi Agent 入住指南》系列第 2 篇，由 WoowTech 渥屋科技 製作。
內容出自 Woow HA Pi Agent 入住指南，依 CC BY 4.0 釋出。
The Smart Space Solution · 智慧空間解決方案 · © 2026 WOOW Technology Co., Ltd.