Codex 新手教程 · 环境

Codex 本地、云端和 Remote 应该怎么选

根据代码位置、电脑状态和隔离需求选择运行方式,并在任务开始前核对执行工作的机器与目录。

本篇会为一个任务选定运行位置。最终产物是一张简短决定卡,写清代码在哪里、哪台机器执行、需要哪些工具,以及完成后到哪里看差异。开始任务前再核对一次环境标识,就能减少在错误目录工作的风险。

前置条件

先回答几个实际问题。代码只在你的电脑上,还是已经推到可访问的仓库。任务要不要用本机数据库、模拟器或硬件。你是否会离开电脑。团队有没有配置好的 Codex 云环境。

桌面端创建 Codex 聊天时,常见运行选择包括 Local、Worktree 和 Cloud。Local 与 Worktree 都在你的电脑上运行。Remote 则让手机连接一台受信任的电脑,由那台电脑继续执行任务,代码不会搬到手机里。

Codex 本地、云端和 Remote 应该怎么选的入口、目标与准备条件操作示意图
图 1 · 进入任务前先确认目标、范围和准备条件

选择 Local 的情况

本地任务直接使用当前项目目录,适合依赖本机文件、已经安装的工具和正在运行的服务。你可以马上使用集成终端、审查面板和内置浏览器。代码尚未推送,或任务必须访问本机模拟器时,Local 往往最省步骤。

开始前确认项目主目录。Codex 会沿当前目录到仓库根读取适用的 AGENTS.md,并在这一层级发现 .agents/skills。受信任仓库的项目配置放在 .codex/config.toml,个人配置则位于 ~/.codex/config.toml。可见结果是聊天和终端都显示同一项目路径,规则与配置来源也能说清。

选择 Worktree 的情况

Worktree 是同一台电脑上的隔离 Git checkout,适合并行任务或需要在后台运行、又不想直接改当前目录的工作。它只支持 Git 仓库。创建后先核对独立路径、起始分支和 HEAD;Codex 管理的 worktree 默认可能处于 detached HEAD,而且从带未提交改动的 current branch 启动时,这些改动也可能被带入。准备提交或推送前,在桌面端选择 Create branch here 建立功能分支;也可以先 Hand off 到 Local,再按团队流程交付。

选择 Cloud 的情况

云端聊天会在容器中检出所选分支或提交,运行环境设置里的准备脚本,再由 Agent 编辑并执行检查。任务完成后会显示回复和文件差异。它适合代码已经在仓库里、环境能用脚本重建的工作。

云端 Agent 阶段的网络默认关闭,是否开放由环境设置决定。秘密只提供给准备脚本,Agent 阶段不会继续拿到。任务依赖本机未提交文件、桌面应用或私人硬件时,先别选 Cloud。

Codex 本地、云端和 Remote 应该怎么选的三步关键操作与请求骨架示意图
图 2 · 把关键操作拆成三步,并给每一步留下可观察结果

使用 Remote 的情况

Remote 适合人在手机旁、电脑仍在线的场景。先在桌面端设置中连接自己的 Mac 或 Windows 电脑,再用同一账户和工作区在手机端选择电脑与项目。手机可以发起任务、查看进度、批准请求和检查差异,命令仍在连接电脑上运行。

Remote 需要电脑保持唤醒并联网。移动端显示可用,也要核对选中的电脑和项目。账户或工作区没有入口时,可能是推出进度或管理员设置所限。

用一个小任务验证选择

在选定环境里只做一次只读检查。要求 Codex 报告项目路径、当前分支和可用的项目检查命令,暂时不要改文件。Local 应返回本机目录,Cloud 应能说明检出的分支或提交,Remote 应指出连接的电脑和项目。

用一个日常场景作决定

你正在调整本机尚未推送的页面,还要用浏览器查看已经登录的测试状态。代码、开发服务和页面状态都在当前电脑,先选 Local。决定卡可以写本机项目路径、需要启动的服务、目标路由和审查面板。

另一项任务来自已推送仓库,只需改文档并运行仓库里的检查,环境可以由脚本重建。此时可以选 Cloud,并记录分支或提交与准备脚本。若你将离开电脑,但希望从手机继续观察本地任务,可以使用 Remote,前提是连接电脑保持唤醒和联网。

三个场景都先做只读验证。返回的路径、分支和执行机器必须与决定卡一致。结果不一致就停在这里重新选择,别等产生文件改动后再迁移。

选择还要考虑验收发生在哪里。本机页面需要浏览器和登录状态,就把验收留在 Local。Cloud 任务若只改仓库文件,可以用差异和自动检查验收。Remote 只是远程控制入口,最终证据仍来自连接电脑上的文件、终端和页面。把验收入口写进决定卡,能避免任务做完才发现无法复现结果。

常见失败与恢复

Cloud 找不到本地文件时,先确认文件是否已经进入仓库或环境准备流程。Remote 断开时,回到连接电脑检查睡眠和网络状态。Local 打开了相似项目时,停止任务,从项目设置核对主文件夹。

运行位置选错以后,不要继续靠提示词弥补。保存当前聊天的进度摘要,回到正确环境再开始一个小步骤。

完成检查

决定卡中已经写明代码位置、执行机器、所需工具和验收入口。任务顶部的环境标识与决定一致,只读检查也返回预期路径。到这一步再允许编辑文件。

Codex 本地、云端和 Remote 应该怎么选的结果验收与交付证据清单示意图
图 3 · 用结果、检查与交付证据确认任务真的完成

参考资料