Pi Web 安装教程：一条命令把 pi 编程智能体搬进浏览器，端口、远程访问与安全配置一次讲清
【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-web
Pi Web 是 pi 编程智能体（pi coding agent）的本地浏览器界面：它与终端里的 pi 共用同一份配置和会话数据，让你在浏览器中继续历史对话、运行智能体任务、管理模型与 Provider，并直接浏览项目文件。
为什么需要 Pi Web：终端之外的第二个工作台
一句话导读：Pi Web 解决的不是"能不能用"，而是"换个姿势用"——它把你已有的 pi 会话、配置和文件，原封不动地搬到了浏览器里。
如果你已经在终端里用 pi 干活，会遇到几件小事：翻历史会话要敲命令，想顺手改个模型配置得退出去，盯着长任务输出不如分屏看个图形界面来得轻松。Pi Web 就是为此存在的——它不是独立产品，而是 pi 的"浏览器外壳"：
- 同一份数据：会话文件（JSONL 格式）落在
~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl，终端里产生的会话在浏览器里直接可查、可继续；反过来，你在 Pi Web 里改的模型配置，pi 终端侧同样生效。 - 两种分支方式并存："新会话"（New session）是从较早消息复制出一个独立的新
.jsonl文件，走的是 SDK 的 fork 逻辑；"从此处编辑"（Edit from here）则是在当前会话文件内新建分支，多个条目共享同一个parentId（即调用navigate_tree）。二者在 hooks/useAgentSession.ts 中有明确区分，日常使用时别混用。 - 配套齐全：按项目分组管理会话（重命名、导出、删除、查看上下文占用与花费）、Git worktree 切换与归组展示、文件浏览与预览（源码、Markdown、图片、音频、PDF、DOCX）、Provider 登录与 API Key 管理、模型测试、插件与技能管理。
- 多语言界面：内置英文、简体中文、繁体中文，首次打开跟随浏览器语言，顶部栏可随时切换（机制见 docs/i18n.md）。
最快上线：环境确认 + 一条命令启动
一句话导读：先确认 Node 版本，然后一条npx命令就能把服务跑起来。
Pi Web 要求Node.js 22.19.0 或更高版本（package.json 的engines字段硬性约束）。入口脚本 bin/pi-web.js 在启动前会先做版本检查，不满足直接报错退出，所以这一步不用你操心，但自己确认一下能避免误会：
node --version版本没问题，直接运行：
npx @agegr/pi-web@latest服务就绪后，命令行会自动打开浏览器。没弹出来的话，手动访问http://127.0.0.1:30141即可。需要注意的是：Pi Web默认只监听127.0.0.1（回环地址），也就是说它只对本机开放，不会暴露到局域网——这是刻意设计的安全默认值。
第一次使用还没配置模型？打开Models面板，登录 Provider 或填入 API Key 就能开始对话。
全局安装、更新与卸载
如果希望常用，可以装一个pi-web命令：
npm install -g @agegr/pi-web@latest pi-web装好之后，pi-web还带几个运维子命令：
pi-web version # 查看已安装版本 pi-web status # 列出正在运行的 Pi Web 服务 pi-web stop [--port N] # 停止指定端口的服务 pi-web open [--port N] # 在浏览器中打开运行中的服务 pi-web update [--check] # 更新全局安装到最新版更新前先用Ctrl+C（或pi-web stop）停掉正在运行的进程，再执行同一条安装命令或pi-web update即可；卸载运行npm uninstall -g @agegr/pi-web。
从源码跑开发服务器
想改代码或者只是想看它怎么跑，用开发模式：
npm install npm run dev开发服务器同样监听 http://127.0.0.1:30141（见 package.json 的dev脚本：next dev -H 127.0.0.1 -p 30141）。日常检查三件套：
npm test # 跑 app/components/hooks/lib/public 下的全部测试 node_modules/.bin/tsc --noEmit # TypeScript 类型检查 npm run lint # ESLint 检查调参全景：端口、主机与代理
一句话导读：启动行为由"命令行参数优先、环境变量兜底"的规则决定，记住优先级就不会踩坑。
参数解析集中在 bin/pi-web-options.js：命令行参数优先于对应环境变量；布尔型环境变量额外接受true、yes、on等取值（源码里的TRUE_VALUES）；端口必须是 0～65535 的整数，传了非法值会直接报错退出（退出码 1）。--help打印帮助后以退出码 0 结束、不启动服务；传入未知参数同样报错退出。
| 参数 / 环境变量 | 干什么用 | 默认值 |
|---|---|---|
--help、-h | 打印启动选项后直接退出 | — |
--port <端口>、-p <端口>或PORT | 服务端口（0表示交给系统自动分配） | 30141 |
--hostname <主机>、-H <主机>或PI_WEB_HOSTNAME | 监听的主机名 | 127.0.0.1 |
--no-open或PI_WEB_NO_OPEN=1 | 不自动打开浏览器 | 自动打开 |
PI_WEB_ALLOWED_HOSTS | 额外允许的代理/自定义主机名，逗号分隔，精确匹配 | 未设置 |
PI_WEB_PASSWORD | 启用浏览器密码登录；API 客户端可用用户名为pi的 Basic Auth | 不启用认证 |
PI_WEB_SKIP_VERSION_CHECK | 设为1关闭 Pi Web 更新检查 | 未设置 |
PI_WEB_IDLE_TIMEOUT_MS | 会话空闲超时毫秒数，0表示禁用 | 600000（10 分钟） |
PI_WEB_APP_NAME | PWA 清单里的应用名（首尾空白会被裁剪） | Pi Web |
PI_WEB_SHUTDOWN_DEADLINE_MS | 关闭会话时等待扩展处理session_shutdown的毫秒上限 | 5000 |
两个常用例子：
pi-web --help pi-web -p 8080 -H 0.0.0.0 --no-open其中PI_WEB_IDLE_TIMEOUT_MS的 10 分钟默认值，和 AGENTS.md 里描述的"AgentSession 空闲 10 分钟自动回收"是同一件事：浏览器关掉或消息发完放着不管，跑着的智能体会在空闲超时后被自动销毁。
让服务端的模型请求走代理
模型调用和 API 请求发生在 Node 服务端，它们读取标准的HTTP_PROXY、HTTPS_PROXY、NO_PROXY环境变量。macOS / Linux：
HTTP_PROXY=http://127.0.0.1:7890 \ HTTPS_PROXY=http://127.0.0.1:7890 \ NO_PROXY=localhost,127.0.0.1 \ npx @agegr/pi-web@latestWindows PowerShell：
$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安全边界：从本地到远程，认证与请求校验是怎么做的
一句话导读：默认监听回环地址是"天然安全"，一旦你把-H 0.0.0.0敲出来，就得把密码、加密、主机白名单这三件事都补齐。
监听非回环地址等于把一个能执行高权限操作的智能体暴露出去。在可信局域网里使用时，至少给它配一个足够长的随机密码：
PI_WEB_PASSWORD='足够长的随机密码' pi-web --hostname 0.0.0.0bin/pi-web.js 启动时会判断监听地址：不在回环名单（127.0.0.1、localhost、::1）里且没设密码，会打印 "listening ... without authentication" 警告；设了密码也照样提醒——密码认证不加密连接，HTTP 明文传输下密码是裸奔的。所以：
- 不要把 Pi Web 用明文 HTTP 直接暴露到互联网；
- 远程访问走可信反向代理 + HTTPS，或可信 VPN；
- 反向代理如果传递外部主机名，把它精确加进
PI_WEB_ALLOWED_HOSTS（逗号分隔，精确匹配），这个白名单不改变 Pi Web 的监听地址。
认证流程：浏览器和 API 各走各的门
启用PI_WEB_PASSWORD后，认证由 proxy.ts 这个 Next.js 中间件统一接管，匹配路径为/、/login、/api/:path*：
- 浏览器：未认证访问页面 → 302 重定向到
/login登录页（原地址通过next查询参数带回）；登录成功后签发pi_web_sessionCookie，后续请求凭 Cookie 通过。 - API 客户端：未认证请求返回
401，并携带WWW-Authenticate: Basic realm="Pi Web"头，提示客户端改用 Basic Auth。
密码校验的细节在 lib/web-auth.ts：
- Basic Auth 的用户名固定为
pi（源码里的PI_WEB_AUTH_USERNAME常量），密码就是PI_WEB_PASSWORD的值； - 比较前先对两侧做 SHA-256 摘要，再用
timingSafeEqual对比，避免时序侧信道； - 会话 Cookie 是 HMAC-SHA256 签名的令牌，默认有效期30 天；
- 连登录表单也带限流：短时间内多次失败会收到
429加Retry-After头，期间即使密码正确也会被拒绝（见 lib/auth-throttle.ts 与 proxy.ts 的联动）。
请求校验：不只查密码，还查"你是谁、从哪来"
lib/request-security.ts 在认证之前先做两层过滤：
- Host 白名单（
isApiRequestHostAllowed）：只信任本地名称（localhost及*.localhost）、IP 字面量，或操作者显式配置的主机名（PI_WEB_HOSTNAME+PI_WEB_ALLOWED_HOSTS）。保留 IP 字面量访问既保住了局域网可用性，又因为浏览器在 Host 头中保留字面地址而天然防 DNS rebinding。 - CSRF 防护（
isApiRequestOriginAllowed）：跨站（cross-site）发起的浏览器 API 请求直接拒绝，只放行非浏览器客户端与同源请求，并兼容反向代理改写Origin的场景（比如隧道服务把Origin改写成后端地址）。
换句话说，即使有人通过跨站脚本或伪造 Host 试图调你的接口，这两道关卡都会先把它挡在认证逻辑之前。
底层拆解：读懂 Pi Web 如何工作
一句话导读：整体是一个 Next.js 应用，浏览会话走只读接口，发消息才会在进程内拉起一个真正的 AgentSession。
先看目录地图：
app/ Next.js 界面与 API 路由（浏览器请求的入口） components/ React 界面组件（会话树、聊天窗口、设置面板……） hooks/ 客户端状态与交互 hooks（SSE 订阅、拖拽、快捷键……） lib/ 会话、智能体、模型、文件、Git 与安全逻辑（服务端核心） public/ 静态资源与 PWA 文件 bin/ npm CLI 入口与启动参数解析 docs/ 面向用户与贡献者的专题文档关键数据流只有三条，理解它们就理解了大半实现（与 AGENTS.md 的 Architecture 一节一致）：
| 动作 | 路由 | 背后逻辑 |
|---|---|---|
| 浏览会话 | GET /api/sessions、GET /api/sessions/[id] | 纯只读，直接把.jsonl当数据源解析，不创建AgentSession，核心是 lib/session-reader.ts |
| 发送消息 | POST /api/agent/[id] | 经 lib/rpc-manager.ts 的startRpcSession()在进程内创建 AgentSession 再投递命令；浏览器侧由 lib/agent-client.ts 提供类型化 fetch 封装 |
| 接收流式输出 | GET /api/agent/[id]/events | SSE 接口，把会话事件流式推给页面 |
会话文件本身是 JSONL，一行一条记录，类型包括session、model_change、message、toolResult、compaction、session_info等，完整示例见 AGENTS.md 的 "Pi Session File Format" 一节。
还有三处值得单独看一眼的实现：
- 文件访问边界：文件浏览器不是通用文件管理器。lib/file-access.ts 会把会话 cwd、解析出的项目根（worktree 共享的主仓库根）、
~/pi-cwd-*目录和显式添加的根收集成允许根集合（带 5 秒短缓存），所有路径判断统一收敛到 lib/path-security.ts 的isPathWithinRoots()，并区分"词法判断"与"解析符号链接后的实存判断"。 - Worktree 支持：lib/worktree.ts 把 linked worktree 解析回主仓库根，让同一仓库不同 worktree 的会话在侧边栏归组展示；worktree 的增删由
/api/worktrees提供，且遵循与/api/files相同的允许根规则。 - 配置读写：
/api/models-config路由直接读写~/.pi/agent/models.json，这也是"网页上改模型、终端里立刻生效"的原因。
架构细节和文件级地图（lib/ 里每个模块干什么）都写在 AGENTS.md 里，改代码之前先读它是团队约定。
实战边界：上手后的细节与避坑
一句话导读：装好只是开始，数据目录、文件系统环境和开发调试习惯里有几个容易踩的坑。
- 智能体数据目录：默认读
~/.pi/agent。想指向别的目录，设置PI_CODING_AGENT_DIR环境变量即可（bin/run-records.js 里的解析逻辑与 pi 的getAgentDir()一致，支持~展开）。 - 文件系统环境必须一致：Pi Web 要能读到智能体数据目录、以及会话记录里的工作目录。如果你打算共享已有 pi 会话，就让 Pi Web 和 pi 跑在同一文件系统环境里——别在一台机器上跑 Pi Web 去读另一台机器的本地路径，也别在容器里挂不存在的主机路径。
- 文件浏览是允许列表制：它只认"你在 Pi Web 里选过的工作目录"和"它已识别的项目/会话根"。想要某个目录可浏览，先让会话在那里跑起来，或者通过显式添加根的方式放行。
- Git worktree：切换器何时出现、怎么创建、删除有什么影响，细节见 docs/worktrees.zh-CN.md。
- 开发时别碰
next build：日常开发不要运行next build或npm run build，它们会写坏.next/、干扰开发服务器，构建只属于发布流程（docs/release.md）。如果开发服务器出问题，先用lsof -nP -iTCP:30141 -sTCP:LISTEN找到健康进程复用；两个next dev同时跑会争用.next/dev/lock，换端口也救不了（AGENTS.md 有专门排障清单）。
项目信息与许可证
Pi Web 采用 MIT 许可证，当前版本信息（@agegr/pi-web，Node>=22.0.19）见 package.json；界面效果参考本文开头的会话截图。想深入了解国际化机制读 docs/i18n.md，想参与发布流程读 docs/release.md；需要源码可以从仓库克隆：
git clone https://gitcode.com/GitHub_Trending/pi/pi-web从npx一行命令到远程访问加固，Pi Web 的价值在于把 pi 的全部本地能力装进浏览器，同时用回环默认值、Host 白名单、CSRF 过滤和 Basic Auth 把安全边界守得很清楚。按上面的步骤把环境、参数、认证三块配好，你就可以安心在浏览器里跑智能体了。
【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-web
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
