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：
|
|
Pi Web 默认读取：
|
|
如果 Pi 还没有产生任何会话，网页可以启动，但会话列表可能是空的。
不安装直接运行
最简单的方式是使用 npx：
|
|
服务启动后会尝试自动打开浏览器，默认地址是：
|
|
这种方式适合先体验，不需要把命令永久安装到全局 npm 目录。
全局安装
经常使用可以执行：
|
|
如果 PowerShell 提示找不到 pi-web，检查 npm 全局目录是否在 PATH：
|
|
修改 PATH 后要重新打开终端。
修改端口和监听地址
默认只在本机使用时，建议显式绑定回环地址：
|
|
修改端口：
|
|
组合使用：
|
|
作为后台服务、不希望自动打开浏览器：
|
|
不要为了从手机访问就直接绑定 0.0.0.0 并开放公网端口。Pi Web 能读取 Agent 会话、项目文件和模型配置，这些内容可能包含源代码、文件路径、提示词与工具输出。
配置 HTTP 代理
Pi Web 会读取标准代理环境变量。Windows PowerShell 示例：
|
|
这些变量只在当前 PowerShell 会话中生效。NO_PROXY 很重要，否则访问本机服务时也可能被送进代理。
找不到 Pi 会话怎么办
Pi Web 默认从 ~/.pi/agent/sessions 读取 JSONL 会话。如果你的 Pi 数据目录不在默认位置，可设置：
|
|
先检查目录是否真的存在：
|
|
会话按项目工作目录组织。如果同一个仓库曾从不同盘符、软链接或 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：
|
|
Pi Web 的侧边栏可以切换已识别的 Worktree，并让新会话与文件浏览器跟随对应目录。
完成后先确认分支内容已经提交，再移除：
|
|
不要在存在未提交修改时强制删除 Worktree。
常见问题
页面打开但没有历史记录
检查 PI_CODING_AGENT_DIR、默认 sessions 目录和当前 Windows 用户是否正确。以管理员身份运行一次、普通用户运行一次，也可能产生两套不同的用户目录。
端口被占用
换一个端口：
|
|
或查询占用进程：
|
|
模型请求失败
先在 Pi CLI 中确认同一模型能用，再检查 Pi Web 进程是否继承了代理变量和 API Key。网页能打开只说明本地服务正常，不代表模型供应商连接成功。
项目文件看不到
文件预览范围受所选项目目录和会话工作目录限制。确认会话确实从目标仓库启动，不要通过不一致的盘符映射或软链接进入项目。
Pi Web 安全远程访问
Pi Web 默认只监听 127.0.0.1，也没有自己的应用层登录认证。因为页面能够操作 Pi Coding Agent 会话，远程访问时应继续保持回环监听，通过 SSH 隧道进入；不要为了省一步操作直接暴露到公网。
首选方案：回环监听加 SSH 隧道
在服务器上启动 Pi Web，并明确指定回环地址：
|
|
先确认监听地址。结果应是 127.0.0.1:30141，而不是 0.0.0.0:30141：
|
|
然后在客户端建立本地端口转发：
|
|
保持 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 并不等于完成安全加固。
修改配置后先做语法检查：
|
|
还要实际验证未登录请求会被拒绝、WebSocket/长连接正常、认证失败时路由可以立即停用。不要把 Pi 会话目录、Cookie 或模型密钥写进代理日志。
代理环境变量应配置在服务进程中
如果模型请求需要经过 HTTP 代理，应在启动 Pi Web 的同一个终端中设置变量：
|
|
浏览器能打开页面但模型请求失败时，分别检查 Pi Web 服务端日志和代理日志。浏览器代理设置不会自动传给服务器上的 Node.js 进程。
隧道断开和页面假在线
浏览器标签页仍显示旧界面，不代表隧道还活着。用新的请求确认端口：
|
|
如果 SSH 已断开，重新建立隧道后再刷新页面。不要在排错时同时更换端口、代理和启动参数，否则很难判断是哪一层恢复了连接。
多用户服务器上的会话隔离
Pi 会话通常位于当前用户的 ~/.pi 目录。共享服务器应让每位用户使用独立系统账号运行 Pi Web，并检查目录权限：
|
|
不要让公共服务账号读取所有人的 Pi 会话，也不要把整个会话目录直接同步到团队共享盘。备份前应确认其中是否含项目路径、对话内容、令牌或其他敏感信息。
关闭服务与验收
结束远程访问后，关闭 Pi Web 和 SSH 隧道，再确认端口已经消失：
|
|
最终验收应满足：服务只监听回环地址；远端只能经 SSH 或受认证代理访问；未认证请求被拒绝；隧道断开后客户端不可继续发起新操作；日志不包含密钥；升级 Pi Web 后重新检查监听参数和认证边界。
安全建议
Pi Web 会接触模型配置、Agent 会话和项目文件。建议：
- 默认绑定
127.0.0.1； - 不把端口直接映射到公网；
- 不在截图中暴露 API Key、提示词和私有源码；
- 定期备份 Pi 会话目录；
- 切换或删除 Worktree 前检查未提交修改；
- 在公司项目中先确认代码和模型数据使用政策。
Pi Web 更适合已有 Pi 用户改善会话管理。若你只是寻找一个能写代码的 Agent，应先把 Pi CLI 的模型、权限和基本工作流跑通，再安装网页界面。