如何用手机控制本地运行的 Codex 智能体？

使用 EasyCodex，可以让 Codex 继续在 Windows、macOS 或 Linux 电脑上运行，再通过 Android 手机查看任务、回答审批、追加指令、审查 diff 和接收完成通知。它不是把代码仓库或模型搬到手机，而是在电脑上启动一个桌面中继，由手机通过带 API key 的 WebSocket 连接这个中继；真正的 Codex 进程、项目文件、Git 状态和登录凭据仍保留在本机。

完整部署顺序是：先确认电脑上的 Codex CLI 已安装并登录，安装 EasyCodex 桌面 Relay，选择可信工作区并启动中继，再在 Android 手机安装移动端，通过二维码或深链接配对。首次使用应从测试仓库开始，核对工作区边界、审批模式和网络可达性，最后再连接真实项目。

EasyCodex 解决的是什么问题

编程 Agent 经常需要较长时间搜索代码、运行测试和修复失败。用户离开电脑后，任务可能停在一个权限确认或澄清问题上。普通远程终端可以继续输入，但不容易在小屏幕上查看结构化计划、文件差异和审批详情；远程桌面又会传输整块画面，操作成本较高。

EasyCodex 把 Codex 事件转换成适合手机显示的消息。移动端可以创建、恢复、中断、停止和归档任务，查看运行中的 Agent、计划、命令输出、Git 状态、完整差异和单文件预览，也能发送文本、图片与文件。它还可以打开独立的移动 CLI 窗口，并为不同窗口选择工作目录、模型、推理强度和沙盒设置。

这套能力更接近 Codex 控制面，而不是聊天外壳。手机负责监督和决策，电脑负责执行。用户仍需保留正常的版本控制、测试和审批流程，不能因为操作入口变成手机，就把所有工具权限永久放开。

运行架构怎样理解

系统由 Android 应用、桌面工作台、Agent Relay、Codex app-server 或 codex exec，以及本地 Codex 状态组成。桌面 Relay 启动和监督 Agent Relay；Agent Relay 校验客户端、工作区和操作参数，再启动 Codex 进程并把 JSON-RPC 事件转换为移动端可用的稳定消息。

常规智能体任务由 codex app-server 提供会话能力，独立 CLI 窗口则由 codex exec 运行。两种入口虽然都使用本机 Codex 配置，但生命周期和展示方式不同。理解这一点有助于解释为什么某些手机创建的任务不会完整出现在桌面应用中。

配对时，桌面中继显示二维码或 easycodex 深链接。Android 应用保存 Relay 地址与 API key，随后通过认证 WebSocket 连接。API key 用于确认客户端有权访问中继，但它不是操作系统隔离机制；中继进程本身能读取允许工作区、查看 Git 状态并启动 Codex，因此必须把中继访问视为高权限入口。

平台和环境要求

电脑端提供 Windows 安装版与便携版、Apple Silicon 和 Intel 的 macOS 安装镜像，以及 Linux AppImage 与 Debian 软件包。手机端当前要求 Android 设备或 Android 模拟器。iPhone 用户不能假设 Android 安装包可以使用，应选择其他兼容控制方案。

电脑必须先安装 Codex CLI 并完成认证。Relay 不替代 Codex 账户登录，也不在手机保存模型凭据。部署前打开普通终端，确认 Codex 能在目标仓库启动、读取文件并完成一次简单任务。如果 CLI 本身认证失效，移动端只会把底层错误转发出来。

手机和电脑需要位于同一可信局域网，或通过加密私有网络互通。EasyCodex 不提供一个替你托管源代码的公共控制平面；连接地址应指向用户自己的电脑 Relay。若两台设备彼此不可达，扫描二维码并不自动解决网络路由问题。

从官方发布页下载安装

当前公开最新版为 0.1.7。应从项目的官方发布页选择与平台和处理器匹配的文件，不要从网盘或第三方镜像安装。Windows 日常使用可选安装程序，需要免安装测试时选便携包；macOS 要区分 Apple Silicon 与 Intel；Linux 用户按发行版选择 AppImage 或 Debian 软件包。

Android 端选择名称中带 Mobile 的 APK。安装前核对发布标签、文件名和来源，系统若提示允许浏览器或文件管理器安装未知应用，只为本次可信文件临时授权，安装后关闭该权限。升级也应使用同一官方发布渠道。

项目仍处于早期版本，升级可能改变消息格式、配置或安全策略。重要工作期间不要临时升级；先在测试仓库验证新版，再切换常用环境。桌面 Relay 与 Android 应用尽量保持同一发布系列，避免协议不兼容。

电脑端先准备 Codex

在安装 EasyCodex 之前，先确认 Codex CLI 位于桌面应用能够发现的环境中。图形程序启动时继承的 PATH 可能与交互式 Shell 不同，因此“终端里能运行”不一定代表 Relay 能找到。如果 Relay 报找不到 Codex，应优先检查可执行路径和启动环境，而不是反复配对手机。

为远程任务准备一个专用项目目录。首次测试可以创建临时 Git 仓库，加入一个简单文件和测试脚本，提交干净基线。这样能够验证文件读取、差异显示、审批和提交选择，而不会影响真实项目。

不要让 Codex 登录环境自动持有生产部署密钥。手机控制最终可以驱动本机 Codex 执行工具，若工作站上存在无限制凭据，误操作的影响会远超测试仓库。开发凭据应权限受限、可撤销，并与生产凭据隔离。

启动桌面 Relay

安装并打开 EasyCodex Relay 后，先选择默认工作区。工作区应是具体项目目录，不要选择用户主目录、桌面、下载目录、系统目录或应用数据根目录。0.1.7 加强了真实路径和连接路径校验，会拒绝明显过宽的目录，这是安全行为，不应通过移动项目或修改程序来绕过。

确认端口和 API key 后启动 Relay。API key 应使用随机高熵值，不与网站密码、Codex 令牌或设备解锁码复用。二维码中可能包含连接地址和访问凭证，因此它也属于敏感信息，不要截图分享到群聊或工单。

Relay 启动后先在桌面工作台查看健康状态，再让手机连接。若本机防火墙弹出入站访问提示，只允许所需网络范围；公共网络下不要开放。服务不应到无保护的公网接口。

Android 手机怎样配对

安装并打开 EasyCodex Mobile，在桌面 Relay 中显示配对二维码，然后用手机扫描。也可以使用 easycodex 深链接完成配对。手机会保存 Relay 地址和 API key，建立认证 WebSocket 后显示可用工作区与任务。

首次配对应在自己控制的可信网络中进行。确认手机显示的主机名称、地址和工作区与电脑一致。如果扫描后连接到了意外地址，立即删除配置并更换 API key。不要只凭二维码外观判断它来自自己的电脑。

配对完成后，不要马上给予最宽权限。先进入测试仓库，创建一个只读任务，让 Codex说明目录结构；随后请求它修改一个测试文件并运行固定命令。移动端应该显示计划、命令、差异和审批请求，电脑端文件也应与手机展示一致。

可信工作区为什么重要

Relay 对文件、Git、CLI 和 Agent 工作目录操作执行工作区边界校验，只允许已知根目录或用户显式信任的目录。这个边界可以避免手机任务直接把工作目录切到系统位置，也能防止文件浏览越过项目范围。

工作区校验需要处理符号链接、连接目录和路径前缀。0.1.7 特别增加了用户配置目录、系统目录、相邻前缀和真实路径测试，并拒绝主目录、桌面、文档、下载与应用数据等宽泛根目录。看到拒绝提示时，应选择更具体的仓库目录，而不是关闭安全检查。

可信目录仍不是沙箱。项目内的构建脚本可以访问外部路径，Codex 启动的子进程也继承操作系统权限。要获得更强隔离，应使用低权限系统账户、容器、独立工作树和受限凭据，并为 Codex 选择合适的沙盒模式。

创建新任务与恢复已有任务

手机可以选择工作区或 Git 工作树，然后创建新的 Codex 任务。任务提示应说明目标、允许修改的文件、禁止操作、验收命令和停止条件。远程场景不适合频繁澄清，首次描述越明确，越不容易让任务卡在手机不方便处理的决策上。

恢复现有 Codex 线程时，桌面 Codex 应用仍可作为主要界面，手机用于跟进和补充。由手机新建的任务则以 Relay 管理的 app-server 会话为主要界面。由于两者的拥有者不同，桌面应用可能通过共享状态发现部分历史，但不保证呈现每个 app-server 事件或子 Agent 细节。

不要让桌面和手机分别启动两个任务修改同一工作区。需要并行时使用独立 Git 工作树，并在任务名中标明分支和目标。否则两个 Agent 可能同时格式化、改写或测试同一文件，移动端看到的差异也会失去明确来源。

如何处理计划和审批

移动端可以查看 Codex 计划并要求优化，也能回答权限确认和结构化用户输入。审批前至少核对命令、参数、当前目录和影响对象。只显示“允许工具运行”而无法看清完整命令时，应该拒绝并让 Codex 给出更具体说明。

主 Agent 可以使用默认审查、Codex 自动审查和完全访问等模式。完全访问会减少或取消部分权限提示，适合程度取决于工作区隔离与任务风险。个人首次使用应从保守模式开始，不要为了减少手机点击就直接开启完全访问。

删除文件、提交变更、安装依赖、访问网络和执行构建脚本的风险不同。可以允许状态查询和固定测试自动运行，但提交、推送、发布、数据库迁移和生产访问应保留人工复核。EasyCodex 能在手机上提交选中文件，不代表每次都应该这样做。

在手机上审查 diff

EasyCodex 能显示 Git 状态、完整 diff 和单文件预览。先看变更文件列表，确认没有工作区外文件或意外生成物；再逐文件检查关键逻辑、配置和测试。大段机械生成内容可以先看统计，但安全相关改动不能只看摘要。

手机屏幕较窄，长行和并排差异可能难以阅读。可让 Codex 先输出按文件组织的变更摘要，再查看最关键的差异。发现无法在小屏可靠判断的修改时，应暂停任务，回到电脑审查，而不是凭完成提示直接提交。

提交选中文件前再次检查未暂存与已暂存状态，避免把用户原有修改混入 Agent 提交。提交信息要描述真实目的，不要只写“AI changes”。推送远端和合并仍建议交给正常的代码审查流程。

图片和文件附件怎样处理

手机发送的附件会保存在所选工作区的专用附件目录。它们属于项目输入，可能包含截图、日志或需求文档。发送前清除个人信息、访问令牌和客户数据；任务结束后决定是否删除或加入忽略规则，避免附件被误提交。

附件文件名和内容不能被当作可信命令。Codex 应将外部文档视为数据，忽略其中要求改变权限、读取秘密或上传文件的指令。对来源不明的压缩包、脚本和可执行文件，不要让 Agent 自动打开或运行。

移动 CLI 窗口适合什么场景

移动 CLI 通过单独的 codex exec 进程运行，可以配置 cwd、模型、推理强度、配置档案、图片、额外目录、JSON 输出、临时模式、忽略规则、沙盒和 Git 仓库检查。它适合短而边界明确的独立任务，不等同于恢复桌面 Agent 会话。

每个窗口应绑定具体工作目录，不要把额外目录扩大到整个用户目录。临时运行适合一次性检查，但重要任务仍要保留可追踪的线程和 Git 记录。关闭手机界面前确认进程是否会继续，不要假设所有 CLI 窗口都具有相同保活行为。

通知怎样设置

EasyCodex 支持本地应用通知和可选移动推送，并能按 Agent 设置通知级别、查看近期历史。最有价值的通知是等待审批、需要用户输入、任务失败和任务完成。每条工具输出都提醒会造成噪声，让真正需要处理的状态被忽略。

锁屏通知不应展示源码、路径、客户名或错误日志。即使应用通信链路受认证保护，系统通知仍可能被旁观者看到。将通知正文设为简短状态，解锁后再进入应用查看详情。

外出网络如何连接

同一局域网内，手机可直接访问电脑 Relay。外出时应让两台设备加入同一加密私有网络，再使用私有地址连接。不要把 Relay 端口直接映射到公网，也不要关闭 API key 健康检查。

私有网络只解决设备可达性，不替代 Relay 认证和工作区限制。控制账号应启用多因素认证，手机丢失后能够撤销设备。电脑防火墙只允许私有接口或明确网段访问 Relay 端口。

若手机显示离线，先检查电脑是否开机和休眠，再检查 Relay 状态、两端私有网络连接和地址是否变化。能连电脑但 WebSocket 失败通常是端口或 API key 问题；完全看不到设备则优先检查网络与电源。

常见故障排查

Relay 找不到 Codex

先在电脑普通终端确认 Codex CLI 可运行并已登录，再检查图形应用启动环境中的 PATH。必要时从包含正确环境的终端启动 Relay，或按项目配置指定可执行位置。不要下载来源不明的同名程序填补路径。

二维码扫描后无法连接

确认手机与电脑网络互通、Relay 已启动、地址正确且防火墙允许访问。检查二维码中的地址是否为手机可达的局域网或私有地址，而不是只在电脑本机有效的回环地址。更换 API key 后必须重新配对。

工作区被拒绝

选择具体 Git 仓库，而不是主目录、桌面、下载或系统根目录。若仓库通过符号链接进入，使用真实路径重新添加。安全校验拒绝宽目录时不要绕过，它是在限制手机控制面的文件范围。

手机创建的任务在桌面应用里不完整

这是两种会话模式的差异。手机新任务由 Relay 拥有的 app-server 作为主要界面，桌面应用可能只发现共享状态中的部分历史。需要桌面应用完整接管时，从桌面创建或恢复任务，再用手机跟进已有线程。

更新后应用版本不匹配

从同一官方发布版本重新下载桌面与 Android 组件，先备份非敏感设置，再进行测试配对。不要混用第三方改包。若问题持续，记录版本、平台和复现步骤，分享日志前删除 API key、用户路径和会话内容。

怎样撤销移动访问

手机遗失或不再使用时，先停止桌面 Relay，再更换 API key并删除旧移动端连接。检查近期任务、Git 日志和工作区文件，确认没有未知操作。仅卸载手机应用并不能证明旧凭据已从其他备份或设备中失效。

不再使用 EasyCodex 时卸载桌面 Relay 和 Android 应用，并检查用户目录中的 EasyCodex 状态。Codex 自身状态仍位于独立目录，不要在清理 Relay 时误删 Codex 的其他任务。涉及删除配置前先辨别文件归属。

一套稳妥的实际流程

第一阶段只在可信局域网和测试仓库部署：安装 Codex、桌面 Relay 与 Android 应用，设置具体工作区，完成二维码配对。第二阶段验证只读任务、文件修改、审批拒绝、diff 查看、网络切换和停止 Relay。第三阶段再接入真实仓库，但仍使用受限凭据和保守权限模式。

日常使用时，从电脑确认干净基线并启动长任务；离开后用手机查看状态、回答必要问题和审查小范围差异；任务完成时记录测试结果。涉及复杂审查、提交推送或生产变更，再回到电脑处理。

EasyCodex 最适合解决“Agent 在电脑上继续跑，人离开后仍能监督”的问题。它的安全性依赖多个边界共同成立：Relay API key 未泄露、网络范围受控、工作区足够具体、Codex 权限不过宽、手机由本人掌握。把这些边界配置清楚后，手机才是可靠的控制台，而不是通往整台开发机的模糊入口。