把 Vibecoding 随身携带：升级新的 rpi 的 web 扩展作区

2026年10月24日15 分钟6,401 字#rpi #coding-agent #教程 #自托管

你可能已经有一个能工作的 rpi 项目：代码在自己的电脑上，模型凭据也不想交给第三方平台，但每次启动 Agent 都要守着终端。rpi-web 解决的不是“再造一个聊天框”，而是把这个本地工作区搬到浏览器里。

浏览器负责看见会话、文件、工具卡片和 Git diff；真正读写项目、调用模型、保存 transcript 的进程，仍然运行在你的电脑或服务器上。这个边界很重要：它既是 rpi-web 的吸引力，也是你部署远程访问时必须理解的安全边界。

下面这张图先把整条链路摆出来。看懂它，再执行安装命令，你就不会把“浏览器密码”“模型 API key”“项目目录”和“会话历史”混成一件事。

rpi-web 工作原理：浏览器连接 Web 服务，Web 服务为会话启动原生 rpi RPC 子进程，子进程访问项目目录和模型 Provider，会话索引与 transcript 单独保存 — 图 1：rpi-web 的关键边界。桌面端直接阅读，手机端可横向拖动查看细节，也可以点击图片打开支持缩放和拖动的交互版；图中关系依据 rpi-web 项目 README 和源码整理，不代表性能测试。

先理解三个原则：为什么它不只是一个网页壳

1. 浏览器是观察和操作入口，不是 Agent 本体

rpi-web 的前端会显示流式对话、工具调用、文件预览和 Git 变更，但项目 README 描述的运行链是 browser → Web server → rpi --mode rpc。浏览器断开时，服务端的会话和项目文件并不会因此变成浏览器本地数据。

2. 一次打开的会话，对应一个原生 rpi 子进程

Web 服务负责把浏览器请求接到会话运行时。每个打开的会话都有独立的 native host，因此“新建会话”不是换一个网页标签，而是建立一条独立的 Agent 上下文。工具真正执行在哪里？在运行 Web 服务的那台机器上。

3. 可恢复性来自服务端的分层保存

项目源文件、会话 transcript、registry 索引和 projects.json 不是同一个文件。registry 负责会话的标题、置顶和归档等组织信息；native host 保存真正的 transcript；源码仍在项目目录。重启后要恢复历史，不能只备份一个索引文件。

因此，rpi-web 最适合三类人：想在浏览器里操作本地 Agent 的个人开发者；把项目放在家用服务器或开发机上的用户；需要查看文件和 Git 变更、又不想把执行权交给 SaaS 的团队。它不是多租户在线 IDE，也不是完整的浏览器自动化工具。

这篇文章按项目当前的 rpi-web 0.1.7 资料来写，主线是从安装到完成第一次会话。先不讨论性能，也不把 rpi-web 写成一个完整的 Web IDE：它目前最重要的价值，是让你用浏览器操作 rpi 的项目、会话、工具和 Git 变更。

先选对安装方式

rpi-web 有两个入口：

native extension：把 Web 服务安装到 rpi，用 rpi --webserver 启动。适合已经在使用 rpi 的人，也是本文的主路径。
standalone executable：单独运行 rpi-web，再指定 rpi 可执行文件。适合容器、服务器或不想把 Web 服务入口放进宿主 CLI 的场景。

两种入口共享同一套 Web 工作区。区别在于谁负责启动 Web 服务。无论选哪一种，项目文件、模型凭据和会话记录都在运行服务的那台机器上。

项目的 rpi-web README 目前以 rpi 0.7.0 作为配套 native host 示例。安装前先查看本机版本：

rpi --version

不要把文章中的版本号当成你的本地状态。扩展和宿主需要处在项目支持的版本范围内；遇到加载失败时，先看 rpi --version 和 rpi-web --version，再按对应发布说明升级。

最短路径：安装扩展并启动

2. 在项目目录生成配置

进入你准备交给 Agent 使用的项目目录：

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

init 会创建 .rpi/web.json，而且不会覆盖已有配置。默认配置大致是：

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

这里的 project: ".." 是因为配置文件通常位于项目的 .rpi/ 目录中，.. 指向项目根目录。Windows 下建议在 JSON 路径中使用正斜杠，例如 D:/Projects/my-project，避免反斜杠转义问题。

3. 启动 Web 服务

仍然在这个项目目录中执行：

rpi --webserver

成功绑定后，终端会显示类似下面的状态：

Status      Running
Listen IP   127.0.0.1
Port        3030
Open        http://127.0.0.1:3030
Project     /path/to/your-project
Password    Not configured

打开 http://127.0.0.1:3030/，然后保持这个终端进程运行。按 Ctrl+C 会停止 Web 服务；已经保存的会话不会因此自动消失。

rpi-web 0.1.7 把 --webserver 作为首选入口，--web 仍是兼容别名。如果你看到旧教程使用 rpi --web，不必同时传两个参数，统一使用：

rpi --webserver

只想临时换一个端口，不必修改 JSON：

rpi --webserver --port 3031

命令行参数会覆盖配置文件。若使用 --port 0，系统会分配一个空闲端口，终端状态页会显示实际端口。

第一次会话：从项目到可执行任务

页面打开后，不要先急着研究所有设置。先看一眼实际工作区，再按下面的顺序走一遍，确认“浏览器 → rpi → 项目工具”这条路径是通的。

rpi-web 工作区界面：左侧项目和会话栏，中间新会话提示，右侧模型状态、文件树和 Git 变更面板 — 图 3：打开工作区后的核心布局。左侧管理项目和会话，中间是对话入口，右侧用于查看上下文、文件和变更；这是本地预览截图，项目名和状态不代表你的环境。

选择项目并新建会话

在左侧项目栏选择项目，点击 New session。每个会话对应一个独立的原生 rpi 子进程，因此不同会话的上下文不会混在同一条对话里。

第一次可以输入一个只读任务，例如：

先阅读项目根目录的 README，告诉我项目的入口、构建命令，以及你还缺哪些信息。暂时不要修改文件。

这个提示的作用不是测试模型有多聪明，而是确认三件事：项目路径正确、模型凭据可用、工具调用能返回浏览器。

选择模型、思考级别和工具

点击模型名称或打开 Runtime settings，可以选择：

当前模型；
thinking level；
当前会话启用的工具。

模型设置决定请求发给谁，工具设置决定 Agent 能否读取文件、执行命令或写入项目。工具卡片会显示调用过程和结果；需要用户选择或确认的交互，会在浏览器中打开相应对话框。

rpi-web 运行时设置面板：模型、上下文、思考深度和启用的 read、bash、edit、write、webfetch、websearch 等工具 — 图 2：运行时设置把“用哪个模型”和“允许哪些工具”放在同一个会话入口里。截图来自本地工作区预览；其中的项目名、模型名和上下文数字只是界面示例，不代表本文推荐或真实调用结果。

完成只读检查后，再给一个边界清楚的任务，例如：

请提出 README 首页的三个改进建议，只修改 README.md 的标题和开头两段。修改前先说明计划，完成后列出 diff。

文件面板可以查看项目文件，Git 面板可以查看变更和 diff。它们主要用于检查结果；真正的文件修改仍然由 Agent 通过工具完成。

中途停止和恢复

运行中的任务可以点击停止按钮。普通消息在任务运行时会进入 follow-up queue，可以在队列面板中查看或取消。

如果任务在进程退出前被中断，重新打开会话后可以使用 /continue，或者点击界面中的恢复操作。上下文过长时使用：

/compact

也可以附加希望保留的重点：

/compact 保留当前修改、失败原因和下一步验证命令

这些命令不是浏览器自己模拟的快捷操作，而是调用同一个会话运行时提供的命令。这样刷新页面或重启服务后，历史仍然以 native session 为准，而不是只依赖浏览器内存。

把启动配置留下来

.rpi/web.json 适合保存项目路径、端口和服务入口。一个更完整的例子是：

{
  "project": "D:/Projects/my-project",
  "projects": [
    "D:/Projects/another-project"
  ],
  "projectsRoot": "D:/Projects/web-projects",
  "rpiBin": "C:/Tools/rpi/rpi.exe",
  "bind": "127.0.0.1",
  "port": 3030,
  "registry": "D:/Data/rpi-web/registry.json",
  "sessionDir": "D:/Data/rpi-web/sessions"
}

配置文件中的相对路径，是相对于配置文件所在目录解析的，不是相对于当前 shell 目录。配置加载顺序是：

内置默认值；
~/.rpi/agent/web.json，或 RPI_CODING_AGENT_DIR 指定目录下的 web.json；
启动项目的 .rpi/web.json；
命令行参数。

后面的配置会覆盖前面的配置。使用 standalone rpi-web 时，一次性的 --port、--bind、--project 等参数优先级最高；native extension 明确转发 --port 和 --bind，项目列表则建议写进 .rpi/web.json。

管理多个项目

浏览器里的 Add project 主要管理 projectsRoot 下面的目录。也就是说，服务端允许你通过网页创建或添加的目录，必须位于这个受管理的根目录中。

如果要挂载一个已经存在、但不在 projectsRoot 下的目录，使用 standalone 的 rpi-web 启动参数显式添加：

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

native extension 则把固定项目写进 .rpi/web.json 的 projects 数组，再用 rpi --webserver 启动。在 Windows PowerShell 中，把路径改成实际的 Windows 路径即可。这里有一个容易忽略的边界：如果 rpi-web 跑在远程服务器上，/work/project-b 指的是服务器目录，不是你打开浏览器那台电脑的目录。

模型凭据和网页密码不是一回事

网页访问密码只负责保护 rpi-web 页面；模型 API key 负责让 rpi 调用 provider。两者要分开配置。

最简单的开发环境可以使用环境变量：

export ANTHROPIC_API_KEY='your-api-key'
# 或者：
export OPENAI_API_KEY='your-api-key'

Windows PowerShell 写法是：

$env:ANTHROPIC_API_KEY = 'your-api-key'

然后用本地检查确认 rpi 是否看到了 provider：

rpi auth check

auth check 用于检查本地配置，不会因为这条命令主动发起模型请求。API key 也可以放在 rpi 的认证文件中，或在 ~/.rpi/agent/models.json 中声明自定义 provider。例如，一个 OpenAI-compatible 网关可以写成：

{
  "providers": {
    "gateway": {
      "api": "anthropic-messages",
      "baseUrl": "https://gateway.example.com",
      "apiKey": "sk-gateway-secret",
      "models": [
        { "id": "custom-claude", "name": "Custom Claude" }
      ]
    }
  }
}

然后用完整的 provider/model 选择它：

rpi --model gateway/custom-claude -p "hello"

示例中的 key 只能替换成你自己的值，不能把真实密钥提交到 Git 仓库。服务进程由谁启动，就要保证谁能读到对应的环境变量、认证文件和 models.json。你在交互式终端里配置过凭据，不代表另一个系统服务用户也能看到它。

给 rpi 加上搜索和网页抓取

rpi-web 本身是工作区界面，不等于一个可以点击网页、登录网站的浏览器。如果希望 Agent 查找公开资料，可以另外安装两个扩展：

rpi install rpi-websearch
rpi install rpi-webfetch

它们的分工不同：

rpi-websearch 返回标题、URL 和摘要；
rpi-webfetch 读取公开 HTTP(S) 页面的可读文本。

这两个扩展都不提供网页 JavaScript 执行、点击流程或登录能力。安装后要重启 rpi，让宿主重新加载扩展。对于需要登录、上传文件或操作复杂前端的场景，不能把它们当成完整浏览器自动化。

需要远程访问时，先补上三层保护

默认情况下，rpi-web 只监听 127.0.0.1，这适合本机使用。要从局域网或反向代理访问，需要同时考虑监听地址、Host 校验和登录密码。

Linux/macOS 示例：

export RPI_WEB_PASSWORD='replace-with-a-long-password'
export RPI_WEB_ALLOWED_HOSTS='192.168.1.10:3030,127.0.0.1:3030,localhost:3030'

rpi-web \
  --project /work/my-project \
  --rpi-bin /path/to/rpi \
  --assets /path/to/web/assets \
  --bind 0.0.0.0 \
  --port 3030

如果使用 native extension，对应的启动命令是：

rpi --webserver --bind 0.0.0.0 --port 3030

RPI_WEB_ALLOWED_HOSTS 是逗号分隔的 Host 值，需要写主机名或 IP 和实际端口，不要带 http://、路径或通配符。远程入口还应使用 HTTPS 和访问密码。若放在反向代理后面，要保留浏览器的 Host，设置 X-Forwarded-Proto: https，并关闭 SSE 响应缓冲，否则流式回复可能无法及时到达浏览器。

这里还有一个使用边界：当前访问密码是共享密码，访问者看到的是同一个服务的项目和会话。它适合个人机器、可信内网或明确隔离的服务用户，不适合直接把一个共享工作区暴露给不受信任的多人。

重启、升级和历史恢复

rpi-web 会把几类状态分开保存：

registry 记录会话 ID、标题、置顶和归档等组织信息；
projects.json 记录通过浏览器添加的项目；
native host 保存真正的会话 transcript；
项目源文件仍在项目目录中。

默认 registry 是 ~/.rpi-web/sessions.json，可以用 --registry 改位置；需要迁移或容器化时，也要保留 --session-dir 指向的会话目录。只复制 registry 文件，不能恢复完整对话。

服务重启后，保存过的会话可能先显示为 offline。选中它可以重新打开；如果看不到历史，按下面的顺序检查：

服务用户是否变了；
project 路径是否仍然存在；
registry 和 sessionDir 是否仍指向原位置；
模型配置和扩展目录是否被新环境继承。

升级前让运行中的任务结束，停止 Web 服务，备份项目、registry、session directory 以及服务用户的 rpi 配置。替换与 host 匹配的 Web 可执行文件或扩展后，再启动并检查版本。

什么时候用 standalone executable

如果你要在服务器或容器中独立运行 Web 服务，可以下载 host 和 Web 的预编译包。Web release 还需要完整的 assets/ 目录；一个典型目录如下：

C:/Tools/rpi-web/
├── rpi-web.exe
├── rpi.exe
└── assets/
    ├── index.html
    ├── favicon.svg
    └── assets/

Linux/macOS 的文件名没有 .exe。然后显式指定项目、host 和前端资源：

./rpi-web \
  --project /path/to/my-project \
  --rpi-bin /path/to/rpi \
  --assets "$PWD/assets" \
  --port 3030

预编译包不需要 Rust 或 Node.js；如果要使用 Git 面板，服务进程的 PATH 中还要能找到 Git。源码构建时，前端会被嵌入 native extension 和 standalone 程序；部署时仍可以用 --assets 指向一份外部前端资源。

下载入口：

rpi host releases：https://github.com/bigfish1913/pi-rust/releases/tag/v0.7.0
rpi-web releases：https://github.com/pi-rust/rpi-package/releases?q=rpi-web-v
rpi-package：https://github.com/pi-rust/rpi-package

项目 README 当前以 host 0.7.0 作为示例配对。你实际下载后仍应执行 rpi --version 和 rpi-web --version，不要把旧 standalone 包和新的 native extension 说明混在一起。

常见失败，先看哪一层

现象	先检查
`rpi --webserver` 进入终端聊天，没有出现 Web 状态页	是否安装了 `rpi-web` 扩展；`rpi-web 0.1.7` 使用 `--webserver`，旧扩展可能只认识 `--web`
能启动但页面空白或 JS/CSS 404	standalone 的 `--assets` 是否指向包含 `index.html` 和内层 `assets/` 的完整目录；更新时不要只替换一个 JS 文件
页面能打开，模型调用失败	运行 `rpi auth check`；确认服务进程能读到 provider、API key、`models.json` 和正确的模型 ID
局域网访问被拒绝	检查 `--bind`、端口、防火墙，以及 `RPI_WEB_ALLOWED_HOSTS` 是否写了实际 Host 和端口
浏览器无法添加已有目录	目录是否位于 `projectsRoot`；不在根目录内的既有项目用 `--add-project`
重启后找不到历史	检查 registry、`sessionDir`、项目路径和服务用户是否改变；只保留 registry 不够
想让 Agent 搜索网页却没有 `websearch`	单独安装 `rpi-websearch`，安装后重启 rpi；它不是 rpi-web 内置能力

你可以从哪条路径开始

如果你只是想在自己的电脑上用浏览器操作 rpi，安装 native extension，然后执行：

rpi --webserver=init
rpi --webserver

如果你要把工作区放到一台服务器上，使用 standalone 或 native extension 都可以，但要把项目目录、凭据、会话目录和访问保护一起规划好，不要只把端口暴露出去。

如果你想把 rpi 接入其他界面或服务，再去看 rpi-http、ACP 和其他扩展。rpi-web 解决的是“浏览器中的项目工作区”这个问题：它让终端 Agent 多了一个可恢复、可查看文件和 Git 变更的入口，同时把实际执行权留在你控制的那台机器上。

本文依据项目资料整理：

rpi-web 使用指南：https://github.com/pi-rust/rpi-package/blob/main/packages/rpi-web/README.md
rpi CLI 使用说明：https://github.com/bigfish1913/pi-rust/blob/main/crates/rpi-cli/README.md
rpi 用户指南：https://github.com/bigfish1913/pi-rust/blob/main/crates/rpi-cli/embedded-docs/user-guide.md

云服务器推荐

如果你需要部署博客、Docker 服务或个人项目，可以参考：

腾讯云特惠产品合集页阿里云云小站官方上云特惠

本文包含推广链接。通过链接购买不会增加你的费用，但我可能获得少量佣金。