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

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

專案地址：

https://github.com/agegr/pi-web

適合它的場景很明確：你已經在用 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 會接觸模型配置、Agent 會話和專案檔案。建議：

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

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