📦 Pi Web 详细部署教程

Pi Web 是 pi coding agent 的本地浏览器用户界面。它共享 pi agent 的配置和会话文件，让你可以通过浏览器浏览、恢复对话、运行 agent、配置模型和资源、以及检查项目文件。部署 Pi Web 非常简单，核心就是运行一个 Node.js 命令行工具。

⚙️ 部署前准备

在开始之前，请确保你的系统满足以下唯一且必须的要求：

  • Node.js 环境：需要 Node.js 22.19.0 或更新版本。你可以通过在终端中运行 node --version 来检查你的版本。
  • （可选）Pi Agent：Pi Web 是 pi agent 的 UI 前端，如果你还没有安装 pi agent，可以同时使用 Pi Web 来配置模型和凭证。不过，Pi Web 可以独立运行，以便你后续配置。

🚀 快速启动

Pi Web 无需安装，通过 npx 即可一键运行。

  1. 打开终端，执行以下命令：

    1
    npx @agegr/pi-web@latest

  2. 等待服务启动。命令执行后，CLI 会在服务器准备就绪后自动打开浏览器。

  3. 访问地址：如果浏览器没有自动打开，可以手动访问 http://127.0.0.1:30141。Pi Web 默认只监听在 127.0.0.1（即本机）。

首次使用提示：如果尚未配置模型提供商，请打开 Pi Web 界面中的 Models（模型） 面板，进行登录或添加 API 密钥。

🛠️ 全局安装与更新（可选）

如果你希望将 pi-web 命令安装到系统全局，可以执行：

1
2
3
npm install -g @agegr/pi-web@latest
# 安装后，直接输入命令即可启动
pi-web

更新：停止正在运行的进程 (Ctrl+C)，然后重新运行相同的安装命令即可完成更新。

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

卸载：

1
npm uninstall -g @agegr/pi-web

⚙️ 高级配置与选项

Pi Web 提供了丰富的命令行选项和环境变量，方便你自定义启动行为。

常用启动参数

运行 pi-web --help 可以查看所有启动选项。

选项 / 环境变量 用途 默认值
--port <port> 或 -p <port> 或 PORT 指定服务器端口 30141
--hostname <host> 或 -H <host> 或 PI_WEB_HOSTNAME 指定绑定的主机地址 127.0.0.1
--no-open 或 PI_WEB_NO_OPEN=1 禁止自动打开浏览器 浏览器会自动打开
PI_WEB_PASSWORD 启用 HTTP 基础认证（用户名固定为 pi） 认证禁用
PI_WEB_IDLE_TIMEOUT_MS 会话空闲超时时间（毫秒），0 表示禁用 600000 (10分钟)

示例：

1
2
3
4
5
# 在 8080 端口上监听所有网络接口，并禁止自动打开浏览器
pi-web -p 8080 -H 0.0.0.0 --no-open

# 使用密码保护
PI_WEB_PASSWORD='你的强密码' pi-web --hostname 0.0.0.0

远程访问与安全警告

  • 重要：将 --hostname 绑定到 0.0.0.0 会允许网络上的其他设备访问 Pi Web，这会暴露一个可执行高权限操作的 agent。
  • 务必设置强密码：通过 PI_WEB_PASSWORD 环境变量启用 HTTP Basic Auth。
  • 使用 HTTPS：Basic Auth 不会加密传输的密码，切勿通过明文 HTTP 在互联网上暴露 Pi Web。应通过受信任的反向代理（提供 HTTPS）或 VPN 进行访问。

HTTP 代理配置

如果你的网络环境需要通过代理访问外部 API，Pi Web 会遵循标准的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。

  • macOS/Linux:

    1
    HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 npx @agegr/pi-web@latest

  • Windows PowerShell:

    1
    2
    3
    $env:HTTP_PROXY = "http://127.0.0.1:7890"
    $env:HTTPS_PROXY = "http://127.0.0.1:7890"
    npx @agegr/pi-web@latest

💡 核心特性与使用须知

  • 数据目录：Pi Web 默认读取 ~/.pi/agent 目录下的数据，包括会话文件。你可以通过设置 PI_CODING_AGENT_DIR 环境变量来更改此路径。
  • 配置同步：在 Pi Web 的 Models（模型） 面板中进行的配置（如 API 密钥、模型设置）会与 pi agent 共享，两边界面修改互相同步。
  • 文件访问边界：Pi Web 的文件浏览器并非通用文件系统浏览器，其访问范围被限定在 Pi Web 中选定的工作目录以及它已知的项目或会话根目录内。
  • Git Worktrees：支持在侧边栏切换 Git worktree 检出，同时同仓库的会话会保持分组。详情请参阅项目文档中的 “Worktrees in Pi Web”。

🧑‍💻 开发与贡献

如果你想修改 Pi Web 的源代码或参与贡献，可以克隆仓库进行开发。

1
2
3
4
git clone https://github.com/agegr/pi-web.git
cd pi-web
npm install
npm run dev

开发服务器会在 http://127.0.0.1:30141 运行。

常用开发命令：

  • npm test：运行测试。
  • node_modules/.bin/tsc --noEmit：TypeScript 类型检查。
  • npm run lint：代码规范检查。
  • 注意：正常开发时不要运行 next build 或 npm run build，这会写入 .next/ 目录并可能干扰开发服务器。

❓ 常见问题

  • Q: 启动后浏览器没有自动打开？
    • A: 这通常意味着服务已启动但浏览器未响应。请手动访问 http://127.0.0.1:30141。你也可以通过 --no-open 禁用自动打开。
  • Q: 提示 Node.js 版本过低？
    • A: Pi Web 需要 Node.js 22.19.0+。请使用 nvm 或 Node.js 官网升级版本。
  • Q: 如何更改默认端口？
    • A: 启动时使用 --port 选项，例如 pi-web --port 8080。
  • Q: 如何让局域网其他设备访问 Pi Web？
    • A: 使用 --hostname 0.0.0.0 启动，但务必同时设置 PI_WEB_PASSWORD 强密码，并确保网络环境安全（如使用 VPN 或反向代理 HTTPS）。

更详细的配置说明、Git worktree 使用和开发指南，请查阅项目中的 AGENTS.md 和 docs/ 文件夹。