Pi Web Windows 安裝教程：瀏覽器管理 Pi Coding Agent 會話、模型與 Worktree

Pi Web 是 Pi Coding Agent 的本地網頁介面。它不會把 Pi 改造成另一個雲端 Agent，而是讀取本機已有的 Pi 會話檔案，在瀏覽器裡展示對話、工具呼叫、上下文用量、模型設定、Skills 和專案檔案。

專案地址：

適合它的場景很明確：你已經在用 Pi，但不想一直在終端裡翻歷史會話，或者希望一邊看專案檔案，一邊繼續同一個 Agent 任務。

安裝前確認

Windows 上先準備：

Node.js 與 npm；
已能正常使用的 Pi Coding Agent；
PowerShell 或 Windows Terminal；
一個由 Git 管理的專案目錄。

檢查 Node.js：

1
2


node --version
npm --version

Pi Web 預設讀取：

1

~/.pi/agent/sessions

如果 Pi 還沒有產生任何會話，網頁可以啟動，但會話列表可能是空的。

不安裝直接執行

最簡單的方式是使用 npx：

1

npx @agegr/pi-web@latest

服務啟動後會嘗試自動開啟瀏覽器，預設地址是：

1

http://localhost:30141

這種方式適合先體驗，不需要把命令永久安裝到全域性 npm 目錄。

全域性安裝

經常使用可以執行：

1
2


npm install -g @agegr/pi-web
pi-web

如果 PowerShell 提示找不到 pi-web，檢查 npm 全域性目錄是否在 PATH：

1
2


npm config get prefix
Get-Command pi-web -ErrorAction SilentlyContinue

修改 PATH 後要重新開啟終端。

修改埠和監聽地址

預設只在本機使用時，建議顯式繫結迴環地址：

1

pi-web --hostname 127.0.0.1

修改埠：

1

pi-web --port 8080

組合使用：

1

pi-web -p 8080 -H 127.0.0.1

作為後臺服務、不希望自動開啟瀏覽器：

1

pi-web --no-open

不要為了從手機訪問就直接繫結 0.0.0.0 並開放公網埠。Pi Web 能讀取 Agent 會話、專案檔案和模型配置，這些內容可能包含原始碼、檔案路徑、提示詞與工具輸出。

配置 HTTP 代理

Pi Web 會讀取標準代理環境變數。Windows PowerShell 示例：

1
2
3
4


$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @agegr/pi-web@latest

這些變數只在當前 PowerShell 會話中生效。NO_PROXY 很重要，否則訪問本機服務時也可能被送進代理。

找不到 Pi 會話怎麼辦

Pi Web 預設從 ~/.pi/agent/sessions 讀取 JSONL 會話。如果你的 Pi 資料目錄不在預設位置，可設定：

1
2


$env:PI_CODING_AGENT_DIR = "D:\pi-data"
pi-web

先檢查目錄是否真的存在：

1
2


Test-Path "$HOME\.pi\agent\sessions"
Get-ChildItem "$HOME\.pi\agent\sessions" -Directory

會話按專案工作目錄組織。如果同一個倉庫曾從不同磁碟機代號、軟連結或 WSL 路徑開啟，可能被識別成不同專案。

網頁裡能管理什麼

Pi Web 主要提供這些功能：

按專案瀏覽過去的 Pi 會話；
繼續、分叉或從舊訊息建立新分支；
檢視 Markdown、工具呼叫和上下文壓縮狀態；
檢視專案原始碼、文件、圖片、音訊和 PDF；
管理模型、登入資訊、API Key 和模型測試；
開啟或關閉 Skills；
在 Git Worktree 之間切換。

它讀寫的是本地 Pi 配置和會話，不是單獨複製一份雲端狀態。修改模型配置或會話分支前，最好先備份 .pi 目錄。

Fork 和會話內分支有什麼區別

Pi Web 中的 Fork 會建立新的 JSONL 會話檔案，適合從某個節點嘗試另一條實現路線，同時保留原會話。

“Edit from here”則是在同一個會話檔案內建立分支。它更輕量，但整理和遷移時不如獨立檔案直觀。

如果要比較兩種實現或交給不同 Worktree，優先 Fork；只是糾正一條提示詞或回到上一步，可使用會話內分支。

配合 Git Worktree

Worktree 適合讓不同 Agent 會話在獨立工作目錄處理不同分支，避免同時修改同一份檔案。

先在主倉庫建立 Worktree：

1
2


git worktree add ..\my-project-feature -b feature/pi-test
git worktree list

Pi Web 的側邊欄可以切換已識別的 Worktree，並讓新會話與檔案瀏覽器跟隨對應目錄。

完成後先確認分支內容已經提交，再移除：

1
2


git worktree remove ..\my-project-feature
git branch -d feature/pi-test

不要在存在未提交修改時強制刪除 Worktree。

常見問題

頁面開啟但沒有歷史記錄

檢查 PI_CODING_AGENT_DIR、預設 sessions 目錄和當前 Windows 使用者是否正確。以管理員身份執行一次、普通使用者執行一次，也可能產生兩套不同的使用者目錄。

埠被佔用

換一個埠：

1

pi-web --port 30142

或查詢佔用程序：

1

Get-NetTCPConnection -LocalPort 30141 -ErrorAction SilentlyContinue

模型請求失敗

先在 Pi CLI 中確認同一模型能用，再檢查 Pi Web 程序是否繼承了代理變數和 API Key。網頁能開啟只說明本地服務正常，不代表模型供應商連線成功。

專案檔案看不到

檔案預覽範圍受所選專案目錄和會話工作目錄限制。確認會話確實從目標倉庫啟動，不要透過不一致的磁碟機代號對映或軟連結進入專案。

Pi Web 安全遠端存取

Pi Web 預設只監聽 127.0.0.1，也沒有自己的應用層登入認證。因為頁面能夠操作 Pi Coding Agent 工作階段，遠端存取時應繼續保持回環監聽，透過 SSH 隧道進入；不要為了省一步操作直接暴露到公網。

首選方案：回環監聽加 SSH 隧道

在伺服器上啟動 Pi Web，並明確指定回環位址：

1

npx @agegr/pi-web@latest --hostname 127.0.0.1 --port 30141 --no-open

先確認監聽位址。結果應是 127.0.0.1:30141，而不是 0.0.0.0:30141：

1

Get-NetTCPConnection -LocalPort 30141 -ErrorAction SilentlyContinue

然後在客戶端建立本機連接埠轉送：

1

ssh -L 30141:127.0.0.1:30141 user@server

保持 SSH 工作階段開啟，在客戶端存取 http://127.0.0.1:30141。這樣 Pi Web 的連接埠仍只存在於伺服器回環介面，SSH 負責身分認證和傳輸加密。

為什麼不應直接綁定到 0.0.0.0

0.0.0.0 會讓服務監聽所有網路介面。即使伺服器暫時位於內網，雲端安全群組、路由、VPN 或連接埠轉送的變化也可能讓它意外暴露。Pi Web 沒有內建登入層，一旦頁面可達，存取者就可能看到工作階段、專案目錄和 Agent 能呼叫的操作入口。

如果測試時曾使用公網監聽，結束後立即恢復 127.0.0.1，重新檢查監聽位址，並確認防火牆或雲端安全群組沒有遺留放行規則。

必須使用反向代理時的保護

只有需要多人長期存取時才考慮反向代理。代理入口至少應同時具備 TLS、獨立認證、存取日誌和來源限制；只設定 reverse_proxy 127.0.0.1:30141 並不等於完成安全加固。

修改設定後先做語法檢查：

1

caddy validate --config Caddyfile

還要實際驗證未登入請求會被拒絕、WebSocket／長連線正常、認證失敗時路由可以立即停用。不要把 Pi 工作階段目錄、Cookie 或模型金鑰寫進代理日誌。

代理環境變數應設定在服務程序中

如果模型請求需要經過 HTTP 代理，應在啟動 Pi Web 的同一個終端中設定變數：

1
2
3
4


$env:HTTP_PROXY='http://127.0.0.1:7890'
$env:HTTPS_PROXY=$env:HTTP_PROXY
$env:NO_PROXY='localhost,127.0.0.1'
npx @agegr/pi-web@latest --hostname 127.0.0.1 --port 30141 --no-open

瀏覽器能開啟頁面但模型請求失敗時，分別檢查 Pi Web 服務端日誌和代理日誌。瀏覽器代理設定不會自動傳給伺服器上的 Node.js 程序。

隧道斷開和頁面假在線

瀏覽器分頁仍顯示舊介面，不代表隧道還活著。用新的請求確認連接埠：

1
2


Test-NetConnection 127.0.0.1 -Port 30141
curl.exe -I http://127.0.0.1:30141

如果 SSH 已斷開，重新建立隧道後再重新整理頁面。不要在除錯時同時更換連接埠、代理和啟動參數，否則很難判斷是哪一層恢復了連線。

多使用者伺服器上的工作階段隔離

Pi 工作階段通常位於目前使用者的 ~/.pi 目錄。共享伺服器應讓每位使用者使用獨立系統帳號執行 Pi Web，並檢查目錄權限：

1

Get-ChildItem -Force $env:USERPROFILE\.pi -ErrorAction SilentlyContinue

不要讓公共服務帳號讀取所有人的 Pi 工作階段，也不要把整個工作階段目錄直接同步到團隊共享磁碟。備份前應確認其中是否含專案路徑、對話內容、權杖或其他敏感資訊。

關閉服務與驗收

結束遠端存取後，關閉 Pi Web 和 SSH 隧道，再確認連接埠已經消失：

1

Get-NetTCPConnection -LocalPort 30141 -ErrorAction SilentlyContinue

最終驗收應滿足：服務只監聽回環位址；遠端只能經 SSH 或受認證代理存取；未認證請求被拒絕；隧道斷開後客戶端不可繼續發起新操作；日誌不包含金鑰；升級 Pi Web 後重新檢查監聽參數和認證邊界。

安全建議

Pi Web 會接觸模型配置、Agent 會話和專案檔案。建議：

預設繫結 127.0.0.1；
不把埠直接對映到公網；
不在截圖中暴露 API Key、提示詞和私有原始碼；
定期備份 Pi 會話目錄；
切換或刪除 Worktree 前檢查未提交修改；
在公司專案中先確認程式碼和模型資料使用政策。

Pi Web 更適合已有 Pi 使用者改善會話管理。若你只是尋找一個能寫程式碼的 Agent，應先把 Pi CLI 的模型、許可權和基本工作流跑通，再安裝網頁介面。