pi-web-chat

在浏览器与手机上，统一使用 pi 和 Codex。

移动优先的 Coding Agent Web 工作台：原生会话、实时工具、项目文件与 Git、断线恢复，以及 Token + 2FA 安全访问。

它是什么

pi-web-chat 最初是 pi 的 Web 扩展。现在，它是可独立安装和启动的 npm 应用，同时保留原有 Pi 扩展入口；一个 Web 服务即可创建、恢复和控制 Pi 与 Codex 两类 Agent 会话。

[!IMPORTANT] 推荐通过 npm 全局安装并运行 pi-web-chat。包内 Pi SDK 是 Pi 会话的权威 runtime；Codex 会话复用本机已安装并登录的 codex CLI。pi install、pi --web 与 /web 继续作为兼容入口，并管理同一个 daemon。

启动后，你可以在网页设置中为新会话选择 pi 或 Codex。已有会话保留各自的后端，pi 与 Codex 标签页可以同时在线、独立运行和恢复。

核心亮点

快速开始

1. 独立安装 pi-web-chat

需要 Node.js 22.19 或更高版本。

# npm 会同时安装 Web Chat 所需的 Pi SDK runtime
npm install -g @ryn-mic/web-chat

npm 包名是 @ryn-mic/web-chat，安装后的命令是 pi-web-chat。不需要先安装 Pi CLI，也不需要执行 pi install。

2. 检测 Agent 并启动 Web 服务

pi-web-chat doctor
pi-web-chat
# pi-web-chat started — http://127.0.0.1:3141

doctor 区分包内 Pi runtime、外部 Pi CLI 与 Codex CLI。默认启动会再次显示简洁探测结果，然后在后台启动 daemon、打开浏览器并立即把终端控制权交还给你。如果服务已经运行，它只会打印现有地址，不会启动第二套服务。

外部 pi 命令是可选的：未安装时，Pi 会话仍使用 npm 包内的 SDK 正常工作。Codex 会话需要本机 codex 命令；未安装或不可用时，Web Chat 与 Pi 会话仍可启动。

3. 可选：启用 Codex 会话

先确保本机 codex 命令可用并已完成 codex login，然后：

1. 运行 pi-web-chat；
2. 打开网页左侧会话抽屉，进入「设置」；
3. 将「新会话使用的 Agent」切换为 Codex；
4. 新建会话。已有 pi 会话不会被转换或中断。

pi + Codex：如何协作

项目	pi	Codex
是否默认	是	否，按需选择
启动入口	pi-web-chat	由同一个 pi-web-chat 服务承载
本机准备	npm 包已包含 Pi SDK；配置模型与认证	安装 Codex 并执行 codex login
会话标识	pi session / JSONL	原生 Codex threadId
Web 能力	流式消息、工具、模型、思考档位、运行中追加指令（steering）、中止	流式轮次、工具与计划、模型与推理档位、运行中追加指令、中止、审批、用户问题、MCP 表单

Codex 传输默认为 auto：优先连接已运行的共享 Codex daemon，不可用时安全回退到 standalone 原生 app-server。

传输模式	行为	适用场景
auto	优先共享 daemon，失败时回退 standalone	默认推荐
proxy	要求共享 daemon 可用，否则失败	发现、观察并在释放后接续 Remote Control / Desktop / CLI 的线程
standalone	使用原生持久化线程，但不能共享另一客户端内存中的进行中 turn	只在 Web Chat 内使用 Codex

如需让 Web Chat 发现、观察并接续同一批 Codex 线程，请先执行：

codex remote-control start
pi-web-chat 3141 restart

Codex 线程遵循单写者约束：当另一客户端正在占用线程时，Web Chat 会以只读 observer 观察；占用释放后再自动升级并接续。standalone 描述的是传输连接方式，不代表每个会话都会单独启动一个操作系统进程；会话仍由原生 threadId 隔离。

功能一览

• 流式对话：文本与思考过程增量、Streamdown Markdown、Shiki 代码高亮、工具调用与可展开结果。
• 多会话工作台：会话列表、独立标签、每会话 URL（/s/:sessionId）、后台持续运行；连接同一个 pi-web-chat 服务并打开同一会话 URL 时可跨设备实时同步。
• 可靠恢复：长历史分页、活动分支同步、增量快照、断线重连与缺失事件补拉。
• 完整交互：发送、运行中追加指令（steering）、中止、模型选择、思考强度、图片附件、用户消息复制与重新填入。
• Codex 原生闭环：命令、文件和权限审批，用户问题、MCP 信息征询表单、计划与上下文用量。
• 项目文件：目录树、受限搜索、@ 引用、文本/图片/PDF/Office/媒体等安全预览。
• Git 工作区：状态、分支、提交历史、diff 查看；工作区干净时可切换本地分支。
• 个性化：系统/浅色/深色主题、pi/Codex 独立状态动效、自定义模型与供应商。
• PWA：可安装到桌面或手机，带自动更新提示；API 与 WebSocket 不做离线缓存。

聊天输入框中的 / 命令

在输入框键入 / 会按当前会话的 Agent 展示命令面板。可使用上下方向键选择、Tab 补全、Esc 关闭，也可以直接点击或触摸命令；补全后按发送键执行。切换 Pi/Codex 会话时，目录会随连接刷新，不会把另一种 Agent 的命令带入当前会话。

• Pi 会话：保留 Web 内置命令，并动态加入当前 Pi runtime 加载的 extension command、prompt template 与 skill。
• Codex 会话：只展示 Web 明确实现的命令子集，不把终端显示、退出、删除、账号、插件或其他 TUI/宿主专属命令伪装成可用命令。

升级服务后，已经打开或安装的 PWA 必须在出现版本更新提示时刷新，再使用新版斜杠命令。旧页面可以连接新版服务，但不承诺识别新增的界面动作或请求关联语义；斜杠命令的支持边界以页面与服务端版本一致为准。

Codex 当前适配：

命令	Web 行为
/settings、/new、/resume	打开对应 Web 设置或会话界面
/model [model]	无参数打开模型选择；也可设置 model 或 codex/model
/reasoning [level]	无参数打开推理档位；带参数时只接受当前模型支持的档位
/fork、/copy、/diff	打开原生线程分叉、复制最后回复或 Git diff 工作区
/rename <name>	重命名 Codex 草稿或原生线程；兼容旧别名 /name
/status	显示 thread、模型、推理档位、上下文、传输、cwd 与运行/observer 状态；兼容旧别名 /session
/compact	对已存在且空闲的原生 Codex thread 发起 context compaction
/review	默认审查未提交改动；支持 --base <branch>、--commit <sha> 或自定义审查说明

/compact 与 /review 不会为了执行控制命令创建空白 Codex thread。请先在草稿中发送一条真实消息；运行中的任务需先停止，observer 会话需等待取得写权限。只读 observer 仅开放 settings、new、resume、copy、diff 与 status（兼容 /session 别名），不能通过命令、工具栏或直接协议消息修改模型/推理档位、回答审批或启动原生控制操作。这两个命令还要求本机 Codex app-server 支持对应 RPC；旧版不支持时会返回明确错误。未知 Codex 命令会明确报错，不会静默作为自然语言 prompt 发给模型。

常用命令

pi-web-chat status              # 查看 daemon 状态
pi-web-chat stop                # 停止服务
pi-web-chat 3141 restart        # 明确使用生产端口重启
pi-web-chat 3200                # 使用自定义端口
pi-web-chat --lan               # 监听 0.0.0.0，允许局域网访问
pi-web-chat --host 0.0.0.0      # 显式指定监听地址
pi-web-chat --token my-secret   # 指定访问令牌
pi-web-chat rftoken             # 立即轮换访问令牌
pi-web-chat doctor              # 检测 Pi runtime / Pi CLI / Codex CLI

托管 restart 必须显式给出端口，避免过期 daemon 状态把生产服务移动到错误 listener。

兼容 Pi 扩展入口

已有 Pi 工作流无需迁移：

pi install npm:@ryn-mic/web-chat
pi --web
pi --web status
pi --web stop
pi --web 3141 restart

也可以在 Pi 会话中使用扩展命令：

/web
/web 3200
/web --lan
/web status
/web stop
/web restart

独立 CLI、pi --web 与 /web 使用同一套 daemon manager 和 ~/.pi/web-chat/ 状态；任一入口启动的服务都可由另一个入口查询或停止。

从旧版本升级时，launcher 会识别尚未写入 pi-web-chat.instance 的健康 pi --web daemon。只有旧 health、state PID、实际监听 PID 与 Node 服务入口全部 一致时才会停止或重启它；无法证明进程身份时会保留服务和状态并明确报错，不会按 PID 猜测杀进程。下一次成功重启会自动切换到新的实例身份，不需要迁移会话或认证。

daemon 状态文件位于 ~/.pi/web-chat/：

• pi-web-chat.pid
• pi-web-chat.port
• pi-web-chat.host
• pi-web-chat.instance（跨 npm/Pi 安装副本验证同一托管进程）
• pi-web-chat.log

安全与远程访问

首次启动时，服务会自动生成并持久化：

• 访问令牌：~/.pi/web-chat/token
• TOTP 密钥：~/.pi/web-chat/2fa.secret（默认启用）

登录页会提供首次 TOTP 绑定二维码。除健康检查与认证入口外，聊天、会话、文件、Git 等业务 API 与 WebSocket 都需要登录；移动端预览使用短期 capability，文件与 Git 路由仅允许访问 Web Chat 已识别的项目根目录。

[!WARNING] 应用自身不负责 TLS。局域网以外访问时，请使用 Caddy、nginx、Tailscale Serve 等可信反向代理或隧道终止 HTTPS。不要在公网明文 HTTP 上传输令牌或 TOTP 验证码。

变量	默认值	说明
PORT	3141	服务端口
HOST	127.0.0.1	监听地址；仅在可信网络使用 0.0.0.0
PI_WEB_TOKEN	自动生成	访问令牌
PI_WEB_2FA	开启	设为 off 可关闭 TOTP 第二因素
PI_WEB_CWD	~/.pi/web-chat	新会话默认工作目录
PI_WEB_AGENT	pi	新会话默认 Agent：pi 或 codex
PI_WEB_NO_OPEN	未设置	设为 1 时独立 CLI 启动后不自动打开浏览器
PI_WEB_PI_BIN	pi	仅用于检测外部 Pi CLI；不会替换包内 Pi SDK runtime
PI_WEB_CODEX_BIN	codex	Codex 可执行文件路径
PI_WEB_CODEX_MODEL	未设置	可选的默认 Codex 模型 ID；未设置时从原生 model/list 读取
PI_WEB_CODEX_TRANSPORT	auto	auto、proxy 或 standalone
PI_WEB_CODEX_SANDBOX	workspace-write	workspace-write、read-only 或 danger-full-access
PI_WEB_CODEX_APPROVAL	on-request	on-request、untrusted 或 never

Pi 模型认证沿用 ~/.pi/agent/auth.json；请先在 pi CLI 中完成登录或 API Key 配置。Codex 认证由本机 Codex CLI 管理。

若 PI_WEB_PI_BIN 或 PI_WEB_CODEX_BIN 使用相对路径，launcher 会以执行 pi-web-chat 时的当前目录为基准解析一次，再把绝对路径传给后台 daemon，避免 Agent 会话工作目录变化后找不到同一个可执行文件。

开发与发布

工程约束见 AGENTS.md，完整资料入口见 docs/README.md。

npm install
npm run notes:check
npm run typecheck
npm test
npm run build
npm run pack:check
npm pack --dry-run

开发模式默认使用服务端 3141 与 Vite 5173：

npm run dev

如果受保护的本地生产服务已占用 3141，不要同时运行默认 npm run dev；请先停止生产服务，或为调试服务选择其他端口。

生产构建产物为 dist/index.js、dist/cli.js 与 dist/public/，均由 npm run build 生成，请勿直接编辑。

GitHub Actions Release

Release 工作流可以由 v* tag 自动触发，也可以在 Actions → Release → Run workflow 中输入一个已经存在的 tag 手动重跑。流程会：

1. 校验 tag 与 package.json 版本一致，且该提交已包含在 main；
2. 执行安装、类型检查、测试、构建与打包检查；
3. 将 npm tarball 与 SHA-256 校验文件发布到 GitHub Release；
4. 检测 GitHub Actions Secret NPM_TOKEN 是否已配置：已配置时尝试发布到 npm；未配置时跳过 npm，仅保留 GitHub Release。

如果相同 npm 版本已经存在，工作流也会安全跳过重复发布。

普通 commit、分支 push、Pull Request 和 main 合并不会触发发布。不需要重新打包或发布时，不创建/推送 v* tag，也不要手动运行 Release workflow。CI 中的 pack:check 与 npm pack --dry-run 仅验证包是否可构建，不会上传 GitHub Release 或发布 npm。

• Server：Node.js、pi SDK、Codex app-server、WebSocket
• Web：React 19、TanStack Router / Query、Base UI、Tailwind CSS v4、Vite、PWA

bin/pi-web-chat.mjs           npm bin 入口
cli/                          独立命令、Agent 探测与输出适配
extensions/daemon-manager.ts  新旧入口共享的 daemon 生命周期
extensions/pi-web-chat.ts     Pi 兼容入口：--web 与 /web
server/                       HTTP、WebSocket、Pi/Codex 会话、文件与 Git 服务
shared/                       服务端与客户端协议、增量快照
src/                          React 前端
scripts/build.mjs             Vite 前端与 esbuild 服务端/CLI 打包
dist/index.js                 生成的服务端产物
dist/cli.js                   生成的独立 CLI 产物
dist/public/                  生成的前端产物

致谢与许可

本项目从 preinpost/pi-web-chat 演进而来，并在其 pi Web 扩展基础上加入 Codex 原生集成、多会话工作台、安全认证、文件与 Git 能力等持续改进。

项目基于 MIT License 开源。