1. 为什么要把 Pi Coding Agent 搬进浏览器如果你已经在本地用 Pi Coding Agent 写过代码大概率遇到过这种场景终端里跑了一堆会话想回头找上周那次重构的记录得在~/.pi/agent/sessions里翻.jsonl文件想对比两个方案的对话分支只能靠记忆想一边看 Agent 改的文件、一边继续追问还得在编辑器和终端之间来回切。命令行本身没问题但会话一多管理成本就上来了。Pi Agent Web 解决的就是这件事。它是一个跑在本地的 Next.js 前端通过npx一条命令就能启动把本地 Pi Coding Agent 的会话数据、工具调用、模型配置、文件浏览全部搬到浏览器里。你依然用的是本地 Agent 的能力只是查看历史、继续对话、Fork 分支、切换模型这些操作变得可视化了。适合谁经常用 AI 编程 Agent 做多轮任务、需要管理大量会话、或者想给团队做一个本地 Agent 控制台的开发者。这篇教程按“能跟做”的标准来写先讲清楚它和 Pi 的关系再给出三种启动方式npx、全局安装、源码运行然后重点讲 Next.js 环境变量和 API 转发怎么配最后用一次真实的代码任务执行来验证整条链路通不通。中间会穿插我踩过的坑比如端口占用、会话目录读不到、next build污染开发环境这些。2. TaoToken 前置给 Pi Agent 准备一个稳定的模型入口Pi Agent Web 本身只是界面层真正干活的是背后的 Pi Coding Agent而 Agent 要调用大模型才能工作。所以在你启动 Web 界面之前得先确保本地 Pi 已经配好了可用的模型。这里我用 TaoToken 来做模型接入。它的作用是提供一个统一的 API 入口你拿到 Key 之后在 Pi 的模型配置里填上 base URL 和 KeyAgent 就能正常发起请求了。对于 Pi Agent Web 来说它读取的是本地~/.pi/agent/models.json和~/.pi/agent/settings.json所以只要 Pi 那边配通了Web 界面里新建会话时就能直接选到模型。具体操作分两步。第一步去 TaoToken 控制台创建一个 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建时给它起个能认出来的名字比如pi-agent-local方便以后区分。第二步把 Key 填进 Pi 的模型配置。如果你还没配过可以参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 base URL 和请求格式的说明。注意Pi Agent Web 不会替你管理 Key它只是读取本地已有的配置。所以务必先在 Pi 侧确认模型能正常对话再启动 Web 界面否则你会看到界面能打开、但发消息没反应的情况。配好之后你可以先在终端里用 Pi 跑一句简单对话验证确认模型通了再进入下一步。这一步别跳过后面排查问题时能省很多事。3. 可复制配置npx 启动 Next.js 环境变量 API 转发3.1 用 npx 直接启动最快路径最省事的方式是直接用npx拉最新版npx maddie1/pi-agent-weblatest启动成功后浏览器打开http://localhost:30141。如果你用的是国内 npm 镜像新版本可能还没同步会报 404 或者拉到旧版本这时候临时指定官方源npx maddie1/pi-agent-weblatest --registry https://registry.npmjs.org我实测下来第一次拉包会慢一点因为要下载 Next.js 相关依赖耐心等终端出现Ready字样再访问。3.2 全局安装后启动适合常用如果你打算长期用全局装更顺手npm install -g maddie1/pi-agent-web装完可以用pi-web或pi-agent-web启动。默认端口 30141想换端口和 hostpi-web --port 8080 --hostname 127.0.0.1短参数也行pi-web -p 8080 -H 127.0.0.1。3.3 Next.js 环境变量配置Pi Agent Web 默认读取~/.pi/agent/sessions作为会话目录。如果你的 Agent 数据不在默认路径需要指定PI_CODING_AGENT_DIR。macOS / LinuxPI_CODING_AGENT_DIR/path/to/agent-dir npm run devWindows PowerShell$env:PI_CODING_AGENT_DIRD:\your-agent-dir npm run dev端口也可以用环境变量覆盖避免和已有服务冲突PORT8080 pi-webPowerShell 下$env:PORT8080 pi-web3.4 API 转发配置说明Pi Agent Web 的后端接口都在app/api下前端通过 SSE 接收流式事件。核心链路是这样的浏览器发起请求 → Next.js API Routes →AgentSessionWrapper→ Pi 的AgentSession→ 读取本地 JSONL 文件。你不需要手动配反向代理但如果你把 Web 界面部署到别的机器、想连回本地的 Agent 服务就要注意hostname别只绑127.0.0.1否则外部访问不到。本地开发保持默认即可。如果你需要二次开发克隆源码后git clone https://github.com/MaddieMo1/Pi-Agent-Web.git cd Pi-Agent-Web npm install npm run dev开发时检查类型和 lintnode_modules/.bin/tsc --noEmit npm run lint注意开发过程中不要运行next build。它会生成.next/构建产物可能污染开发服务导致npm run dev出现异常。这是项目说明里明确提醒的我踩过一次清掉.next/才恢复。4. 验证请求浏览器访问、会话连通与一次代码任务执行启动之后先确认界面能打开。浏览器访问http://localhost:30141左侧应该出现会话列表按工作目录分组。如果本地已经有 Pi 的会话数据这里会直接列出来点进去能看到历史消息、工具调用记录。接着验证会话连通。在底部输入框发一句简单的话比如“列出当前目录下的文件”。发送后服务端会通过startRpcSession()创建或复用一个内存中的AgentSession前端通过 SSE 接收实时事件。你应该看到的是流式输出而不是等半天一次性返回。如果消息发出去没反应先回第 2 步确认模型配置。然后做一次真实的代码任务验证。我试过让它读一个项目文件并做小改动流程是这样的在输入框里写“读取package.json把 name 字段改成pi-agent-demo然后告诉我改了哪一行”。Agent 会调用文件读取工具界面上能看到工具调用和结果改完后给出说明。这一步能同时验证三件事模型通了、工具调用正常、文件读写权限没问题。如果你想验证模型对话本身是否正常也可以直接用模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息确认 Key 和模型都没问题再回到 Pi Agent Web 里操作。验证通过后你可以试试 Fork 功能在某条用户消息上点 Fork会从该节点创建一个新的独立会话文件侧边栏以子会话形式展示。适合“想从某个历史问题重新尝试另一种方案”的场景。会话内分支切换则不会创建新文件只是在同一会话里切换不同后续路径两者区别可以这样记Fork 产生新.jsonl分支切换不产生。5. 本篇常见错排查页面打开后没有历史会话。先确认~/.pi/agent/sessions存在。如果 Agent 数据在别处用PI_CODING_AGENT_DIR指定。另外如果某个会话文件第一行不是合法 header页面会标记为orphaned这是不完整会话不是 bug。npx 启动失败。大概率是国内镜像没同步新版本加--registry https://registry.npmjs.org重试。如果还失败检查 Node.js 版本建议 18 以上。端口被占用。默认 30141 被占时用pi-web --port 8080换端口或者用PORT环境变量。Windows 下$env:PORT8080; pi-web。发消息没反应。九成是模型配置问题。回第 2 步确认~/.pi/agent/models.json里的 base URL 和 Key 正确先在终端用 Pi 验证一次。开发时npm run dev异常。检查是不是跑过next build如果是删掉.next/目录再重启开发服务。想长期跑编码任务或 Agent 工作流。如果你不只是体验界面而是要把 Pi Agent 用在日常编码、多轮 Agent 任务上可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它在长会话和连续任务场景下更省心。接入相关的细节都在接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里遇到配置问题先翻文档比到处搜快。最后提醒一句Pi Agent Web 是本地 Agent 的可视化控制台不是替代编辑器也不是让你把生产库直连进去的工具。把它当成“会话管理和任务下发的浏览器入口”来用边界清晰出问题也好定位。