# Codex Pilot 外部版完整部署与使用教程

适用版本：2.60-external

## 一、这套软件做什么

Codex Pilot 把手机变成电脑端 Codex 的远程控制台。手机可以查看电脑工作包和小对话、发送任务、补充或打断执行、语音转文字、上传附件、查看结果、取消和重发任务，并在多台电脑之间切换。

基本链路：

```text
手机 App -> 电脑端 8787 服务 -> 电脑上的 Codex -> 结果返回手机
```

每台电脑都运行自己的服务并生成自己的访问口令。外部版不预置任何内部地址、节点或口令。

## 二、安装前准备

### 手机

- Android 手机，允许安装来源不明的 APK。
- 手机与电脑在同一 Wi-Fi；异地使用时安装 Tailscale、ZeroTier 或准备其他可访问地址。

### Mac

- 已安装并登录 ChatGPT/Codex。
- macOS 自带 Python 3 可用。
- 首次运行 `.command` 文件时允许系统打开。

### Windows

- 已安装并登录 Codex。
- Python 3 可用；安装脚本也会尝试使用 Codex 自带的 Python。
- PowerShell 可以运行本地脚本。
- 防火墙允许 TCP 8787。脚本会尝试自动添加规则，失败时需要管理员手动放行。

## 三、部署第一台 Mac

1. 解压完整部署 ZIP，不要直接在压缩包预览器里运行。
2. 双击 `install-mac.command`。
3. 如果系统阻止，右键文件选择“打开”，再确认运行。
4. 等待脚本显示安装完成。
5. 记录以下内容：

```text
手机电脑地址：http://电脑IP:8787
访问口令：随机字符串
工作包目录：/Users/你的用户名/CodexWorkspaces
```

连接信息也会保存在：

```text
~/.codex-pilot/mobile-control/connection-info.txt
```

6. 双击 `verify-mac.command`。看到本机服务正常、工作包数量和 Codex 启动文件状态后，电脑端部署完成。

## 四、部署第一台 Windows

在部署包目录打开 PowerShell，运行：

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

普通客户可以直接双击 `install-windows.cmd`，在系统提示时允许管理员权限。PowerShell 命令作为备用安装方式。

安装脚本会完成：复制服务文件、生成 token、创建默认工作包目录、注册登录自启、尝试放行 8787 端口并启动服务。

连接信息保存在：

```text
%USERPROFILE%\.codex-pilot\mobile-control\connection-info.txt
```

验证命令：

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

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

## 五、安装手机 App 并连接

1. 打开部署包的 `app/` 目录，安装版本号最新的 `CodexPilot-external-*.apk`。
2. 外部版包名为 `com.langchao.codexcontrol.external`，不会覆盖内部版。
3. 首次启动时允许通知权限；使用扫码连接时允许相机权限。
4. 打开 App，进入电脑连接页面。
5. 填写安装脚本输出的电脑地址和 token，或者使用下方扫码方式。
6. 点“保存并连接”。
7. 成功后应看到电脑在线、工作包数量和节点状态。

### 扫码连接

安装成功后，Windows 和 Mac 安装器会自动打开扫码页面。手机 App 点“扫码连接”扫描二维码即可。

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

页面未自动打开时，在电脑浏览器打开：

```text
http://127.0.0.1:8787/connect
```

然后在手机 App 点“扫码连接”扫描页面二维码。二维码由电脑本机生成，不经过第三方服务。

同一 Wi-Fi 示例：

```text
http://192.168.1.25:8787
```

只填地址和端口，不要把 `/api/bootstrap` 或 `?token=` 一起填进去。token 输入框只填随机字符串。

### 首次连接验收

1. 运行节点诊断并确认没有缺失能力。
2. 确认手机能读取电脑工作包和小对话。
3. 从手机发送“只回复：联动正常”。
4. 必须收到电脑端 Codex 的最终回复，不能只根据端口在线判断部署成功。
5. 锁屏测试一次任务开始、确认、失败或完成通知。

## 六、异地连接和多电脑

### 推荐方案：Tailscale

1. 手机和每台电脑安装 Tailscale。
2. 登录同一 Tailscale 网络，或由管理员共享设备。
3. 找到电脑的 Tailscale IPv4 地址。
4. 在 App 添加电脑：

```text
http://100.x.x.x:8787
```

5. 每台电脑使用各自安装脚本生成的 token。

### 添加多台电脑

对每台电脑分别运行安装脚本，然后在 App 的电脑管理页面逐台添加：

- 电脑名称：自定义，例如“办公室 Mac”“家里 Windows”。
- 电脑地址：该电脑的局域网或 Tailscale 地址。
- 访问口令：该电脑自己的 token。

添加后先运行节点诊断，确认在线再发送真实任务。

## 七、工作包和小对话

- 手机新建工作包：会在当前电脑默认工作包目录创建，并登记到电脑 Codex。
- 电脑新建工作包：在 Codex 打开或创建过后，手机刷新即可读取。
- 小对话对应电脑端 Codex 线程，上下文与电脑端相通。
- 手机删除工作包默认只删除登记和桌面入口，不删除真实文件。
- 删除小对话会归档对应线程；执行删除前都有确认步骤。
- 批量管理支持全选、单选、反选和取消。

## 八、发送任务的三种方式

### 桌面线程

默认模式。任务写入电脑端当前小对话，上下文与电脑保持一致，适合做项目、改代码和持续任务。

### 引导执行

用于任务正在执行时补充要求、纠正方向或要求停止。常用指令包括：补充、打断、继续、先解释和不要修改文件。

### API 问答

用于快问快答，不写入电脑端小对话。需要在电脑服务中配置可用的 API Key 和供应商。

## 九、语音、附件和链接

- 点麦克风开始实时语音转文字，再点停止结束；发送消息时会自动停止识别。
- 语音准确率首先取决于手机系统语音服务。网络受限时可配置电脑端转写服务作为后备。
- 点“+”可以上传图片、视频和文件。
- 聊天中的网页地址可以直接点击打开。
- 长按消息可复制全文；文本选择模式可只复制部分内容。

## 十、任务状态和恢复

- 排队：等待同一工作包的前一个任务完成。
- 正在执行：电脑端 Codex 已开始处理。
- 正在重连：电脑网络或模型服务短暂中断，系统在恢复。
- 疑似卡住：超过合理时间没有新进度，可进入详情执行诊断、取消或重发。
- 失败：查看简明错误提示和日志，再选择“纠正”或“重新发送”。

任务中心支持查看详情、补充、打断、取消、重发和日志。不要只根据端口在线判断电脑已恢复，应以节点状态和真实回复为准。

### 离线队列和后台通知

- 电脑暂时不可达时，App 会把任务加密保存到本机离线队列。
- 后台联动服务每 25 秒尝试续传，成功后通知已发送数量。
- 任务开始、需要确认、失败和完成会通过 Android 通知渠道提醒。
- 手机重启或 App 升级后，开机接收器会恢复后台联动服务。

### 可选云端中转

1. 在云服务器进入部署包的 `cloud-relay/` 目录。
2. 复制 `.env.example` 的变量或直接设置 `CODEX_RELAY_TOKEN`。
3. 运行 `docker compose up -d --build`。
4. 在 App 的“云端中转”中填写 HTTPS 地址和中转口令。

不填 GitHub 仓库时，云端只暂存任务，目标电脑上线后领取；填写允许的 GitHub HTTPS 仓库时，可由云端 Codex 执行。

## 十一、升级

### 手机 App

下载新版 APK 后直接覆盖安装。外部版和内部版包名不同，不会互相覆盖。

### 电脑端

下载新版完整部署包，再次运行对应安装脚本。脚本会更新程序文件并保留工作包登记、历史任务和 token。

### Codex/ChatGPT 更新后

新版 Mac 服务会自动寻找 `ChatGPT.app`、旧 `Codex.app` 和 PATH 中的 Codex。若仍提示找不到启动文件，重新运行安装脚本并验证。

## 十二、故障排查

### 保存并连接没有反应

检查地址格式、token 是否完整，并先在电脑运行验证脚本。

### 手机提示连接失败

确认手机和电脑网络互通；关闭手机移动数据测试；检查防火墙和 8787 端口；异地连接确认 Tailscale 在线。

### 一直正在排队

进入任务中心查看是否有旧任务占用；取消疑似卡住任务；运行节点诊断；确认电脑 Codex 可以正常发送一条普通消息。

### 手机有工作包，电脑没有

刷新电脑 Codex 侧栏；确认工作包目录真实存在；重新运行电脑安装脚本；再在手机执行节点诊断。

### 电脑有工作包，手机没有

先在电脑 Codex 打开该目录并创建一次对话，再回手机刷新工作包。

### Windows 防火墙

用管理员 PowerShell 放行：

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

## 十三、安全建议

- 不要把 token 发给不可信的人。
- 不要把 8787 端口直接暴露到公网；优先使用 Tailscale。
- 怀疑 token 泄露时，停止服务，删除安装目录中的 `.token`，重新运行安装脚本生成新 token。
- 卸载脚本默认保留数据和 token；确认不再使用后再手动删除安装目录。

## 十四、卸载

Mac：双击 `uninstall-mac.command`。

Windows：

```powershell
powershell -ExecutionPolicy Bypass -File .\uninstall-windows.ps1
```

卸载脚本只移除自启和停止服务，不自动删除历史数据与工作包文件。