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 的模型、权限和基本工作流跑通，再安装网页界面。