Codex IDE 与 Cloud

IDE 让 Codex 靠近当前选区和文件；Cloud 让任务离开本机并行执行。两者最容易出错的地方不是提示词，而是上下文和运行环境并不相同。

核对日期 2026-07-15 · 依据 OpenAI 当前 IDE、Cloud environment 与 developer settings 文档

什么时候用 IDE

优先用 IDE 的场景：

• 解释当前选区或文件中的逻辑。
• 围绕一个组件、测试或错误快速迭代。
• 需要在编辑器中立即跳转、比较和人工修改。
• 想把选区或整个文件明确加入当前任务上下文。

改用桌面 App 的场景：

• 同时管理多个项目或后台任务。
• 需要完整 Review、集成终端、Worktree、Handoff 或 Scheduled。
• 任务跨越大量模块，更适合保持独立任务窗口。

IDE 第一次任务

1. 打开仓库而不是单个文件

在 VS Code 或兼容编辑器中打开仓库根目录，再打开 Codex 侧栏。项目级 AGENTS.md、.codex/config.toml、Git 状态和测试命令都依赖正确 workspace。

预期结果：Codex 侧栏关联当前项目；在 Git 仓库中可以使用 /review。

2. 明确加入上下文

通过命令面板可以：

• chatgpt.addToThread：把选中文本加入当前任务。
• chatgpt.addFileToThread：把整个文件加入当前任务。
• chatgpt.newChat：新建任务。
• chatgpt.newCodexPanel：打开新的 Codex 面板。
• chatgpt.openCommandMenu：打开 Codex 命令菜单。
• chatgpt.openSidebar：聚焦 Codex 侧栏。

选区只提供局部事实。涉及调用链、状态管理或接口契约时，要求 Codex 继续搜索定义、调用方和测试，不要让它只根据片段猜整个系统。

3. 先解释，再改动

解释当前选中函数的输入、输出、副作用和调用方。
先不要修改。指出它与同目录测试之间的可验证契约，以及你仍缺少的上下文。

确认后：

只修复刚确认的空值边界。保持公开 API、日志字段和错误类型不变。
先补回归测试，再做最小修改；完成后运行相关测试并审查完整 diff。

预期结果：改动集中在目标实现和测试；最终回答列出真实命令与结果。

IDE 设置分两层

层	管什么	放在哪里
Codex agent 设置	模型、推理、sandbox、approval、MCP、个性化	config.toml 和 Codex Settings
编辑器设置	侧栏启动、输入框行为、Review 交付、字体、Windows WSL	VS Code 的 chatgpt.* 设置

从 Codex 侧栏齿轮进入 Codex Settings；常用设置可以在面板中调整，完整配置通过 Open config.toml 编辑。

不要把 chatgpt.* 键写入 config.toml。它们属于编辑器设置系统。

高频编辑器设置：

设置	作用
chatgpt.openOnStartup	编辑器启动后是否聚焦 Codex 侧栏
chatgpt.followUpQueueMode	运行中发送消息时排队还是立即 steer 当前任务
chatgpt.composerEnterBehavior	Enter 与 Cmd/Ctrl+Enter 的发送行为
chatgpt.reviewDelivery	/review 在当前任务内运行，还是创建 detached 任务
chatgpt.runCodexInWindowsSubsystemForLinux	Windows 项目和工具链位于 WSL2 时让 Codex 在 WSL 运行

IDE、App 与子代理

当前官方资料明确了 IDE 的选区/文件上下文、IDE 中的 subagent activity，以及 App 自己的项目与任务界面，但没有承诺所有版本和账号都能在 IDE 与 App 之间自动共享每个活跃任务，也没有把 IDE context 作为通用跨端开关。不要依赖未在当前界面验证的自动续接。

使用原则：

• IDE 需要明确上下文时使用 chatgpt.addToThread 或 chatgpt.addFileToThread，并要求 Codex继续搜索调用方和测试。
• 从 IDE 切到 App，或从 App 切到 IDE 后，重新确认真实路径、Git HEAD、当前 diff 和任务完成标准。
• 同名项目的不同 checkout 或 Worktree 不能仅靠目录名判断。
• 适合并行探索、测试或审查时可以明确要求 subagents；IDE 出现 background-agent 面板时，可展开查看状态、停止活动线程或打开单个线程。
• 子代理继承父任务当前权限并额外消耗 Token；多个子代理不要同时改同一文件集合。

Cloud 与本机有什么不同

Cloud 任务在配置好的远程环境运行。它不是把当前电脑完整复制过去。

项目	Local / Worktree	Cloud
文件来源	当前本地 checkout 或托管 worktree	远程可用的仓库快照与任务输入
未提交文件	Local 可见；Worktree 按创建与 Handoff 规则处理	不应假设自动存在
依赖	使用本机环境或 Local Environment	依赖 setup 脚本和缓存
网络	受本机 sandbox、approval 和策略限制	setup 阶段可安装依赖；agent 阶段默认网络策略更严格，可按环境配置
凭据	来自本机已授权范围	必须单独、安全地配置，不能假设继承本机 shell
运行中的服务	可以连接本地端口	不能直接依赖你电脑上的进程

创建可复现的 Cloud Environment

实际入口与闭环：

1. 打开 Codex environments，确认目标仓库已有环境；没有时在这里创建。
2. 选择仓库并配置运行时版本、setup 脚本、可选 maintenance 脚本、环境变量、setup-only secrets 和 agent 网络范围，然后保存。环境配置变化后缓存会自动失效，也可以在环境页手动 Reset cache。
3. 在 Codex cloud 新任务中选择目标仓库与分支或提交基线，确认匹配到预期环境，再提交一个只读检查提示词。
4. 任务完成后先看回答和完整 diff。结果可继续追问、从 Cloud 打开 PR，或在本地目标仓库使用 codex apply 应用最近的 Cloud diff；应用前仍要核对分支、已有修改和冲突。

账号、工作区或仓库权限不具备 Cloud 时，环境入口或可选仓库可能不可见。这不是本地 API Key 能自动解锁的能力。

一个可靠环境至少定义：

1. 仓库与基线： 任务从哪个仓库、分支或提交开始。
2. Setup： 安装依赖、生成代码和准备测试数据的可重复命令。
3. 运行时： 语言、包管理器、系统依赖和必要环境变量。
4. 网络： agent 阶段真正需要访问的域名和方法。
5. 验证： 测试、lint、类型检查、构建和产物检查。
6. 凭据： 区分普通环境变量与 setup-only secrets，不写进仓库和日志。

Cloud 的变量生命周期很容易配错：

类型	Setup 阶段	Agent 阶段	适用
Environment variable	可用	可用	agent 运行时确实需要的非敏感配置
Secret	可用	会被移除	仅安装依赖或 setup 下载私有资源时使用

Setup 在独立 Bash 会话中运行，因此仅在脚本里 export NAME=value 不会延续到 agent 阶段。需要贯穿任务的值应在 Environment settings 中配置；只给 setup 使用的凭据才放 Secrets。不要为了让 agent 读取凭据而把 secret 写入仓库、缓存产物或日志。

第一次使用 Cloud 时先跑只读任务：

不要修改文件。报告当前提交、可用运行时、依赖安装状态、环境变量名称（不要输出值）、网络限制和可执行的验证命令。

预期结果：你能把远程环境与本机差异列出来，再决定是否适合实现。

Cloud 失败分支

现象	常见原因	下一步
本机通过，Cloud 找不到命令	setup 未安装依赖或 PATH 不同	从锁文件和项目脚本重建 setup，记录版本
找不到本机未提交文件	Cloud 没有当前 checkout 临时状态	提交到任务分支，或把必要补丁明确交给任务
下载依赖成功，任务阶段访问 API 失败	setup 与 agent 阶段网络策略不同	只允许必要域名；不要直接开放无限网络
测试连接到错误服务	远程环境变量或 endpoint 不同	输出变量名与目标环境，禁止打印 secret 值
Setup 能认证，Agent 阶段却是 401	凭据放在 Secrets，任务阶段已被移除	判断 agent 是否真的需要凭据；需要时改用受控环境变量和最小权限账号
Setup 中 export 后任务仍找不到变量	Setup 与 Agent 是独立 Bash 会话	在 Environment settings 配置，不依赖临时 shell export
结果无法在本机应用	基线变化、冲突或生成物差异	先检查 patch、基线提交和锁文件，再人工解决冲突

选择 Local、Worktree 还是 Cloud

• 需要当前本地服务、数据库、设备或未提交文件：选 Local。
• 想在同一台电脑隔离 Git 修改并行工作：选 Worktree。
• 任务可从清晰仓库基线开始、依赖可脚本化、适合远程并行：选 Cloud。
• 无法说清环境差异时，先不要上 Cloud；把本地流程做成可复现脚本后再迁移。

官方资料

• IDE commands
• IDE settings
• Environment modes
• Cloud environments
• Agent internet access