完整部署教程
从零部署手机、Mac、Windows 和多电脑联动。适用版本 5.0.78-external。
1. 安装准备
- 电脑已安装并登录 ChatGPT/Codex。
- Android 手机允许安装 APK。
- 连接使用专属接入网址(HTTPS 域名),或手机和电脑均安装 Tailscale(电脑端由安装脚本自动代装,手机端要你自己装并登录同一账号)。
- Windows 准备 Python 3;脚本也会尝试使用 Codex 自带运行环境。
- 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
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。
修复旧 Windows 节点
如果手机显示某台 Windows 为“需升级”,或者点“升级电脑端”后服务版本仍不变化,在那台 Windows 上解压新版完整部署包并运行:
powershell -ExecutionPolicy Bypass -File .\repair-windows.ps1
普通客户也可以直接双击 repair-windows.cmd。修复脚本会保留本机 token 和历史数据,覆盖当前服务文件,修正登录自启启动路径,放行 8787 端口并重启服务。完成后再运行 verify-windows.ps1,确认服务版本,以及远程画面与远程操作的可用状态。
repair-windows.ps1 升级后即可。5. 安装手机 App
- 安装
app/目录里版本号最新的 APK。 - 首次启动时允许通知权限;使用扫码连接时允许相机权限。
- 打开 App,进入“电脑 / 当前连接”。
- 手动填写电脑地址和 token,或使用下面的扫码方式。
- 点“保存并连接”,等待电脑在线和工作包数量出现。
扫码连接
新版安装器会自动打开扫码页面,然后在手机 App 点“扫码连接”扫描页面二维码。二维码由电脑本机生成,不经过第三方服务。
二维码使用 10 分钟有效的一次性配对码,不包含长期 token;配对成功后立即失效。过期或扫码失败时刷新页面即可重新生成。
页面未自动打开时,在电脑浏览器访问 http://127.0.0.1:8787/connect。
10. / 172.16-31. / 192.168.),或 Tailscale 的 100.64.0.0/10 加密专网地址。电脑地址不要带 /api/bootstrap 或 ?token=。token 输入框只填随机字符串。装完之后:要让手机能出图,先绑做图密钥
App 底部「AI电商图」是手机端出电商图的地方,用的是你启流账号下的额度(和官网出图同一份额度,按张扣费,没有免费额度)。第一次进去要在页面上绑一把「做图密钥」:名下已经有用在做图分组的密钥就直接点一把;没有就点「一键创建做图密钥」,App 会按默认的「生图分组」替你建一把。绑完卡片显示「已绑定 · 密钥名」。
6. 多电脑与异地连接
多电脑
每台电脑分别运行安装脚本,然后在 App 的电脑管理页面逐台添加名称、地址和该电脑自己的 token。添加后先运行节点诊断。
异地连接(方式一:专属接入地址,推荐)
同一个 Wi-Fi 下用局域网地址即可,不需要做任何额外设置。人不在同一个网络里(出差、用 4G)时,如果你的账号已经开通了专属接入,这是最省事的一条路:不用装任何第三方软件,也不需要你自己做任何网络配置。
- 拿到两项信息。一个专属网址(
https://开头),和一串连接器令牌。这两项由我们单独发给你。 - 填进部署包。打开
tunnel/access-info.txt,把网址填在ADDRESS=后面、把令牌填在TOKEN=后面,保存。 - 运行接入脚本。Windows:以管理员身份运行
tunnel\windows\install.cmd;macOS:双击tunnel/macos/install.command。 - 确认成功。脚本最后会自动自检,看到下面两句就成功了:
接入完成,专属地址已通(HTTP 401:隧道正常且在要求令牌)
安全检查:公网 /connect 已封(HTTP 403),符合预期
手机 App 连接页填那个专属网址即可,手机端不用装任何东西。连接器会开机自动运行。
接入脚本已经替你封掉了会泄露配对码的
/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 专网地址。
- 电脑端已经在安装脚本里自动装好了。Windows 是全静默安装;macOS 装完需要你在“系统设置 → 通用 → 登录项与扩展”里允许它的系统扩展。
- 登录 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 是凭据,用完请自行撤销,不要写进任何文件。
- 手机上也要装 Tailscale,并登录同一个账号(或者由管理员把电脑共享给你)。中国大陆用官方 APK 直链,不要用 Google Play:
https://pkgs.tailscale.com/stable/tailscale-android-universal-latest.apk - 登录完成后重跑一次电脑端安装脚本(或
verify脚本),它会打印出本机的 Tailscale 地址,并写进connection-info.txt。在 App 里填写http://100.x.x.x:8787即可。
/connect 页面如果显示的是 192.168.x.x 这类局域网地址,说明 Tailscale 那一步还没做完 —— 页面会给出提示。7. 完整验收
- 电脑验证脚本通过。
- 手机显示节点在线。
- 手机能读取电脑工作包。
- 手机发送“只回复:联动正常”,电脑返回真实回复。
- 新建工作包后电脑和手机都能看到。
- 执行一条任务时能补充、取消和查看状态。
- 点“远程 → 进入桌面”,能看到电脑上的真实窗口(不是只有壁纸)。
- 锁屏后能收到任务开始、确认、失败或完成通知。
远程画面单独验收
- 底部点“远程”,确认列表里能看到这台电脑,标题下方显示“在线 N/M”。
- 点“进入桌面 ›”,等待画面出现。
- 确认画面里能看到电脑上真实的窗口;如果只看到壁纸和菜单栏,说明 macOS 屏幕录制权限没给,回到第 3 步处理。
- 在画面上单指拖动一次,确认画面跟着移动;双指捏合一次,确认能放大缩小;双指轻点一次,确认画面复位。
- 点“⋯”打开菜单,依次试“帧率”“清晰度”“画面模式”“指针”,确认每一项都能改且画面立刻响应。
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. 安全和卸载
- 不要把 token 发给不可信的人。
- 怀疑泄露时删除安装目录中的
.token,重新运行安装脚本。 - 卸载脚本只移除自启并停止服务,默认保留历史数据和真实工作包文件。