codex-app-remotely

远程操作你电脑上的 Codex.app。这个项目会以受控方式启动本机 Codex Electron App，开启 Electron 的 Chrome DevTools Protocol，然后把画面和输入事件转发到移动端 Web 页面。

截图

要求

• Node.js 22+
• macOS 或 Windows 上的 Codex Electron App
• 使用 remote 模式时需要 Cloudflare Workers + Durable Objects

安装和使用

无需安装即可运行：

npx codex-app-remotely

也可以全局安装 CLI：

npm install -g codex-app-remotely

安装后使用：

car

服务启动后会输出一个带 token 的访问 URL，并在终端显示该链接的二维码，手机扫码或在浏览器打开链接即可。

默认从 9222 开始自动选择一个空闲 CDP 端口。如果 9222 已经被 Chrome 或其他程序占用，服务会自动切到下一个可用端口。

通过 Cloudflare 的 remote 模式

remote 模式通过 Cloudflare Worker 中继访问。先部署项目内置 Worker：

npx codex-app-remotely deploy

这个命令会使用包内置的 wrangler.toml、worker/ 和 public/ 执行 Wrangler 部署。需要传 Wrangler deploy 参数时，直接跟在 deploy 后面，例如 npx codex-app-remotely deploy --env production。

然后以 remote 模式启动本机 host：

car --mode remote --remote-url "https://codex-app-remotely-remote.<account>.workers.dev"

如果通过 npm scripts 启动，需要使用 npm 的 -- 分隔符；也可以使用已支持的位置参数简写：

npm run start -- --mode remote --remote-url "https://codex-app-remotely-remote.<account>.workers.dev"
npm run start remote "https://codex-app-remotely-remote.<account>.workers.dev"

CLI 会输出带 room 和 token 的远端 URL，手机浏览器打开或扫码即可。如果 URL 没有 room，两端都会使用 default。本机进程会向 /ws/host 建立出站 WebSocket；远端浏览器使用 /ws/control 和 /ws/frame；每个 room 对应一个 Durable Object，用来中继控制 JSON 和二进制画面帧。

debugger 模式

debugger 模式会启动或连接 Codex，并为选中的 Codex target 打开 DevTools：

car debugger

等价写法：

car --mode debugger
car --open-devtools

如果由本工具启动 Codex，这个模式还会追加 --auto-open-devtools-for-tabs。如果连接的是已经启动的 Codex 进程，则会在默认浏览器里打开 CDP DevTools frontend：

car debugger --no-launch --cdp-port 9222

指定 Codex App 路径

如果 Codex app 不在默认位置，可以显式指定路径。macOS 上可以传 .app bundle：

npx codex-app-remotely --app "/Applications/Codex.app"

全局安装后等价写法：

car --app "/Applications/Codex.app"

Windows 上可以传安装目录或可执行文件路径：

npx codex-app-remotely --app "$env:LOCALAPPDATA\Programs\Codex"
npx codex-app-remotely --executable "$env:LOCALAPPDATA\Programs\Codex\Codex.exe"

默认情况下，Windows 自动启动会检查常见 Electron 安装路径，包括 %LOCALAPPDATA%\Programs\Codex\Codex.exe 和 %LOCALAPPDATA%\Programs\OpenAI Codex\OpenAI Codex.exe。

连接已启动的 Codex

如果你已经手动启动了 Codex 并开启 CDP：

npx codex-app-remotely --no-launch --cdp-port 9222

全局安装后等价写法：

car --no-launch --cdp-port 9222

手动启动 Electron CDP 的参数形式通常是：

"/Applications/Codex.app/Contents/MacOS/Codex" \
  --remote-debugging-port=9222 \
  --remote-allow-origins=* \
  --disable-renderer-backgrounding \
  --disable-background-timer-throttling \
  --disable-backgrounding-occluded-windows

Windows 上：

& "$env:LOCALAPPDATA\Programs\Codex\Codex.exe" `
  --remote-debugging-port=9222 `
  --remote-allow-origins=* `
  --disable-renderer-backgrounding `
  --disable-background-timer-throttling `
  --disable-backgrounding-occluded-windows

常用配置

car \
  --host 0.0.0.0 \
  --port 3147 \
  --mode remote \
  --remote-url https://codex-app-remotely-remote.<account>.workers.dev \
  --cdp-port 9333 \
  --screencast-every-nth-frame 1 \
  --screenshot-max-width 1440 \
  --screenshot-max-height 900 \
  --screenshot-quality 74

也可以使用环境变量：

• CODEX_APP_PATH
• CODEX_EXECUTABLE
• CDP_HOST
• CDP_PORT
• HOST
• PORT
• REMOTE_TOKEN
• REMOTE_MODE
• REMOTE_WORKER_URL
• REMOTE_ROOM
• SCREENCAST_EVERY_NTH_FRAME
• SCREENSHOT_MAX_WIDTH
• SCREENSHOT_MAX_HEIGHT
• SCREENSHOT_QUALITY
• OPEN_DEVTOOLS=1
• CODEX_DEBUGGER=1
• NO_LAUNCH=1

架构

• src/server.js：入口，编排启动器、CDP 桥和移动端 WebSocket。
• src/codexLauncher.js：定位并启动 Codex Electron App，注入 --remote-debugging-port。
• src/cdpClient.js：连接 CDP target，收到 Page.screencastFrame 后立即 ACK，动态切换 JPEG screencast 档位，并把点击、指针、滚动、文字、按键转换为 CDP Input 命令。
• src/mobileWsServer.js：零依赖 WebSocket 服务端，使用独立控制/画面通道，并按“只保留最新帧”的方式推送二进制画面。
• src/remoteRelayClient.js：remote 模式下连接 Cloudflare 的本机出站 WebSocket host。
• src/staticServer.js：静态页面和少量状态 API。
• src/workerDeploy.js：部署内置 Cloudflare Worker 中继的命令封装。
• worker/index.js：Cloudflare Worker + Durable Object 远端 room 中继。
• public/：移动端控制页面。

安全说明

CDP 拥有很高权限，本项目不会直接暴露 CDP 端口；移动端只连接本地 WebSocket 服务或 Cloudflare 中继。移动端连接需要启动时生成的一次性 token。remote 模式下，拿到完整远端 URL 的人都可以在本机 host 运行期间控制应用，请把该 URL 当作密钥处理。由本服务自动启动的 Codex app 会在服务关闭时一同退出；使用 --no-launch 连接手动启动的 Codex 时，本服务不会关闭该外部进程。