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

上一篇《我怎样设计 Remote Codex:从手机远程控制本机 Codex》发出来后,我自己连着两周在手机上用它看任务和点审批,很快撞上了两个非常具体的问题。

第一个问题是工具切换。日常写代码时,我经常在同一台 Mac 上交替使用 OpenAI 的 Codex 和 Google 的 Antigravity(命令行工具 agy)。如果给两边各跑一个桥接进程、各占一个端口、各扫一次配对二维码,在手机主屏幕上来回切两个图标会很繁琐。

第二个问题出在 Codex 桌面端共存上。只要电脑后台开着 ChatGPT.app,在手机上点开列表里的历史会话,几乎每条都会弹出报错:thread <id> already has an active writer。明明电脑上没有任何任务在跑,手机上却连历史对话都打不开。

围绕这两个痛点,我把项目升级到了 0.2.0 并整理开源在 GitHub(Nicksxs/remoteCodex,MIT 许可证)。新版默认在同一个进程里同时接入 codex app-server 与 agy acp,并在协议层处理了桌面端文件锁冲突、手机锁屏断流恢复以及双后端并发审批。这篇文章基于 0.2.0 源码(状态截至 2026 年 11 月 22 日),把这次改造中踩到的协议差异与实际排障过程拆开讲清楚。

抽出共用 StdioRpcClient 与双后端并存架构

Codex CLI 的 codex app-server 与 Antigravity CLI 的 agy acp(Agent Client Protocol)底层通信方式很接近:都由外部宿主拉起子进程,通过标准输入输出(stdio)收发按行分隔的 JSON-RPC 消息。把原来的单后端结构拆开后,0.2.0 的整体分层变成了下面这样:

1
2
3
4
5
6
7
8
9
10
手机 PWA(public/app.js)
│ 统一会话视图(全部 / Codex / Antigravity)
│ HTTPS + JSON + SSE(局域网)/ 长轮询(Quick Tunnel)
▼
Remote Codex 桥接服务(src/server.mjs)
│ Bearer 配对令牌 · 方法白名单 · 命名空间审批表 · EventBuffer(2000)
├──▶ CodexAppServer(src/codex-client.mjs)
│ └── stdio JSON-RPC ──▶ codex app-server
└──▶ AntigravityClient(src/antigravity-client.mjs)
└── stdio JSON-RPC 2.0 ──▶ agy acp

仓库依然保持零第三方生产依赖,只用 Node.js 20+ 内置模块完成进程管理、加密鉴权与 HTTP 服务。新增和重构后的核心模块分工如下:

文件职责
src/stdio-rpc.mjs通用的子进程 stdio 行分隔双向 JSON-RPC 客户端,统一管理请求超时、通知分发与退出清理
src/codex-client.mjs继承 StdioRpcClient,封装 codex app-server 握手与进程退出后的按需自愈
src/antigravity-client.mjs将 ACP v1 的会话、流式片段、思考过程、执行计划与单次权限审批适配为前端统一模型
src/event-buffer.mjs维护最近 2000 条带序号事件,提供 hasGap() 游标断层检测,同时支撑 SSE 与长轮询
src/server.mjs同时管理多个本地 Agent 实例,按 provider 路由 RPC、打标事件并隔离待审批请求

抽公共传输层时有一个容易忽略的帧格式差异:codex app-server 不强制要求顶层携带 "jsonrpc": "2.0" 字段,而 agy acp 遵循标准 JSON-RPC 2.0 校验,缺了这个字段会直接判为非法帧。StdioRpcClient 通过构造参数 jsonrpc: true 按需注入该字段,两边就能共用同一套缓冲区切行、请求映射和异常收敛逻辑。

默认执行 npm start、npm run lan 或 npm run remote 时,src/server.mjs 会用 Promise.allSettled() 并发拉起两个后端。很多人的电脑上可能只装了其中一个命令行工具,或者 agy 还没完成首次登录,所以双端模式下只要有任意一个后端握手成功,HTTP 服务就会正常监听,并在 /api/status 中按后端分别汇报状态:

1
2
3
4
5
6
7
{
"provider": "all",
"providers": {
"codex": { "enabled": true, "ready": true, "error": null },
"antigravity": { "enabled": true, "ready": false, "error": "找不到 agy..." }
}
}

如果运行途中某个子进程意外崩溃,或者用户启动服务后才在终端补做完 agy acp --login,也不用重启桥接服务。每次 /api/rpc 转发前都会检查目标客户端的 ready 状态,未就绪时自动调用 ensureReady() 重新拉起子进程并完成握手(并发请求共享同一个启动 Promise,避免重复派生进程)。

把阻塞式 ACP 会话翻译成异步流式轮次

虽然底层都跑在 JSON-RPC 上,但 codex app-server 和 Antigravity ACP v1 对“会话”与“执行轮次”的协议建模差别很大。两边的核心方法对照如下:

交互环节Codex app-serverAntigravity agy acp
握手协商initialize + initialized 通知initialize(声明 protocolVersion: 1)
列举历史会话thread/listsession/list(需检查 sessionCapabilities.list)
新建会话thread/startsession/new(传入绝对路径 cwd 与 mcpServers: [])
恢复历史记录thread/resume / thread/read 直接返回结构化 turnssession/load 通过一串 session/update 通知回放历史
发送用户消息turn/start 立即返回 turn 回执session/prompt 一直阻塞到整轮任务结束才返回 stopReason
停止当前任务turn/interrupt 请求session/cancel 单向通知
工具权限审批item/commandExecution/requestApproval 等session/request_permission 请求

这里最关键的差异在发送消息这一步。浏览器调用 /api/rpc 发起 turn/start 时,期望尽快拿到响应解锁发送按钮,随后在漫长的代码修改和测试运行期间随时点“停止”或点“允许执行”。而 ACP 规范里的 session/prompt 是一次长生命周期调用:直到模型真正答完(end_turn)、被取消(cancelled)或拒绝回答(refusal),这条 RPC 才会返回结果。Antigravity CLI ACP 文档

如果在 HTTP 处理函数里直接 await 这条 session/prompt,单次请求动辄挂起几分钟,既容易撞上代理层超时,也会让前端状态机和 Codex 路径分叉。src/antigravity-client.mjs 在 prompt() 里把“返回 HTTP 回执”和“等待 ACP 轮次结束”拆成了两步:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const turn = { id: randomUUID(), status: "inProgress" };
session.active = turn;
session.prompted = true;
session.cancelRequested = false;
const item = { id: randomUUID(), type: "userMessage", content: prompt };
session.items.push(item);
session.preview ||= prompt[0].text.slice(0, 120);
this.notify("turn/started", { threadId: session.id, turn });
this.notify("item/started", { threadId: session.id, item });

this.call("session/prompt", { sessionId: session.id, prompt }, null).then(
({ stopReason } = {}) => {
const [status, reason] = STOP_OUTCOMES[stopReason] || ["failed", `Antigravity 已停止(${stopReason || "unknown"})`];
this.finish(session, status, reason);
},
(error) => this.finish(session, "failed", error.message),
);
return { turn };

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

把 agy acp 真正接进日常使用后,还顺手填平了四个协议细节坑:

  1. 思考过程与执行计划映射:Antigravity 在动手改代码前经常先发一段较长的内部推理和步骤规划。如果只处理 agent_message_chunk,手机屏幕会干等十几秒没有任何动静。update() 额外接入了 agent_thought_chunk 和 plan 两类事件,分别映射为前端现成的“思考过程”与“执行计划”折叠卡片,工具调用(tool_call / tool_call_update)则按 toolCallId 原地合并标题、输入参数与执行状态。
  2. 原子化历史回放与无标题预览:ACP 的 session/load 调用期间会密集推回一串 user_message_chunk 和 agent_message_chunk 通知来重放对话,响应体本身并不直接携带消息数组。load() 先把回放期间收到的条目写进临时数组 session.replaying,等 session/load 成功后一次性赋给 session.items,防止中途报错留下半截脏数据;同时从首条用户消息提取前 120 个字符填入 session.preview,避免还没生成标题的历史会话在列表里全部显示成“未命名会话”。
  3. 新会话兜底标记与分页错位:刚调完 session/new、还没发第一条消息的会话,有时不会立刻出现在 session/list 里,桥接层用 session.created = true 把它暂存在第一页顶部。一旦后续 session/list 返回了这条会话,必须立刻把 session.created 清零;否则等这条旧会话以后掉到第二页,第一页看它不在本页列表里,又会把它错误置顶回来。另外 session/list 返回的 ISO 时间戳往往只精确到秒,而本地 Date.now() / 1000 带毫秒小数,比对标题更新时间时要先对本地时间戳向下取整(Math.floor(session.updatedAt)),否则服务端刚生成的会话标题会被本地毫秒差挡在外面写不进去。
  4. 子进程重启后的上下文续接:agy acp 进程一旦退出重连,新进程内存里并没有之前打开过的会话状态。exit 事件监听器会把已有会话的 loaded 置回 false,保留 everLoaded: true;下次用户在手机上直接发消息时,prompt() 检测到该会话曾经加载过,就会先自动调一次 session/load 把历史上下文装回新进程,再继续发送本轮提问。

双端事件复用、审批隔离与锁屏重连同步

两个后端同时在线跑任务时,事件流和待审批表如果混在一起,立刻就会撞上 ID 冲突。比如 codex app-server 和 agy acp 各自从 1 开始给服务端请求编号,两边同时停下来等用户点确认时,裸 id: 1 就会互相覆盖。

src/server.mjs 在接入每个后端时,给所有出站通知和审批请求统一包上了来源标识:

1
2
3
4
5
6
7
client.on("notification", (message) => publish("notification", { provider: name, ...message }));
client.on("serverRequest", (message) => {
const publicId = `${name}:${message.id}`;
const wrapped = { ...message, id: publicId, provider: name };
pendingServerRequests.set(publicId, { provider: name, rawId: message.id, message: wrapped });
publish("serverRequest", wrapped);
});

对外暴露给手机端的审批 ID 变成了 codex:1 和 antigravity:101。用户点选后提交到 POST /api/respond,服务端查表拿到对应的 provider 与原始 rawId,再精准写回对应子进程的 stdin。对于 Antigravity 的 session/request_permission 请求,桥接层还会把当前会话的 cwd(工作目录)和会话名称一并塞进审批参数,并且在手机端只开放 allow_once(本次允许)与 reject_once(本次拒绝)两类单次选项,同时把“本次拒绝”(让模型换方案重试)和“取消本轮”(发送 cancelled 终止当前审批)拆成不同样式的按钮,避免在手机小屏幕上误触。

手机远程控制还有一个绕不开的物理场景:发完一条长任务后顺手按灭屏幕揣进兜里,过两分钟再亮屏看结果。iOS Safari 和 Android Chrome 在锁屏期间会冻结后台脚本、断开 SSE 或暂停长轮询,这里补上了三处针对移动端的同步细节:

  • 长轮询游标断层检测:一段稍长的代码生成很容易吐出上千个文本 delta。src/event-buffer.mjs 将环形缓冲上限扩到 2000 条,并新增了 hasGap(cursor) 方法:一旦客户端传来的 after 游标小于缓冲区现存最早一条事件的前序编号,/api/events/poll 就会附带返回 truncated: true。
  • 亮屏与断层自动重拉当前会话:之前切回前台(visibilitychange)只刷新了会话列表,没刷新当前正打开的聊天窗口,容易导致界面一直卡在“正在工作”。现在无论是亮屏恢复、SSE 断线重连还是收到 truncated: true,前端都会同时调用 refreshCurrentThread() 把当前打开的会话完整对齐一遍。
  • 流式刷新保留折叠状态与阅读位置:流式输出期间每收到一个字符增量都会更新消息列表。renderMessages() 改用 data-item-id 记住用户当前点开了哪些 <details> 思考或工具卡片,重绘后原样恢复展开状态;同时只在滚动条原本就贴近底部(距离底部小于 150px)时才自动滚到底,往回翻看上文命令输出时不再被新吐出的文字强行拽回底部。

排查并解决 Codex 的 already has an active writer 锁冲突

回到开头提到的那个怪现象:电脑上明明没有任务在跑,为什么手机一点开 Codex 历史会话就报 already has an active writer?

在终端里用 lsof 查一下 ~/.codex/thread-writer-locks/*.lock 目录,原因马上就清楚了:

1
lsof ~/.codex/thread-writer-locks/*.lock

输出显示,macOS 后台常驻的桌面版 ChatGPT.app 拉起了它自带的 codex app-server 子进程(0.167+ 版本),并且同时对 30 多条历史会话的 .lock 文件持有排他锁。为了防止多客户端同时往同一个会话记录文件里写数据造成损坏,新版 Codex 严格执行单写者(Single-Writer)约束:桌面客户端只要加载或浏览过某条会话,哪怕当前完全空闲,也会一直占着这把写入锁,直到彻底退出桌面应用才释放。

问题就出在手机端打开会话的动作上。原先 openThread() 一点进会话就调用 thread/resume。在 codex app-server 的协议语义里,thread/resume 代表“我要作为活跃写者接管这条会话”,一上来就会去抢 .lock 文件锁,撞上桌面端持有的锁自然直接报 -32600 错误,连历史消息都读不出来。

用 codex app-server generate-ts 导出官方协议定义核对后可以看到,app-server 其实专门提供了不抢写入锁的只读接口 thread/read(支持传入 includeTurns: true 一次性读回全部历史轮次与工具记录)、主动释放订阅锁的 thread/unsubscribe,以及从磁盘历史分叉新会话的 thread/fork。

利用这三个原语,public/app.js 做了一套三步无感兼容,不需要每次为了看手机去杀掉桌面端 ChatGPT.app:

1
2
3
4
5
6
7
8
9
10
11
12
async function fetchThread(thread) {
await releaseCodexWriter(thread.id);
try {
const result = await rpc("thread/resume", { threadId: thread.id }, "codex");
state.subscribedCodexThreadId = thread.id;
return { result, writerLocked: false, provider: "codex" };
} catch (error) {
if (!isActiveWriterError(error)) throw error;
const result = await rpc("thread/read", { threadId: thread.id, includeTurns: true }, "codex");
return { result, writerLocked: true, provider: "codex" };
}
}

整套流转逻辑如下:

  1. 点开会话遇锁自动退回只读:优先尝试 thread/resume;一旦捕获到 already has an active writer,立即回退调用 thread/read(includeTurns: true),把完整历史对话和命令输出渲染出来,同时把当前视图标记为 writerLocked = true,输入框底部提示“电脑端正占用此会话,发送将自动分叉继续”。
  2. 离开空闲会话主动放锁:记录当前桥接进程自己持锁的 subscribedCodexThreadId。每当用户切去别的会话、新建会话或断开连接时,只要旧会话没有正在跑的任务,releaseCodexWriter() 就会调用 thread/unsubscribe 把锁还回去,避免手机桥接层自己变成占着茅坑的锁持有者。
  3. 继续追问时自动分叉(Fork):当用户在一条 writerLocked 会话里输入新要求点发送时,先重试一次 thread/resume(万一这期间桌面端已经关掉了就能直接续写);如果锁还在,自动调用 thread/fork 基于原会话完整上下文派生出一条拥有全新 ID 的新会话,平滑切换当前会话指针并立即执行 turn/start。

这样改完之后,桌面开着 ChatGPT.app 时手机端翻阅任何历史记录都毫无阻碍;真正在手机上接着往下聊时,也会在保留全部前文的前提下干净地分出新分支,不会去动桌面端正占用的记录文件。

快速上手与使用边界

项目代码已完整推送至 GitHub 仓库 https://github.com/Nicksxs/remoteCodex,要求本机安装 Node.js 20+,并至少装好 codex 或 agy 其中之一:

1
2
3
4
5
6
7
8
9
git clone https://github.com/Nicksxs/remoteCodex.git
cd remoteCodex

# 同一 Wi-Fi 下使用(默认同时连接本机 Codex 与 Antigravity)
npm run lan

# 出门在外通过 Cloudflare 临时 HTTPS 隧道连接,并加上邮箱验证码保护
brew install cloudflared
npm run remote -- --allowed-mail you@example.com

首次配合 Antigravity 使用前,先在电脑终端确认 agy acp --help 可用并完成登录;如果只想单独挂某一个后端,也可以传 --agent codex 或 --agent antigravity。仓库自带不依赖真实大模型的假后端(test-support/fake-app-server.mjs 与 test-support/fake-antigravity.mjs),修改协议逻辑后跑一遍 npm run check 就能在几百毫秒内验完双端路由、游标断层、进程崩溃重连与锁冲突分叉共 20 项测试。

这套方案有两处明确的使用边界:Antigravity 目前走的是 agy acp 命令行协议通道,适合从手机发起新任务或续接 ACP 会话;如果你希望直接接管电脑上 Antigravity.app 桌面窗口里正在交互的图形界面会话,可以直接开启官方提供的 Google Remote Control。此外,Remote Codex 保持单人轻量工具定位,配对二维码和 #token=... 链接本身就是完整控制凭据,用完回到电脑前按 Ctrl+C 即可收回所有外部入口。