先说 rpi 是什么

Vibecoding 不必固定在终端前。把 rpi-web 跑在自己的电脑或服务器上，完成远程访问配置后，就能从手机或另一台设备的浏览器进入工作区，继续查看会话、文件和 Git 变更。

rpi 是一个运行在本机或服务器上的 coding agent。配置模型后，它可以读取项目目录，调用 read、bash、edit 等工具，查看文件和 Git 变更，并在用户给出边界后协助完成代码任务。

它的一个重要使用方式是自托管：项目文件、模型凭据和会话记录可以留在开发机或服务器上。rpi-web 就是在这个基础上提供浏览器入口，让 Vibecoding 从固定终端延伸到其他受控设备。这里的“随身”依赖远程访问配置，并不意味着项目自动同步到手机。

图：运行链路依据项目 README 和源码整理，不代表性能测试。

rpi-web 做了什么

rpi-web 是 rpi 的浏览器工作区。它提供项目和会话侧栏、流式对话、工具交互、文件预览和 Git diff。浏览器主要负责界面与操作，实际的项目访问和模型请求仍由服务所在机器执行。

运行链路可以概括为：

browser
  → rpi --webserver（native extension）或 rpi-web（standalone）
  → rpi --mode rpc
  → model provider + project tools

每个打开的会话使用独立的 native host 子进程。浏览器刷新或断开，不会把服务端的项目文件变成浏览器本地数据。

图：工作区来自本地预览，项目名和状态仅为界面示例。

会话恢复依赖几层服务端数据：

• registry 保存会话 ID、标题、置顶和归档状态；
• projects.json 保存通过浏览器添加的项目；
• native host 保存 transcript；
• 项目源文件仍然位于项目目录。

因此只复制 registry 文件并不能恢复完整对话。

最短启动路径

项目当前版本为 rpi-web 0.1.7。README 使用 rpi 0.7.0 作为配套 native host 示例，安装后仍应检查自己的版本，不要把两个版本号混成兼容承诺。

rpi --version
rpi install rpi-web --github pi-rust/rpi-package

在目标项目目录初始化配置并启动：

cd /path/to/your-project
rpi --webserver=init
rpi --webserver

默认配置大致如下：

{
  "project": "..",
  "rpiBin": "rpi",
  "port": 3030
}

从 rpi-web 0.1.7 开始，--webserver 是首选入口，--web 保留为兼容别名。

图：本地预览截图，用于说明界面结构；其中项目名、模型名和状态仅为示例。

模型凭据与网页密码

网页访问密码保护 rpi-web 页面，模型 API key 则用于让 rpi 调用 Provider。这是两套配置。

export ANTHROPIC_API_KEY='your-api-key'
rpi auth check

rpi auth check 用来检查本地凭据配置，不会因为这条命令主动发起模型请求。服务进程由谁启动，就要确保它能读到对应的环境变量、认证文件和 models.json。

多项目与扩展

浏览器里的 Add project 主要管理 projectsRoot 下面的目录。已经存在、但不在管理根目录内的项目，可以通过 standalone：

rpi-web \
  --project /work/project-a \
  --add-project /work/project-b \
  --projects-root /work/new-projects \
  --rpi-bin /path/to/rpi \
  --port 3030

native extension 则把固定项目写进 .rpi/web.json 的 projects 数组。

如果需要让 Agent 读取公开网页，可以另外安装：

rpi install rpi-websearch
rpi install rpi-webfetch

前者提供搜索结果摘要，后者读取公开 HTTP(S) 页面的可读文本。它们不提供登录、点击流程和 JavaScript 浏览器自动化。

远程访问与恢复

默认监听地址是 127.0.0.1。远程访问至少需要一起考虑：

• --bind 或配置中的监听地址；
• allowedHosts 或 RPI_WEB_ALLOWED_HOSTS；
• RPI_WEB_PASSWORD；
• HTTPS 反向代理；
• SSE 响应缓冲设置。

共享密码意味着访问者看到的是同一个服务的项目和会话，不适合直接暴露给不受信任的多人。

升级或迁移前，应同时保留项目目录、registry、session directory、rpi 配置和服务用户。重启后会话可能显示为 offline，需要确认服务用户、项目路径、registry 和 sessionDir 没有改变。

项目与完整教程

• rpi-package：https://github.com/pi-rust/rpi-package
• pi-rust：https://github.com/bigfish1913/pi-rust
• 🏠 官网与文档：https://rpi.bigfisharc.cn/
• ✍️ 个人博客：https://blog.bigfisharc.cn/