系统原理｜Woodox

1. 产品解决什么问题

Codex、Kimi Code 和 Qwen Code 都是命令行 Agent。它们需要读取项目文件、执行命令并维持一个长时间运行的进程。手机不适合直接承载这些工作，因此 Woodox 把职责拆开：

电脑负责执行：保存项目、运行 CLI、执行工具、保存登录状态和会话。
手机负责交互：显示对话时间线、发送输入、上传附件、切换会话和处理确认。
云服务器只负责寻址和转发：仅在离开局域网时使用，不代替你的电脑运行 Agent。

所以手机 App 单独安装后不能直接使用；电脑关机、休眠或后台服务停止时，手机也无法继续连接。

2. 六个组件分别做什么

组件	职责	为什么需要
Windows 桌面客户端	检测环境、启动服务、选择项目、配置端口转发、生成连接信息和管理设备。	把 PowerShell、WSL、Windows 防火墙和图形界面组织成一套可重复流程。
WSL2	在 Windows 中提供带虚拟网络的 Linux 运行平台。	Agent CLI、tmux、bubblewrap 和 Linux 工具链在这里运行；它不是 Ubuntu 本身。
Ubuntu 发行版	提供 Linux 用户、文件系统、apt 软件源和 Shell。	WSL2 是引擎，Ubuntu 是安装在该引擎中的操作系统环境。两者缺一不可。
Agent CLI 与 tmux	Codex/Kimi/Qwen 处理任务；tmux 让受管会话在终端窗口关闭后继续存在。	手机重新连接的是同一受管会话，而不是每次创建一个新的临时命令。
本机 Node.js 服务	在 Ubuntu 中监听 8787，提供鉴权后的 HTTP/WebSocket、历史、附件和会话控制接口。	把终端与结构化事件转换成手机能够稳定使用的协议。
Android App	保存连接记录和本机设备身份，展示实时状态与历史，并把输入送回电脑。	它是电脑端 Agent 的远程交互界面，不保存项目副本，也不在手机执行 Agent。

3. 局域网连接的完整链路

Android 手机同一 Wi-Fi，发送 HTTP / WebSocket

Windows防火墙规则 + netsh portproxy

Ubuntu / WSL2Node 服务监听 0.0.0.0:8787

Agent + tmux读取项目并执行任务

WSL2 默认使用虚拟网卡和 NAT。Ubuntu 常见的 172.x.x.x 地址属于 Windows 内部虚拟网络，手机通常不能直接访问。客户端因此执行两项 Windows 级配置：

查出当前 Ubuntu 的 WSL2 IPv4 地址。
把 Windows 所有网卡上的 0.0.0.0:8787转发到该地址的 8787，并创建 Windows 入站防火墙规则。

# 客户端所做工作的等价形式；不要在未确认发行版和 IP 时照抄
wsl.exe -d Ubuntu --exec hostname -I
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8787 connectaddress=<WSL_IP> connectport=8787

WSL2 的地址可能在关机、wsl --shutdown或网络重建后改变，所以客户端启动/修复时会重新生成转发。手机连接时应使用电脑 WLAN/以太网的 192.168.x.x或10.x.x.x地址，不应手填 WSL 的 172.x.x.x地址。

继续阅读局域网配对和验收方法 →

4. 公网连接的完整链路

Android 手机HTTPS / WebSocket，TCP 443

云端 Nginx / Caddy按设备域名选择 Unix Socket

反向 SSH 隧道电脑主动连云端 TCP 22

Ubuntu 后台鉴权、设备审批、会话控制

电脑主动建立下面这种反向隧道，并在断线后重试：

ssh -N   -o ExitOnForwardFailure=yes   -o StreamLocalBindUnlink=yes   -o StreamLocalBindMask=0117   -o ServerAliveInterval=30   -o ServerAliveCountMax=3   -R /run/codex-mobile-relay/<tenant>/codex-mobile.sock:127.0.0.1:8787   codex-relay-<tenant>

这里的 -R表示监听点创建在云服务器，流量沿 SSH 连接反向回到电脑。家用路由器不需要做端口映射，也不需要让公网直接访问电脑的 8787。云端每台设备使用独立 Linux 身份和独立 Unix Socket，Web 入口根据域名把请求转给对应 Socket。

查看自建服务器、DNS、TLS 和防火墙完整说明 →

5. 对话、终端、app-server 与历史

“把当前终端画面定时截图”只能勉强远程看终端，无法形成接近 ChatGPT App 的交互。当前实现把实时事件、持久历史和断线校正分开处理：

机制	作用	不是用来做什么
实时事件流	新增用户消息、回复、命令、文件修改和状态时立即推送；断线重连先补发内存缓冲事件。	不是反复替换整个页面的“快照”。
分页持久历史	手机向上滚动时按游标读取更早记录；长列表对离屏内容做渲染优化。	不是只保留终端最后 160 行。
状态快照	首次连接、事件缓冲不足或断线后，用当前状态校正是否仍在运行及终端末端。	它是恢复兜底，不是正常对话的唯一来源。
Codex app-server	客户端通过本机标准输入/输出启动 `codex app-server`，读取 Thread/Turn/Item 结构化历史和流式事件。	它不监听局域网/公网端口，不需要个人开发者另建一台 app-server。
终端增量回退	当 app-server 不可用，或使用 Kimi/Qwen 时，根据终端变化保留可滚动历史。	结构会少于 Codex 的消息/工具卡片，但仍可发送、查看和控制终端。

因此“断线后用快照校正”本身没有问题，问题在于不能只靠快照。正常链路应先恢复实时事件，再读取持久历史，最后才用当前快照校正遗漏状态。Codex 结构化历史可区分普通消息、命令、文件修改和工具活动；内部推理正文不进入手机历史。

6. 端口和协议一览

端口/对象	监听位置	用途	是否公开
8787/TCP	Ubuntu 后台；Windows 端口代理	本机 HTTP/WebSocket 与局域网连接	只允许可信局域网；绝不在云安全组开放
22/TCP	云服务器 OpenSSH	电脑发起反向 SSH 隧道	公网可达，但只用密钥和受限账号
80/TCP	云服务器 Nginx/Caddy	HTTP 跳转或 ACME 验证	公网
443/TCP	云服务器 Nginx/Caddy	手机 HTTPS/WebSocket 入口	公网
8790/TCP	云服务器 `127.0.0.1`	账户中心控制服务	不得公开，只由反向代理访问
Unix Socket	`/run/codex-mobile-relay/…`	每个租户/设备的反向隧道入口	不是网络端口，仅本机文件权限可访问

7. 数据保存在哪里

项目文件

仍在 Windows 项目目录或 Ubuntu 文件系统中。手机和中转站不创建完整项目副本。

Agent 登录状态

由对应 CLI 保存在当前 Ubuntu 用户环境；桌面客户端不读取账号密码。

受管会话与历史

位于运行服务的电脑。Codex 的原始 Thread 历史由 Codex CLI 管理，手机端只按需读取。

手机设备身份

保存在 Android 本机，用于重新连接和公网设备审批；卸载/清除数据后会重建。

电脑设备私钥

自建公网时在 Ubuntu 的 ~/.ssh生成，私钥不上传到账户中心。

中转控制状态

保存用户、设备公钥指纹、租户、撤销状态和审计；不应保存 Agent 会话正文。

8. 信任边界与权限

连接安全不是只靠一个二维码。公网路径同时依赖：

TLS：手机验证服务器证书，防止公网链路被直接窃听或篡改。
SSH 密钥与主机指纹：电脑只连接预期服务器，云端只接受已登记设备私钥。
访问 token 与远程保护：后台服务在应用层验证连接凭据。
设备审批：新手机通过公网连接后仍需电脑端允许。
租户隔离：云端账号无 Shell、命令、SFTP、PTY、Agent 转发或任意 TCP 监听能力，只允许指定方向的 Unix Socket 转发。

9. 按层定位故障

排障不要一上来重装全部组件。沿数据流逐层验证，前一层不通就不检查后一层：

Agent 层：在 Ubuntu 中直接运行目标 CLI，确认登录和项目访问正常。
会话层：电脑客户端能新建/继续会话，tmux 中 Agent 正常响应。
本机服务层：概览显示后台在线，Ubuntu 的 8787 正在监听。
Windows 转发层：Windows 8787 有监听，portproxy 指向当前 WSL2 地址，防火墙规则存在。
局域网层：手机和电脑处于可互访网络，没有访客 Wi-Fi/AP 隔离。
公网层：DNS、证书、443 反向代理、Unix Socket 和 SSH 隧道依次正常。
应用鉴权层：访问 token、设备身份和电脑端审批均有效。

这套顺序能区分“Agent 自己未登录”“电脑服务没启动”“局域网不通”和“云中转配置错误”。具体命令见问题排查。