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

适用版本：5.0.78-external

## 一、这套软件做什么

Codex Pilot 把手机变成电脑端 Codex 的远程控制台。手机可以查看电脑工作包和小对话、发送任务、补充或打断执行、语音转文字、上传附件、查看结果、取消和重发任务，并在多台电脑之间切换。底部还有一个独立的「AI电商图」入口，可以在手机上直接出电商图（见第十五节）。

基本链路：

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

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

## 二、安装前准备

### 手机

- Android 手机，允许安装来源不明的 APK。
- 客户版连接必须使用 HTTPS 域名、局域网私有地址（`10.` / `172.16-31.` / `192.168.`），或手机与电脑同时接入 Tailscale 后使用它的 `100.64.0.0/10` 加密专网地址；公网裸 HTTP 地址不支持。
  拿到 HTTPS 域名有两条路：**方式一「专属接入地址」**（我们发你一个 `https://xxxx.qiliuapi.com`，电脑端跑一次脚本装好，**手机什么都不用装**，推荐）；**方式二 Tailscale**（由电脑端安装脚本代装，但**手机也要装并登录同一账号**）。
  **手机与电脑在同一个 Wi-Fi 时两条都不用**，直接填局域网地址即可；异地才需要。详见第九节。

### Mac

- 已安装并登录 ChatGPT/Codex。
- macOS 自带 Python 3 可用。
- 首次运行 `.command` 文件时允许系统打开。
- 需要给电脑端服务授予“屏幕录制”权限，否则手机上只能看到桌面壁纸。这一步必须本人在电脑前点击确认，脚本无法代劳。

### Windows

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

## 三、让外部电脑 AI 自己部署

如果外部电脑上已经有 Codex、ChatGPT 或其他能操作本机终端的 AI 助手，可以优先走 AI 自部署流程。部署包内提供：

- `bootstrap-windows.ps1`
- `bootstrap-mac.command`
- `docs/AI-SELF-DEPLOY-zh-CN.md`

推荐把 `docs/AI-SELF-DEPLOY-zh-CN.md` 里的提示词复制给外部电脑 AI。AI 会从公开下载站读取 `app-info.json`，下载最新版完整部署包，校验 SHA256，解压后执行正式安装或修复脚本，再做本机健康检查并打开扫码页。

Windows 手动启动 bootstrap：

```powershell
$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 手动启动 bootstrap：

```bash
cd /tmp
curl -fL "https://pilot.qiliuai.com/bootstrap-mac.command" -o bootstrap-mac.command
chmod +x bootstrap-mac.command
./bootstrap-mac.command
```

AI 可以自动处理下载、校验、解压、安装、修复、启动和健康检查。连接方式上：**方式一**它会读 `tunnel/access-info.txt`、装好隧道连接器、把公网地址写进节点并做公网自检；**方式二**它会自动把 Tailscale 装好并读出本机地址。
但 Windows 管理员授权、macOS 屏幕录制/辅助功能权限、Codex 登录、**方式一所需的 `ADDRESS`/`TOKEN`（只能由我们发给你）**、**方式二的 Tailscale 登录（以及手机上装 Tailscale 并登录同一账号）**和手机扫码仍需要用户确认。不要让 AI 把 token、私有地址或日志里的敏感信息粘贴到公开聊天里。

## 四、部署第一台 Mac

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

```text
手机电脑地址：https://电脑域名
访问口令：随机字符串
工作包目录：~/CodexWorkspaces
```

连接信息也会保存在：

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

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

### 接上连接方式（异地连接才需要）

同一个 Wi-Fi 下不需要这一步。要异地连，二选一：

**方式一（推荐）**：把我们发的 `ADDRESS` / `TOKEN` 填进部署包 `tunnel/access-info.txt` 的等号后面，然后：

```bash
./tunnel/macos/install.command
```

它会装好隧道连接器、把公网地址写进节点、重启节点并自检。看到这两句就算成功：

```text
接入完成，专属地址已通（HTTP 401：隧道正常且在要求令牌）
安全检查：公网 /connect 已封（HTTP 403），符合预期
```

**方式二**：`./install-mac.command --tailscale-authkey=tskey-auth-xxxxxxxx`（详见第九节）。

## 五、部署第一台 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”，然后重新运行安装脚本。

### 接上连接方式（异地连接才需要）

同一个 Wi-Fi 下不需要这一步。要异地连，二选一：

**方式一（推荐）**：把我们发的 `ADDRESS` / `TOKEN` 填进 `tunnel\access-info.txt` 的等号后面，然后**以管理员身份**运行：

```powershell
.\tunnel\windows\install.cmd
```

它会装好隧道连接器服务、把公网地址写进 `start-windows-node.ps1`、重启节点并自检。看到这两句就算成功：

```text
接入完成，专属地址已通（HTTP 401：隧道正常且在要求令牌）
安全检查：公网 /connect 已封（HTTP 403），符合预期
```

**方式二**：`.\install-windows.ps1 -TailscaleAuthKey tskey-auth-xxxxxxxx`（详见第九节）。

### 修复旧 Windows 节点

如果手机的远程控制切换页显示某台 Windows 为“需升级”，或者在手机里点“升级电脑端”后 Windows 服务版本仍不变化，在那台 Windows 上解压新版完整部署包并运行：

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

普通客户可以直接双击 `repair-windows.cmd`。修复脚本会优先识别当前正在运行的服务目录，保留本机 token 和历史数据，覆盖 Windows 服务文件，重写登录自启脚本，放行 8787 端口并重启服务。完成后再运行 `verify-windows.ps1`，确认服务版本和远程观看/远程输入能力已经变为可用。

## 六、安装手机 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 点“扫码连接”扫描页面二维码。二维码由电脑本机生成，不经过第三方服务。

手机不在电脑旁、只能远程看到那块屏幕时，把二维码页面截个图弄到手机上，在 App 里点「扫码连接 → 从相册选择二维码截图」选这张图即可，不需要相机。

客户版不允许直接填写同一 Wi-Fi 的裸 HTTP 地址。请用**方式一**拿到一个 HTTPS 域名（我们发你地址与令牌，电脑端跑一次脚本即可），或按下一节用**方式二 Tailscale**。

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

### 首次连接验收

1. 运行节点诊断并确认没有缺失能力。
2. 确认手机能读取电脑工作包和小对话。
3. 从手机发送“只回复：联动正常”。
4. 必须收到电脑端 Codex 的最终回复，不能只根据端口在线判断部署成功。
5. 点底部“远程 → 进入桌面”，确认画面里能看到电脑上真实的窗口（不是只有壁纸），并用手势拖动、捏合各一次。
6. 锁屏测试一次任务开始、确认、失败或完成通知。

## 七、远程控制电脑画面

这是本版的主功能：手机上直接看到电脑桌面，并且可以点击、拖动、滚动和打字，等于把电脑搬到手上。画面走专用视频通道，手机端硬件解码，静止画面几乎不产生流量。

### 进入

1. 底部点“远程”，进入远程控制页；标题下方显示“在线 N/M”，N 是当前能连上的电脑数量。
2. 列表里每台电脑显示名称和状态，支持实时画面的会排在前面。
3. 点这台电脑右侧的“进入桌面 ›”，开始拉取画面。
4. 看到画面后：单指轻点就是把点击发给电脑，单指拖动是移动画面。

### 顶栏三颗按钮

| 按钮 | 作用 |
| --- | --- |
| ‹ | 返回上一层 |
| Codex / 桌面 | 切换画面目标：只看 Codex 窗口，还是看整张电脑桌面 |
| ⋯ | 打开菜单 |

看整张桌面时可以顺手操作电脑上的其它软件；只看 Codex 窗口时画面更聚焦。两种目标随时可换，不用退出画面。

### 手势

| 手势 | 作用 |
| --- | --- |
| 单指轻点 | 把这一次点击发给电脑 |
| 单指拖动 | 移动画面本身，把想看的位置拉到屏幕中央 |
| 双指捏合 | 放大缩小画面，以两指中心为缩放中心 |
| 双指轻点 | 画面复位，回到完整显示并居中 |
| 长按约 0.4 秒后拖动 | 按住电脑上的鼠标左键拖动，用于框选文字、拖窗口 |

要点：单指拖动永远只移动画面，不会误碰电脑；要按住鼠标拖动必须先长按一下再拖（长按后 App 会提示“正在按住远程鼠标”）。

### “⋯”菜单

| 菜单项 | 可选值 / 作用 |
| --- | --- |
| 键盘 | 呼出或收起屏幕键盘；键盘聚焦时显示“收起键盘” |
| 横屏 / 竖屏 | 切换画面方向，看宽屏桌面建议横屏 |
| 帧率 | 30 fps / 60 fps / 120 fps，默认 60 |
| 清晰度 | 流畅 / 清晰 / 分辨率… |
| 画面模式 | 匹配铺满 / 完整显示 |
| 指针 | 隐藏指针（触摸）/ 显示指针（鼠标） |
| 切换电脑 | 不退出画面直接换到另一台电脑 |
| 重新连接 | 画面卡住或起步超时后重连 |
| 唤起桌面端 | 让电脑把 Codex 桌面端拉到前台；电脑端不支持时该项不可用 |
| 复位画面 | 等同双指轻点 |

指针两档：画面里的白色箭头是电脑采集时画进去的真实远端光标，所以换档需要重连一次画面（约一秒）。默认“隐藏指针（触摸）”，手指点哪儿就点哪儿；需要看清鼠标停在哪里时切到“显示指针（鼠标）”。

### 电脑端前提

| 情况 | 表现与处理 |
| --- | --- |
| 电脑端版本过旧 | 提示“这台电脑端版本太旧，暂不支持远程控制 Codex 的实时画面”，需升级电脑端服务 |
| macOS 没有屏幕录制权限 | 画面只有壁纸和菜单栏，看不到窗口。到“系统设置 → 隐私与安全性 → 屏幕录制”授权后重启服务 |
| 画面起步超时 | App 自动切到兼容画面并提示一次（延迟略高，功能仍可用）；点“⋯ → 重新连接”可再试高清通道 |

“屏幕录制”是 macOS 上远程画面的硬前提，而且只能本人在电脑前点确认，脚本和远程操作都无法代替。

## 八、扫码连接、启流账号与换手机

### 扫码连接

1. 电脑端安装完成后会自动打开本机配对页；没打开就在电脑浏览器访问 `http://127.0.0.1:8787/connect`。
2. 手机 App 点“扫码连接”，扫页面上的二维码。
3. App 自动保存地址和口令，直接可用。

二维码是 10 分钟有效的一次性配对码，不含电脑的长期 token；过期或已被使用就刷新电脑页面重新生成。

### 登录启流账号：换手机不用重配

登录启流账号并把电脑绑定到账号名下后，这台电脑会出现在“启流账号已绑定”列表里。之后任何一台登录同一账号的手机，点一下就能直接连上，不用再输地址和口令。

- 绑定入口：电脑连接页的“绑定启流账号到此电脑”，或连接后右上角设置里的同一项。
- 同一台电脑在账号里只显示一行，不会因为换了网络（专属接入地址 / 局域网地址 / Tailscale 地址）重复出现。
- 电脑在中转站已经登记在别的启流账号名下时，App 会明确提示，并提供改绑到当前账号的入口。

账号只用来帮你记住电脑、免口令连接。任务、对话和文件始终在你自己的电脑上。

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

### 方式一（推荐）：专属接入地址

**我们发你两行内容**：`ADDRESS`（形如 `https://xxxxxxxx.qiliuapi.com`）与 `TOKEN`（约 180 字符）。收不到就找我们，不要自己编。

1. **电脑端**：把它们填进部署包 `tunnel/access-info.txt` 的等号后面。
   - Windows：`<解压目录>\codex-pilot-external-package\tunnel\access-info.txt`，保存后**以管理员身份**运行 `tunnel\windows\install.cmd`
   - macOS：`tunnel/access-info.txt`，然后在终端运行 `./tunnel/macos/install.command`

   填充要点：`TOKEN` **一次性完整粘贴**，不要换行、不要加空格；`ADDRESS` 结尾不要带斜杠。

2. **脚本会做什么**：装好 Cloudflare Tunnel 连接器（开机自启）、把公网地址写进节点启动脚本、重启节点、自检。
   看到下面两句才算成功：

```text
接入完成，专属地址已通（HTTP 401：隧道正常且在要求令牌）
安全检查：公网 /connect 已封（HTTP 403），符合预期
```

   自检返回 **530** = 连接器没起来（重跑脚本）；返回 **502** = 刚掉线，等一分钟再试。

   安装脚本**还会顺手把 Tailscale 也装好当备选通道**（不装也行，但装了不影响任何事）。
   如果你只用方式一，看到「Tailscale 还没登录 / 未安装」这类提示**可以忽略** —— 只有走方式二才需要登录它。

3. **手机端**：**什么都不用装**。在 App 添加电脑时直接填那个 https 地址：

```text
https://xxxxxxxx.qiliuapi.com
```

4. **安全**：这个地址是公网可访问的，所以它本身就是钥匙——**不要外传**。
   脚本已经替你封掉了配对码页面（`/connect` 公网返回 403）；如果你自己 curl 这个地址发现 `/connect` 返回 200，
   说明护栏没生效，请立刻找我们。电脑本地的 `http://127.0.0.1:8787/connect` 返回 200 是正常的。

### 方式二：Tailscale

1. **电脑端**：安装脚本已经代装 Tailscale。Windows 是全静默安装；macOS 装完需要你在“系统设置 → 通用 → 登录项与扩展”里允许它的系统扩展。
2. **登录电脑端 Tailscale**，两条路任选：
   - 手动：点菜单栏 / 开始菜单里的 Tailscale，点 Log in，在浏览器里完成登录。
   - 一步到位：在 `login.tailscale.com/admin/settings/keys` 生成一个 auth key（勾 **Preauthorized**、可复用、可设过期），然后重跑安装脚本：
     - macOS：`./install-mac.command --tailscale-authkey=tskey-auth-xxxxxxxx`
     - Windows：`.\install-windows.ps1 -TailscaleAuthKey tskey-auth-xxxxxxxx`

     这条会直接加入网络，不再需要点浏览器。**auth key 是凭据，用完请自行撤销，不要写进任何文件。**
3. **手机端**：装 Tailscale 并登录**同一个账号**（或由管理员共享设备）。中国大陆用官方 APK 直链，不要用 Google Play：

```text
https://pkgs.tailscale.com/stable/tailscale-android-universal-latest.apk
```

4. 重跑一次电脑端安装脚本或 `verify` 脚本，它会打印本机的 Tailscale IPv4 地址，并写进 `connection-info.txt`。电脑端 `/connect` 页面也会自动显示这个地址（如果显示的是 `192.168.x.x`，说明 Tailscale 还没登录完）。
5. 在 App 添加电脑：

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

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

> **两条方式选一条即可，不要都装。** 客户版接受 HTTPS 域名、局域网私有地址，或 Tailscale 的 `100.64.0.0/10` 地址（`NodeTransportPolicy.java`）。**手机与电脑连同一个 Wi-Fi 时用局域网地址就够了，两条都不需要**；只有人不在同一个网络里（异地）才需要。
> 方式一的差别在于**手机端零安装**；方式二的差别在于**电脑端不依赖我们发地址**。

### 添加多台电脑

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

- 电脑名称：自定义，例如“办公室 Mac”“家里 Windows”。
- 电脑地址：该电脑的专属接入地址（`https://…`），或 Tailscale 地址（`http://100.x.x.x:8787`）。
- 访问口令：该电脑自己的 token。

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

## 十、工作包和小对话

- 手机新建工作包：会在当前电脑默认工作包目录创建，并登记到电脑 Codex。
- 电脑新建工作包：在 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（列表、弹窗、远程页）都会跟着变，只有远程画面本身保持黑底，避免影响看画面。

### 账号与充值

“我的”页显示当前账号、余额和版本号。充值弹窗里可以直接用兑换码，也可以点“去小店购买卡密”。

### 换成你自己的 ChatGPT 账号（以及改回启流）

电脑上的 ChatGPT 桌面端是被我们装好的 **API key 模式**登着的 —— 所以桌面端菜单里那颗「退出登录」**点了不会有反应**：它清的是账号会话，而这台电脑上本来就没有账号会话。这不是故障，也没有谁在挡你。

想用回自己的账号：「电脑与连接」页里，逃生通道那两行的第二行有 **用我的账号** 和 **改回启流** 两颗。

- **用我的账号**：会暂停启流守卫、摘掉 `config.toml` **根部**启流选的那几行模型设置（你自己写的配置一律不动，改前先备份），并把桌面端登录用的那把 API KEY **备份后移走** —— 最后这一步才是关键，只要它还在，桌面端就一直停在「API KEY 模式」、不给账号登录入口。做完之后打开电脑上的 ChatGPT 桌面端，用你自己的账号登录即可。
- **改回启流**：把上面三件事原样倒回去（放回备份的登录凭据、把模型选择写回 `config.toml` 根部、恢复守卫）。手机端刷新一下就能照常用，电脑端不用重启。
- **「改回启流」不会覆盖你自己刚登上的 ChatGPT 账号。** 如果你在切过去之后已经用自己的账号登录成功，那份登录会原样留着。
- 点之前会先把这台电脑当前的状态摆给你看（含「桌面端登录：API KEY 模式 / 你自己的 ChatGPT 账号」），确认后才动手。
- 电脑端程序偏旧、没有这两条接口时，点下去会收到一句中文说明让你重新运行一次安装程序，而不是空白弹窗或英文报错。

在电脑上开终端也可以办同一件事：

```
pilot-control status          # 现在是什么状态，包括「桌面端登录：API KEY 模式 / ChatGPT 账号」
pilot-control login           # 用我自己的账号
pilot-control resume          # 改回启流
pilot-control restore-auth    # 只把之前备份的登录凭据放回去（--backup 可指定哪一份）
```

## 十五、手机端 AI 电商图

底部「AI电商图」把官网「启流AI专业电商图片生成」那一套出图能力搬到了手机上：写提示词、挂参考图、选比例和数量，图直接出在手机里，可以看大图、存进相册，也能翻历史记录按原参数重做。这条链路走我们自己的网关，与远程画面、工作包任务互不影响。

### 先绑定做图密钥

出图用的是**你启流账号下的额度**（和官网出图同一份额度，按张扣费，没有免费额度），所以要先在页面上绑一把「做图密钥」：

1. 名下已经有用在做图分组的密钥时，最上面的账号卡会直接把它们列出来，点一把就绑上了。
2. 没有可用密钥时点「一键创建做图密钥」，App 会按默认的「生图分组」替你建一把并绑定；名下已有密钥时也可以点「手动填密钥」粘一把你自己的。
3. 绑定成功后卡片显示「已绑定 · 密钥名」，下面一行说明「分组与费率由网关按这把密钥自己判定」。

| 按钮 | 作用 |
| --- | --- |
| 更换密钥 | 换绑到另一把（名下已有的，或手动粘的） |
| 解绑 | 只清除 App 里的这条绑定，站点上那把密钥不会被删除或停用 |
| 重新读取账号 | 在别处新建了密钥、或刚换了账号时，刷新这张卡片 |

账号余额不足时会出图失败，充值和卡密都在 App 的「我的」页。

### 六个创作 tab

| Tab | 用途 |
| --- | --- |
| 主图 | 方形商品主图，可以只写提示词，也可以挂参考图 |
| 详情图 | 竖版分节图，一次出几节拿去铺详情页 |
| 海报 | 竖版活动海报，活动信息写在提示词里 |
| 复刻同行 | 必须上传一张同行的图，照它的构图和光影出同款 |
| 批量改图 | 可一次传多张，画面比例跟随你的原图 |
| AI工具 | 图片去水印、画质提升这一类，暂未开通 |

一排放不下全部 tab，左右滑动可以看后面两个。

### 怎么出一张图

1. 选好 tab，写提示词。下面「常用场景」里的词条可以一键套用现成描述；其中「更换背景」「模特换脸」「批量抠图」这类用的是固定模板，套上之后输入框会锁住（页面会说明原因）。
2. 要改背景、换模特、改图上文字这类**必须挂参考图**：点「+ 加参考图」可一次选多张，缩略图右上角的「×」能单张移除。不挂图就是纯文生图。
3. 按需调参数：平台、比例、风格、语言、数量、模型。比例选定后下面会显示这次实际出图尺寸。
4. 选「套图模式」还是「自定义生图」。套图模式要求先挂参考图，张数档位也和自定义生图不同。
5. 看底部那条：按钮上会写明还差什么（「先绑定做图密钥」→「先选一个出图模型」），齐了就变成「生成 N 张」；按钮上方那行是预估消耗，实际以网关扣费为准。
6. 出图过程中按钮变成「取消生成」，进度卡按「这一批试了几张」计数。出好的图落在「本次出的图」里，点开可以看大图、保存到相册。

标题右边的「记录」进历史页：每条记录带时间、张数、是文生图还是图生图，可以「按原参数重做」，也可以「查看提示词」看这次实际发出去的完整提示词。**重做不带图** —— 如果这类图必须挂参考图，App 会先提醒你补上再重做。

> 写着写着切到底栏别的页去，再切回来时草稿和已经加进去的参考图都还在。
> 「清空全部记录」会把记录和已经出好的图一起删掉，不能恢复；要留的图先「保存到相册」。

## 十六、升级

### 手机 App

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

### 电脑端

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

### Codex/ChatGPT 更新后

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

## 十七、故障排查

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

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

### 手机提示连接失败

确认手机和电脑网络互通；关闭手机移动数据测试；检查防火墙和 8787 端口。
异地连接时按你选的那条查：**方式一**——在电脑上 `curl -s -o /dev/null -w "%{http_code}" https://<你的地址>/api/node-status`，
返回 **401** 说明隧道通、在正常要令牌；返回 **530** 说明连接器没在跑（重跑 `tunnel` 安装脚本）；返回 **502** 说明刚掉线，等一分钟。
**方式二**——确认 Tailscale 在电脑端和手机端都已登录同一账号、均显示在线。

### 一直正在排队

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

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

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

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

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

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

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

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

那台电脑上跑的服务太旧。解压新版完整部署包后，Windows 运行 `repair-windows.ps1`，Mac 重新运行 `install-mac.command`，完成后在画面里点“⋯ → 重新连接”。

### 画面卡住或看不清

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

### Windows 防火墙

用管理员 PowerShell 放行：

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

## 十八、安全建议

- 不要把 token 发给不可信的人。
- **不要把 8787 端口直接在路由器上做端口映射**（那才是真正的裸奔）。要异地连，用第九节的**方式一**（专属接入地址，走 Cloudflare 隧道）或**方式二**（Tailscale）。
- **方式一的专属接入地址本身就是钥匙** —— 它形如 `https://k<12位随机>.qiliuapi.com`，那 12 位是随机生成的，别人猜不到就等于进不来。所以**这个地址不要外传**；一旦泄露，联系我们换一条。
  安装脚本已经替你封掉了会泄露配对码的 `/connect` 页面（公网访问返回 403）。**自己验一下**：
  `curl -s -o /dev/null -w "%{http_code}" https://<你的地址>/connect` 必须是 **403**；若返回 200，立刻联系我们。
- 怀疑 token 泄露时，停止服务，删除安装目录中的 `.token`，重新运行安装脚本生成新 token。
- 卸载脚本默认保留数据和 token；确认不再使用后再手动删除安装目录。

## 十九、卸载

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

Windows：

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

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

