Remote Codex 0.2.0:一套手机界面同时控制本机 Codex 与 Antigravity

Remote Codex 0.2.0:一套手机界面同时控制本机 Codex 与 Antigravity

💡 原文中文,约9900字,阅读约需24分钟。
📝

内容提要

Remote Codex 0.2.0 通过同一套零依赖 Node.js 桥接服务和手机 PWA,同时接入 Codex app-server 与 Antigravity ACP。它主要解决两类问题:一是将 ACP 阻塞式 session/prompt 转为异步流式轮次,并统一双后端事件与审批隔离;二是针对 Codex 桌面端占用写入锁,采用 thread/read 只读回退、thread/unsubscribe 主动放锁和 thread/fork 自动分叉,实现手机与桌面端无感共存。

🔎

延伸解读

双后端并存的容错设计

文章指出,同时拉起 Codex 与 Antigravity 时使用 Promise.allSettled(),只要任一后端握手成功,HTTP 服务就会正常监听,并在 /api/status 中分别汇报状态。运行中若子进程崩溃或用户事后才完成 agy 登录,每次转发前检查 ready 状态并自动 ensureReady() 重新拉起,并发请求共享启动 Promise 避免重复派生。这种设计降低了单后端故障对整体可用性的影响。

阻塞式 ACP 的异步化处理

Antigravity 的 session/prompt 会一直阻塞到整轮任务结束才返回,若在 HTTP 处理函数中直接 await,单次请求可能挂起数分钟并撞上代理超时。桥接层先在本地生成轮次 ID 并立即返回回执,把真正的 session/prompt 设为无超时在后台等待,期间将流式通知转译为前端增量事件。这样手机端无需区分后端是立即返回还是阻塞返回,停止与审批交互得以复用同一套逻辑。

Codex 写锁冲突的三步兼容

桌面版 ChatGPT.app 会对其加载过的历史会话持有排他锁,手机端调用 thread/resume 抢锁即报 active writer 错误。文章给出的方案是:遇锁自动回退到只读的 thread/read 并标记 writerLocked;离开空闲会话时用 thread/unsubscribe 主动放锁;在锁定会话中继续追问时先重试 resume,仍失败则用 thread/fork 基于原上下文分叉新会话。这样无需杀掉桌面端即可浏览历史并继续对话。

移动端断流恢复的细节

锁屏会冻结后台脚本并断开 SSE 或长轮询。文章将事件缓冲扩至 2000 条,并用 hasGap(cursor) 检测游标断层,返回 truncated 标记;亮屏、重连或收到断层时都会完整刷新当前会话。流式重绘时用 data-item-id 保留折叠卡片展开状态,且仅在滚动条贴近底部时自动滚动,避免用户回看输出时被新内容强行拽回底部。

❓

Q&A

Remote Codex 0.2.0 主要解决了哪两个痛点?

一是工具切换繁琐:日常交替使用 Codex 和 Antigravity 时,无需各跑一个桥接进程、各占端口、各扫二维码,新版在同一进程内同时接入两者。二是 Codex 桌面端共存冲突:电脑后台开着 ChatGPT.app 时,手机打开历史会话会报“already has an active writer”,新版通过协议层处理解决了该锁冲突。

Remote Codex 0.2.0 的整体架构是怎样的?

手机 PWA 通过 HTTPS+JSON+SSE(局域网)或长轮询(Quick Tunnel)连接桥接服务(src/server.mjs)。桥接服务包含 Bearer 配对令牌、方法白名单、命名空间审批表和 EventBuffer(2000),并分别通过 CodexAppServer 和 AntigravityClient 以 stdio JSON-RPC 连接 codex app-server 与 agy acp。项目保持零第三方生产依赖,仅用 Node.js 20+ 内置模块。

Antigravity ACP 的阻塞式 session/prompt 是如何被适配成异步流式轮次的?

src/antigravity-client.mjs 的 prompt() 先在桥接层本地生成轮次 ID,立即发出 turn/started 通知并返回 { turn } 给前端;真正的 session/prompt 设为无超时在后台等待,期间将 session/update 流式通知转译成前端增量事件,等 Promise 落定后再统一触发 turn/completed。这样手机端无需关心后端是立即返回还是阻塞返回,停止按钮和审批弹窗可复用同一套交互逻辑。

双后端同时在线时,审批请求的 ID 冲突是如何解决的?

src/server.mjs 在接入每个后端时,给所有出站通知和审批请求统一包上来源标识,对外暴露的审批 ID 变为 codex:1 和 antigravity:101 等。用户点选后提交到 POST /api/respond,服务端查表拿到对应的 provider 与原始 rawId,再精准写回对应子进程的 stdin。对于 Antigravity 的 session/request_permission,桥接层还会把当前会话的 cwd 和会话名称塞进审批参数,并且只开放 allow_once 与 reject_once 两类单次选项。

手机锁屏后 SSE 断流或长轮询暂停,Remote Codex 是如何恢复同步的?

补上了三处移动端同步细节:1)长轮询游标断层检测:EventBuffer 扩到 2000 条,hasGap(cursor) 检测到游标落后时返回 truncated: true;2)亮屏与断层自动重拉当前会话:visibilitychange、SSE 断线重连或收到 truncated 时,前端调用 refreshCurrentThread() 对齐当前会话;3)流式刷新保留折叠状态与阅读位置:renderMessages() 用 data-item-id 记住展开的 details 卡片,且仅在滚动条贴近底部(<150px)时才自动滚到底。

Codex 报“already has an active writer”的原因是什么?Remote Codex 如何实现无感共存?

原因是 macOS 后台常驻的桌面版 ChatGPT.app 拉起了自带的 codex app-server 子进程,并对 30 多条历史会话的 .lock 文件持有排他锁;手机端 openThread() 调用 thread/resume 会去抢写入锁,撞上桌面端持有的锁就报错。Remote Codex 利用 thread/read(只读回退)、thread/unsubscribe(主动放锁)和 thread/fork(自动分叉)三个原语实现三步无感兼容:遇锁自动退回只读并标记 writerLocked;离开空闲会话主动放锁;在 writerLocked 会话中发送新消息时先重试 resume,若锁还在则自动 fork 出新会话继续。

如何快速上手 Remote Codex 0.2.0?有哪些使用边界?

要求本机安装 Node.js 20+,并至少装好 codex 或 agy 其中之一。克隆仓库后,同一 Wi-Fi 下运行 npm run lan;出门在外可 brew install cloudflared 后运行 npm run remote -- --allowed-mail you@example.com 通过 Cloudflare 临时 HTTPS 隧道连接。首次配合 Antigravity 需先在终端完成 agy acp --login。使用边界:Antigravity 目前走 agy acp 命令行协议通道,适合从手机发起新任务或续接 ACP 会话,若想接管桌面窗口图形界面会话可开启官方 Google Remote Control;项目保持单人轻量工具定位,配对二维码和 #token=... 链接本身就是完整控制凭据,用完按 Ctrl+C 即可收回所有外部入口。

🏷️

标签

➡️

继续阅读