Codex Pilot 外部版

外部版完整部署教程

从零部署手机、Mac、Windows 和多电脑联动。适用版本 3.88-external。

返回下载页继续看使用教程

1. 安装准备

部署包不会预置任何内部地址或口令。每台电脑首次安装都会在本机生成独立 token。

2. AI 自部署

外部电脑上如果有能操作本机终端的 AI 助手，可以让它运行公开 bootstrap 脚本。脚本会读取公开版本信息、下载最新版完整部署包、校验 SHA256、解压、执行安装或修复、启动服务并打开扫码页。

AI 自部署提示词复制给外部电脑 AI，让它按标准流程执行 Windows Bootstrap自动下载并安装或修复 Windows 电脑端 Mac Bootstrap自动下载并安装 Mac 电脑端

Windows 手动启动

$p = Join-Path $env:TEMP "bootstrap-windows.ps1"
Invoke-WebRequest "https://pilot.qiliuai.com/bootstrap-windows.ps1" -OutFile $p -UseBasicParsing
powershell -NoProfile -ExecutionPolicy Bypass -File $p

Mac 手动启动

cd /tmp
curl -fL "https://pilot.qiliuai.com/bootstrap-mac.command" -o bootstrap-mac.command
chmod +x bootstrap-mac.command
./bootstrap-mac.command
Windows 管理员授权、macOS 屏幕录制/辅助功能权限、Codex 登录、Tailscale 登录和手机扫码仍需要用户确认。AI 不应把 token 或私有地址发到公开聊天里。

3. 部署 Mac

解压完整部署包
不要直接在压缩包预览器里运行文件。
运行安装
双击 install-mac.command。如系统阻止，右键选择“打开”。
记录连接信息
脚本会显示电脑地址、访问口令和工作包目录，并保存到 ~/.codex-pilot/mobile-control/connection-info.txt。
验证
双击 verify-mac.command，确认服务、工作包和 Codex 启动文件正常。
手机电脑地址：https://电脑域名
访问口令：每台电脑独立生成的随机字符串

4. 部署 Windows

双击一键安装
运行 install-windows.cmd，在 Windows 提示时允许管理员权限。安装器会自动放行端口、注册自启并打开扫码页面。

PowerShell 备用安装方式：

powershell -ExecutionPolicy Bypass -File .\install-windows.ps1

安装脚本会复制服务、生成 token、创建工作包目录、注册登录自启、尝试放行 TCP 8787 并启动服务。

验证：

powershell -ExecutionPolicy Bypass -File .\verify-windows.ps1

连接信息保存在 %USERPROFILE%\.codex-pilot\mobile-control\connection-info.txt。

提示找不到 Python 时，先安装 Python 3 并勾选“Add Python to PATH”，然后重新运行安装脚本。

修复旧 Windows 节点

如果手机显示某台 Windows 为“需升级”，或者点“升级电脑端”后服务版本仍不变化，在那台 Windows 上解压新版完整部署包并运行：

powershell -ExecutionPolicy Bypass -File .\repair-windows.ps1

普通客户也可以直接双击 repair-windows.cmd。修复脚本会保留本机 token 和历史数据，覆盖当前服务文件，修正登录自启启动路径，放行 8787 端口并重启服务。完成后再运行 verify-windows.ps1，确认服务版本和远程观看/远程输入能力。

5. 安装手机 App

  1. 安装 app/ 目录里版本号最新的外部版 APK。
  2. 首次启动时允许通知权限；使用扫码连接时允许相机权限。
  3. 打开 App，进入“电脑 / 当前连接”。
  4. 手动填写电脑地址和 token，或使用下面的扫码方式。
  5. 点“保存并连接”，等待电脑在线和工作包数量出现。

扫码连接

新版安装器会自动打开扫码页面，然后在手机 App 点“扫码连接”扫描页面二维码。二维码由电脑本机生成，不经过第三方服务。

二维码使用 10 分钟有效的一次性配对码，不包含长期 token；配对成功后立即失效。过期或扫码失败时刷新页面即可重新生成。

页面未自动打开时，在电脑浏览器访问 http://127.0.0.1:8787/connect。

客户版只接受 HTTPS 地址，或 Tailscale 的 100.64.0.0/10 加密专网地址。电脑地址不要带 /api/bootstrap 或 ?token=。token 输入框只填随机字符串。

6. 多电脑与异地连接

多电脑

每台电脑分别运行安装脚本，然后在 App 的电脑管理页面逐台添加名称、地址和该电脑自己的 token。添加后先运行节点诊断。

异地连接

  1. 手机和电脑安装 Tailscale。
  2. 加入同一个网络或共享设备。
  3. 在 App 填写电脑 Tailscale 地址，例如 http://100.x.x.x:8787。
不要把 8787 端口直接暴露到公网。客户版仅允许 HTTPS，或 Tailscale 专网地址。

7. 完整验收

只看到端口在线或节点在线不算完整验收。必须至少发送一条真实任务并收到 Codex 最终回复。

8. 升级

手机直接覆盖安装新版 APK。电脑下载新版完整部署包，再次运行对应安装脚本；工作包登记、任务历史和 token 会保留。

ChatGPT/Codex 更新后，Mac 服务会自动寻找新旧安装位置。出现启动路径错误时，重新运行安装脚本并验证。

云端中转

部署包的 cloud-relay/ 可用 Docker 运行。设置 CODEX_RELAY_TOKEN 后执行 docker compose up -d --build，再在 App 中填写中转 HTTPS 地址和口令。

9. 故障排查

连接失败

先运行电脑验证脚本，再检查地址、token、Wi-Fi、Tailscale 和防火墙。

一直排队

进入任务中心取消疑似卡住任务，运行节点诊断，并确认电脑 Codex 可以正常发送普通消息。

工作包不同步

电脑已有目录但手机没有时，先在 Codex 打开目录并创建一次对话；手机新建后电脑没有时，刷新 Codex 侧栏并重启一次 Codex。

Windows 防火墙

New-NetFirewallRule -DisplayName "Codex Pilot 8787" -Direction Inbound -Protocol TCP -LocalPort 8787 -Action Allow

10. 安全和卸载