Codex Pilot

完整部署教程

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

1. 安装准备

部署包不会预置任何内部地址或口令。每台电脑首次安装都会在本机生成独立 token。
Mac 的“屏幕录制”权限是远程画面的硬前提,没有它手机只能看到壁纸和菜单栏。这个授权必须在电脑上由本人点击确认,远程或脚本都无法代替。

2. AI 自部署

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

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 登录和手机扫码仍需要用户确认(Tailscale 软件本身由安装脚本代装,但登录只能你本人来)。AI 不应把 token 或私有地址发到公开聊天里。

3. 部署 Mac

解压完整部署包
不要直接在压缩包预览器里运行文件。
运行安装
双击 install-mac.command。如系统阻止,右键选择“打开”。
授予屏幕录制权限
打开“系统设置 → 隐私与安全性 → 屏幕录制”,把安装脚本提到的 Codex Pilot 电脑端服务打勾。这一步不做,手机上的远程画面只能看到桌面壁纸。
记录连接信息
脚本会显示电脑地址、访问口令和工作包目录,并保存到 ~/.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,确认服务版本,以及远程画面与远程操作的可用状态。

Windows 端的远程画面由电脑端服务自己采集和编码,不需要额外装程序。如果手机点“进入桌面”时提示“这台电脑端版本太旧,暂不支持远程控制 Codex 的实时画面”,说明这台 Windows 上跑的还是旧版服务,运行 repair-windows.ps1 升级后即可。

5. 安装手机 App

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

扫码连接

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

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

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

客户版只接受 HTTPS 地址、局域网私有地址(10. / 172.16-31. / 192.168.),或 Tailscale 的 100.64.0.0/10 加密专网地址。电脑地址不要带 /api/bootstrap 或 ?token=。token 输入框只填随机字符串。

装完之后:要让手机能出图,先绑做图密钥

App 底部「AI电商图」是手机端出电商图的地方,用的是你启流账号下的额度(和官网出图同一份额度,按张扣费,没有免费额度)。第一次进去要在页面上绑一把「做图密钥」:名下已经有用在做图分组的密钥就直接点一把;没有就点「一键创建做图密钥」,App 会按默认的「生图分组」替你建一把。绑完卡片显示「已绑定 · 密钥名」。

这一步不需要在电脑上做任何事,也不影响远程画面和工作包任务。账号余额不足时出图会失败,充值入口在 App 的「我的」页。完整说明见使用教程第 13 节。

6. 多电脑与异地连接

多电脑

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

异地连接(方式一:专属接入地址,推荐)

同一个 Wi-Fi 下用局域网地址即可,不需要做任何额外设置。人不在同一个网络里(出差、用 4G)时,如果你的账号已经开通了专属接入,这是最省事的一条路:不用装任何第三方软件,也不需要你自己做任何网络配置。

  1. 拿到两项信息。一个专属网址(https:// 开头),和一串连接器令牌。这两项由我们单独发给你。
  2. 填进部署包。打开 tunnel/access-info.txt,把网址填在 ADDRESS= 后面、把令牌填在 TOKEN= 后面,保存。
  3. 运行接入脚本。Windows:以管理员身份运行 tunnel\windows\install.cmd;macOS:双击 tunnel/macos/install.command。
  4. 确认成功。脚本最后会自动自检,看到下面两句就成功了:
    接入完成,专属地址已通(HTTP 401:隧道正常且在要求令牌)
    安全检查:公网 /connect 已封(HTTP 403),符合预期
    手机 App 连接页填那个专属网址即可,手机端不用装任何东西。连接器会开机自动运行。
自检返回 530 = 连接器没在跑(重跑接入脚本);返回 502 = 刚掉线,等一分钟再试。两者都不是「配置没生效」。
安装脚本还会顺手把 Tailscale 也装好当备选通道。只用方式一的话,看到「Tailscale 未安装 / 还没登录」这类提示可以忽略,不影响使用。
这个专属网址本身就是钥匙(域名里那 12 位是随机生成的),不要外传;一旦泄露请联系我们换一条。
接入脚本已经替你封掉了会泄露配对码的 /connect 页面:curl -s -o /dev/null -w "%{http_code}" https://你的网址/connect 必须是 403;若返回 200,立刻联系我们。电脑本机的 http://127.0.0.1:8787/connect 返回 200 是正常的。
专属接入连接器只对这一台电脑有效,令牌等同于密码:不要发到公开网盘或聊天群,不要截图外发。不再使用时,请在该目录里运行卸载脚本,并通知我们吊销。

异地连接(方式二:Tailscale,需要自己注册账号)

如果手上没有专属接入,也可以自己用 Tailscale,让手机能直接到达那台电脑。客户版为此认三条路:HTTPS 域名、局域网私有地址,或 Tailscale 的 100.64.0.0/10 专网地址。

  1. 电脑端已经在安装脚本里自动装好了。Windows 是全静默安装;macOS 装完需要你在“系统设置 → 通用 → 登录项与扩展”里允许它的系统扩展。
  2. 登录 Tailscale。两条路任选:
    • 手动:点菜单栏 / 开始菜单里的 Tailscale,点 Log in,在浏览器里完成登录。
    • 一步到位:在 login.tailscale.com/admin/settings/keys 生成一个 auth key(勾 Preauthorized、可复用、可设过期),然后重跑安装脚本并带上它:
      ./install-mac.command --tailscale-authkey=tskey-auth-xxxxxxxx
      .\install-windows.ps1 -TailscaleAuthKey tskey-auth-xxxxxxxx
      这条会直接加入网络,不再需要点浏览器。auth key 是凭据,用完请自行撤销,不要写进任何文件。
  3. 手机上也要装 Tailscale,并登录同一个账号(或者由管理员把电脑共享给你)。中国大陆用官方 APK 直链,不要用 Google Play:
    https://pkgs.tailscale.com/stable/tailscale-android-universal-latest.apk
  4. 登录完成后重跑一次电脑端安装脚本(或 verify 脚本),它会打印出本机的 Tailscale 地址,并写进 connection-info.txt。在 App 里填写 http://100.x.x.x:8787 即可。
不要把 8787 端口直接暴露到公网。电脑端 /connect 页面如果显示的是 192.168.x.x 这类局域网地址,说明 Tailscale 那一步还没做完 —— 页面会给出提示。

7. 完整验收

远程画面单独验收

  1. 底部点“远程”,确认列表里能看到这台电脑,标题下方显示“在线 N/M”。
  2. 点“进入桌面 ›”,等待画面出现。
  3. 确认画面里能看到电脑上真实的窗口;如果只看到壁纸和菜单栏,说明 macOS 屏幕录制权限没给,回到第 3 步处理。
  4. 在画面上单指拖动一次,确认画面跟着移动;双指捏合一次,确认能放大缩小;双指轻点一次,确认画面复位。
  5. 点“⋯”打开菜单,依次试“帧率”“清晰度”“画面模式”“指针”,确认每一项都能改且画面立刻响应。
只看到端口在线或节点在线不算完整验收。必须至少发送一条真实任务并收到 Codex 最终回复,并且远程画面里能看到真实窗口。

8. 升级

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

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

云端中转

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

9. 故障排查

连接失败

先运行电脑验证脚本,再检查地址、token、Wi-Fi 和防火墙。异地连接按你选的那条查:方式一 —— 在电脑上 curl -s -o /dev/null -w "%{http_code}" https://你的网址/api/node-status,返回 401 说明隧道通、在正常要令牌,530 说明连接器没在跑(重跑接入脚本),502 说明刚掉线等一分钟;方式二 —— 确认电脑端与手机端 Tailscale 都登录了同一账号且都显示在线。

一直排队

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

工作包不同步

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

远程画面只有壁纸和菜单栏

macOS 没有授予“屏幕录制”权限,或者授权后没有重启电脑端服务。到电脑的“系统设置 → 隐私与安全性 → 屏幕录制”里给电脑端服务打勾,然后重新运行一次安装脚本或重启服务,再回手机点“⋯ → 重新连接”。

远程画面提示版本太旧或起不来

那台电脑上跑的服务低于支持实时画面所需版本。解压新版完整部署包后:Windows 运行 repair-windows.ps1,Mac 重新运行 install-mac.command;完成后在手机画面里点“⋯ → 重新连接”。

画面卡住或模糊

先点“⋯ → 重新连接”。仍不理想就调低“帧率”(网络一般时用 30 fps)或调高“清晰度”;“画面模式”在“匹配铺满”和“完整显示”之间切换,可以分别照顾看清细节和看全整张桌面。

Windows 防火墙

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

10. 安全和卸载