安装准备部署 Mac 部署 Windows 连接手机多电脑与异地验收升级故障排查安全

# 外部版完整部署教程

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

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

## 1. 安装准备

- 电脑已安装并登录 ChatGPT/Codex。
- Android 手机允许安装 APK。
- 同网使用时手机和电脑连接同一 Wi-Fi。
- 异地使用时，手机和电脑安装 Tailscale。
- Windows 准备 Python 3；脚本也会尝试使用 Codex 自带运行环境。

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

## 2. 部署 Mac

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

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

## 3. 部署 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”，然后重新运行安装脚本。

## 4. 安装手机 App

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

### 扫码连接

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

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

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

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

## 5. 多电脑与异地连接

### 多电脑

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

### 异地连接

1. 手机和电脑安装 Tailscale。
2. 加入同一个网络或共享设备。
3. 在 App 填写电脑 Tailscale 地址，例如 `http://100.x.x.x:8787`。

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

## 6. 完整验收

- 电脑验证脚本通过。
- 手机显示节点在线。
- 手机能读取电脑工作包。
- 手机发送“只回复：联动正常”，电脑返回真实回复。
- 新建工作包后电脑和手机都能看到。
- 执行一条任务时能补充、取消和查看状态。
- 锁屏后能收到任务开始、确认、失败或完成通知。

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

## 7. 升级

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

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

### 云端中转

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

## 8. 故障排查

### 连接失败

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

### 一直排队

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

### 工作包不同步

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

### Windows 防火墙

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

## 9. 安全和卸载

- 不要把 token 发给不可信的人。
- 怀疑泄露时删除安装目录中的 `.token`，重新运行安装脚本。
- 卸载脚本只移除自启并停止服务，默认保留历史数据和真实工作包文件。