Pi Agent + Pi Web：从终端到浏览器的轻量 Coding Agent 工作流

习惯 Claude Code、Codex 或 OpenCode 之后，再看一款 Coding Agent，最值得问的不是“它还能不能写代码”，而是它能不能用更轻的方式进入现有工作流。

Pi 的特点正是轻量和可扩展：核心界面留在终端，需要计划模式、MCP、LSP、浏览器或状态栏时再按需安装 package。Pi Web 则补上了另一块体验——它读取同一套本地配置与会话，把实时对话、历史记录、模型管理、Skill 管理和项目文件预览搬进浏览器。

这两者组合起来，可以同时保留终端的直接和网页界面的可视化。

Pi 和 Pi Web 分别负责什么

Pi 是实际执行任务的 Coding Agent。它连接模型、读取项目、调用工具，并把配置和会话保存在 ~/.pi/agent/ 下。

Pi Web 不是远程 SaaS，也不只是聊天记录查看器。它是在本机启动的 Web 工作台，可以直接调用 Agent，同时读取 Pi 的模型配置和会话文件。

终端中的 Pi ───────┐
                   ├── ~/.pi/agent/
浏览器中的 Pi Web ─┘     ├── models.json
                         ├── settings.json
                         └── sessions/*.jsonl
                                  |
                                  v
                         当前项目与模型服务

因此，在终端开始的会话可以回到 Pi Web 中浏览；网页里的模型设置、会话分支和项目上下文，也围绕同一个 Pi 数据目录工作。

开始前的准备

Pi Web 当前要求 Node.js 22.19.0 或更高版本，先检查本机环境：

node --version
npm --version

另外还需要准备一个可用的模型服务。它可以是 OpenAI、Anthropic 等官方服务，也可以是兼容相应 API 格式的自建或第三方服务。

如果你只想体验 Pi Web，可以直接通过 npx 启动；如果希望终端和网页配合使用，建议先把 Pi 装好并跑通一次基础对话。

安装并配置 Pi

Linux.do 的快速上手教程推荐通过 npm 安装：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

安装完成后运行：

pi

Pi 的自定义模型配置位于 ~/.pi/agent/models.json。Windows 对应 %USERPROFILE%\.pi\agent\models.json。一个精简的 OpenAI Chat 兼容配置可以写成：

{
  "providers": {
    "my-provider": {
      "baseUrl": "https://example.com/v1",
      "api": "openai-completions",
      "apiKey": "replace-with-your-api-key",
      "models": [
        {
          "id": "your-model-id",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

这里的 baseUrl、模型 ID、上下文长度和最大输出必须以服务商的真实参数为准，不要直接照抄示例。常见的 api 类型包括：

• openai-completions：多数 OpenAI Chat 兼容服务。
• openai-responses：支持 Responses API 的服务。
• anthropic-messages：Anthropic Messages 兼容服务。

示例中的 API Key 只是占位符。真实凭证只应保存在本机配置中，不要提交到 Git，也不要把带有凭证的配置截图公开。

为限流服务调整重试

Pi 默认会快速重试，但某些按分钟限制 RPM 的服务并不会在几秒内恢复。遇到连续 429 或限流错误时，可以在 ~/.pi/agent/settings.json 中加入：

{
  "retry": {
    "enabled": true,
    "maxRetries": 5,
    "baseDelayMs": 15000
  }
}

这会增加重试次数，并把基础等待时间提高到 15 秒。它适合明确由短时限流引起的失败；如果是 API Key、模型名或接口格式配置错误，延长等待只会让报错来得更晚，应该先修正配置。

启动 Pi Web

最省事的方式是不安装，直接运行最新版：

npx @agegr/pi-web@latest

也可以全局安装：

npm install -g @agegr/pi-web
pi-web

服务就绪后会尝试自动打开浏览器，也可以手动访问：

http://127.0.0.1:30141

常用启动参数包括：

pi-web --port 8080        # 修改端口
pi-web --no-open          # 不自动打开浏览器
pi-web -p 8080 -H 0.0.0.0

Pi Web 默认读取 ~/.pi/agent/sessions。如果你的 Pi 数据放在其他位置，可以在启动前设置 PI_CODING_AGENT_DIR 指向对应的 agent 目录。

网页界面真正补上了什么

Pi Web 的价值不只是“给终端套一层皮”，而是把几类在长任务中很难从终端一眼看清的信息集中起来：

• 按项目浏览历史会话，并继续之前的工作。
• 从早期消息重新编辑，或把会话 fork 成一条独立路线。
• 实时查看上下文占用、费用、压缩状态和系统提示。
• 在 Models 面板管理登录、API Key、模型配置并测试连通性。
• 搜索、安装、启用或停用 Skill。
• 一边对话，一边预览源码、文档、图片、音频、PDF 和 DOCX。
• 从侧边栏切换 Git worktree，让新会话和文件浏览跟随对应 checkout。

其中要特别区分两种“分支”：Fork 会创建新的 .jsonl 会话文件；“Edit from here”则是在同一个会话文件里产生新的对话分支。前者适合长期并行探索，后者更适合回到某个节点修正方向。

扩展不要一次装满

Linux.do 原文审查并列出了 22 个 Pi package，覆盖状态栏、计划、子代理、MCP、LSP、浏览器、Token 优化和主题等能力。这个清单适合用来发现扩展，但不代表每个人都需要一键全装。

更稳妥的方式是按实际痛点逐层添加：

# 统一扩展设置；使用它时应优先安装
pi install npm:@juanibiapina/pi-extension-settings

# 信息栏
pi install npm:@juanibiapina/pi-powerbar

# 计划和待办
pi install npm:@narumitw/pi-plan-mode
pi install npm:@juicesharp/rpiv-todo

# 外部能力
pi install npm:pi-mcp-adapter
pi install npm:@narumitw/pi-lsp

# 工作区撤销
pi install npm:pi-workspace-history

如果需要更自动化的执行，还可以再了解 @narumitw/pi-goal、@narumitw/pi-subagents 和 pi-agent-browser-native。每增加一个扩展，Agent 的工具面、依赖和排障范围都会扩大，所以最好一次只装一两个，确认没有命令冲突和异常行为后再继续。

第三方 package 本质上是会在本机运行的代码。安装前应检查仓库、维护状态、依赖和权限，不要只根据下载量或一键命令决定是否信任。

不要把 Pi Web 直接暴露到公网

这是整套方案最重要的安全边界。Pi Web 没有应用层身份验证，而且能够调用拥有较高本机权限的 Agent，因此默认只监听 127.0.0.1。

--hostname 0.0.0.0 只应该用于可信局域网。它不是“开启远程登录”，而是让网络中的其他设备可以直接访问服务。如果确实需要跨设备使用，应至少放在受控内网、VPN 或带强认证的访问层后面，同时限制防火墙来源。

通过可信反向代理使用自定义域名时，还需要显式允许准确的主机名：

PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web

PI_WEB_ALLOWED_HOSTS 是 Host 校验，不是用户认证，不能替代登录保护。

常见问题排查

Pi Web 看不到已有会话

先确认终端中的 Pi 和 Pi Web 是否使用同一个 agent 数据目录。默认会话路径是：

~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl

自定义过目录时，启动 Pi Web 前同步设置 PI_CODING_AGENT_DIR。

模型在终端或网页里调用失败

依次检查 baseUrl、api 类型、模型 ID 和 API Key。Pi Web 的 Models 面板可以直接测试模型，比反复发起完整任务更适合定位连接问题。

如果只有 429 限流错误，再考虑调整 retry；认证失败、接口不兼容和不存在的模型不会因为重试而恢复。

浏览器能联网，但模型请求走不通代理

Pi Web 的模型和 API 请求由本地服务端发出，需要给启动进程设置标准的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量，不能只依赖浏览器代理。

Windows Terminal 偶尔跳到滚动区域顶部

Linux.do 原文提到 Pi 配合 Windows Terminal 时可能出现滚动位置突然跳回顶部的问题。它更接近终端渲染问题；在修复前，可以把 Pi Web 作为长会话的替代查看界面。

一套更容易维护的使用顺序

1. 安装 Pi，先用一个模型完成最小配置。
2. 在终端跑通一次短任务，确认模型和工具调用正常。
3. 用 npx @agegr/pi-web@latest 启动本地网页。
4. 在 Pi Web 中确认历史会话、模型测试和项目文件预览都能工作。
5. 根据真实需求逐个添加计划、MCP、LSP 或浏览器扩展。
6. 保持默认本机监听，不把无认证的 Agent 工作台暴露到公网。

Pi 负责把 Coding Agent 保持得足够轻，Pi Web 负责让会话、配置和项目状态更容易观察。先用最小配置跑通核心链路，再逐步添加扩展，通常比一开始堆满 package 更稳定，也更容易知道问题来自哪里。

参考：

• Pi Agent 快速上手教程以及扩展推荐
• agegr/pi-web GitHub 仓库