外部版完整部署教程

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

1. 安装准备

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

解压完整部署包
不要直接在压缩包预览器里运行文件。

运行安装
双击 install-mac.command。如系统阻止，右键选择“打开”。

记录连接信息
脚本会显示电脑地址、访问口令和工作包目录，并保存到 ~/.codex-pilot/mobile-control/connection-info.txt。

验证
双击 verify-mac.command，确认服务、工作包和 Codex 启动文件正常。

手机电脑地址：http://192.168.1.25:8787
访问口令：每台电脑独立生成的随机字符串

双击一键安装
运行 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”，然后重新运行安装脚本。

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

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

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

电脑地址不要带 /api/bootstrap 或 ?token=。token 输入框只填随机字符串。

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

不建议把 8787 端口直接暴露到公网。Tailscale 更容易配置，也更安全。

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

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

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

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

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

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

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

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