Pi Web 安装教程一条命令把 pi 编程智能体搬进浏览器端口、远程访问与安全配置一次讲清【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-webPi 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-weblatest服务就绪后命令行会自动打开浏览器。没弹出来的话手动访问http://127.0.0.1:30141即可。需要注意的是Pi Web默认只监听127.0.0.1回环地址也就是说它只对本机开放不会暴露到局域网——这是刻意设计的安全默认值。第一次使用还没配置模型打开Models面板登录 Provider 或填入 API Key 就能开始对话。全局安装、更新与卸载如果希望常用可以装一个pi-web命令npm install -g agegr/pi-weblatest 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] # 更新全局安装到最新版更新前先用CtrlC或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端口必须是 065535 的整数传了非法值会直接报错退出退出码 1。--help打印帮助后以退出码 0 结束、不启动服务传入未知参数同样报错退出。参数 / 环境变量干什么用默认值--help、-h打印启动选项后直接退出—--port 端口、-p 端口或PORT服务端口0表示交给系统自动分配30141--hostname 主机、-H 主机或PI_WEB_HOSTNAME监听的主机名127.0.0.1--no-open或PI_WEB_NO_OPEN1不自动打开浏览器自动打开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表示禁用60000010 分钟PI_WEB_APP_NAMEPWA 清单里的应用名首尾空白会被裁剪Pi WebPI_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 / LinuxHTTP_PROXYhttp://127.0.0.1:7890 \ HTTPS_PROXYhttp://127.0.0.1:7890 \ NO_PROXYlocalhost,127.0.0.1 \ npx agegr/pi-weblatestWindows 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-weblatest安全边界从本地到远程认证与请求校验是怎么做的一句话导读默认监听回环地址是天然安全一旦你把-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 realmPi Web头提示客户端改用 Basic Auth。密码校验的细节在 lib/web-auth.tsBasic 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_HOSTNAMEPI_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/ 客户端状态与交互 hooksSSE 订阅、拖拽、快捷键…… 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]/eventsSSE 接口把会话事件流式推给页面会话文件本身是 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-webNode22.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），仅供参考