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 和 Key，Agent 就能正常发起请求了。对于 Pi Agent Web 来说，它读取的是本地~/.pi/agent/models.json和~/.pi/agent/settings.json，所以只要 Pi 那边配通了，Web 界面里新建会话时就能直接选到模型。
具体操作分两步。第一步，去 TaoToken 控制台创建一个 API Key，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建时给它起个能认出来的名字，比如pi-agent-local，方便以后区分。第二步，把 Key 填进 Pi 的模型配置。如果你还没配过，可以参考接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 base URL 和请求格式的说明。
注意：Pi Agent Web 不会替你管理 Key，它只是读取本地已有的配置。所以务必先在 Pi 侧确认模型能正常对话，再启动 Web 界面，否则你会看到界面能打开、但发消息没反应的情况。
配好之后，你可以先在终端里用 Pi 跑一句简单对话验证，确认模型通了，再进入下一步。这一步别跳过，后面排查问题时能省很多事。
3. 可复制配置：npx 启动 + Next.js 环境变量 + API 转发
3.1 用 npx 直接启动（最快路径）
最省事的方式是直接用npx拉最新版：
npx @maddie1/pi-agent-web@latest启动成功后，浏览器打开http://localhost:30141。如果你用的是国内 npm 镜像，新版本可能还没同步，会报 404 或者拉到旧版本，这时候临时指定官方源：
npx @maddie1/pi-agent-web@latest --registry https://registry.npmjs.org我实测下来，第一次拉包会慢一点，因为要下载 Next.js 相关依赖，耐心等终端出现Ready字样再访问。
3.2 全局安装后启动（适合常用）
如果你打算长期用，全局装更顺手：
npm install -g @maddie1/pi-agent-web装完可以用pi-web或pi-agent-web启动。默认端口 30141，想换端口和 host：
pi-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 / Linux：
PI_CODING_AGENT_DIR=/path/to/agent-dir npm run devWindows PowerShell：
$env:PI_CODING_AGENT_DIR="D:\your-agent-dir" npm run dev端口也可以用环境变量覆盖，避免和已有服务冲突：
PORT=8080 pi-webPowerShell 下：
$env:PORT="8080" 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开发时检查类型和 lint：
node_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_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 发一条消息，确认 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:PORT="8080"; 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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它在长会话和连续任务场景下更省心。接入相关的细节都在接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里，遇到配置问题先翻文档，比到处搜快。
最后提醒一句：Pi Agent Web 是本地 Agent 的可视化控制台，不是替代编辑器，也不是让你把生产库直连进去的工具。把它当成“会话管理和任务下发的浏览器入口”来用，边界清晰，出问题也好定位。
