简介
本页说明 pi-webapp 是什么、它在 Pi 之上多了什么，以及三种运行方式该选哪一种。
pi-webapp 是什么
Pi 是一个在你本机读写文件、运行命令的编程代理。pi-webapp 是它的本地界面：一个浏览器页面或桌面窗口，叠在 Pi 之上，在对话周围补上一个工作区。
真正干活的仍然是 Pi：它运行代理、调用你的模型提供方、执行工具并写入会话历史。pi-webapp 不替代其中任何一部分，所以你已有的 Pi 模型、技能、扩展和已保存的会话都能直接沿用。
你能得到什么
| 能力 | 作用 |
|---|---|
| 对话 | 流式回复、可展开的工具调用、用量统计、按轮次查看的轨迹、文件附件，以及 Pi 忙碌时可以继续排队的消息。 |
| 会话与工作区 | 每个项目目录就是一个工作区，有自己的已保存会话。会话互相独立，切换到另一个不会打断前一个。 |
| 文件、终端与 Git | 只读文件预览、真实的交互式 Shell，以及用来审阅差异、暂存、提交和切换本地分支的 Git 面板。 |
| 图表 | 可选的 Excalidraw 插件，把一句话变成可编辑的图表。 |
| 模型与提供方 | 登录提供方或填写 API Key、选择模型，还可以添加自己的 OpenAI 或 Anthropic 兼容地址。 |
| 包、技能与插件 | 管理 Pi 包和技能，开关内置的文件、终端和 Git 能力。 |
三种运行方式
| 方式 | 命令或下载 | 适合 | 运行多久 |
|---|---|---|---|
| Web 启动器 | npx pi-webapp | 大多数人。只需要 Node.js。 | 作为后台服务运行，关掉终端和浏览器标签页都不会停，直到你运行 pi-webapp stop。 |
| 在 Pi 终端里使用 | pi install npm:pi-webapp，然后在 Pi 里输入 /web | 你已经在用 Pi 的终端界面，想在浏览器里看同一个会话。 | 与那个 Pi 进程绑定，退出 Pi 就结束。 |
| 桌面应用 | GitHub Releases 里的测试版 | 更喜欢独立窗口，也不想安装 Node。 | 退出时可以选择让服务继续在后台运行。 |
先看快速开始，它讲的是 Web 启动器。另外两种见在 Pi 终端里使用和桌面版。
你需要准备什么
- Node.js 22.19 或更新版本，用于 Web 启动器和
/web。桌面应用自带 Node。 - 一个你能用的模型。 pi-webapp 不自带模型。你可以登录某个提供方、粘贴 API Key，或指向一个兼容的地址。界面在本地并不等于本地推理：你的消息会发给你选定的提供方。
- 如果要用 Git 面板，需要安装 Git。
它是怎么工作的
启动器在本机 127.0.0.1（只有你自己的电脑）的一个随机端口上启动一个小型 HTTP 服务。它打印出的地址里带有一个随机访问令牌，页面用这个令牌访问服务的每个请求。服务驱动 Pi，Pi 照常把数据放在 ~/.pi/agent 下。pi-webapp 没有自己的云服务。
不是沙箱
代理和终端以你自己的用户权限运行。工作区只是一个起始目录，不是受限区域。让代理接触敏感内容之前，请先读安全与隐私。
我读的是哪个版本的说明？
这些页面描述的是本仓库的源码。你安装的版本可能更旧或更新：打开 Pi 设置 → 通用设置，在 应用更新 → 当前版本 里查看。版本之间的差异会在相关位置标出。
下一页：快速开始。