Codex 桌面 App 完整操作
桌面 App 的价值不是把终端换成聊天框，而是把项目、任务、diff、终端和并行工作区放进同一条可审查流程。
核对日期 2026-07-15 · 依据 OpenAI 当前官方 Codex 手册 · 当前模型基线 GPT-5.6
开始之前
准备以下条件：
- ChatGPT 桌面 App 中可以选择 Codex。
- 项目是你信任的本地目录；需要 Review 或 Worktree 时应是 Git 仓库。
- 你知道项目的安装、测试和构建命令，或允许 Codex 先从仓库文件中确认。
- 工作区没有未识别的敏感文件；真实 Key 不出现在截图和提示词中。
App 不等于无限权限
App 能看到哪些目录、能否写入、是否能运行命令和访问网络，仍受当前项目、sandbox、approval、系统权限和组织策略限制。
当前模型：GPT-5.6
OpenAI 当前模型页在 ChatGPT 桌面 App、Codex CLI 和 IDE 扩展中推荐 GPT-5.6 系列。默认 Power 档使用 gpt-5.6-sol 和 Medium reasoning；需要更快或更低成本时再向 Faster 调整，只有明确需要时才进入 Advanced 固定具体模型。
| 模型 | 适合 |
|---|---|
| 5.6 Sol | 复杂、开放式、高价值任务，需要更强分析、判断和交付质量 |
| 5.6 Terra | 日常开发、代码探索和工具调用，在能力与成本间取平衡 |
| 5.6 Luna | 边界明确、可重复、高吞吐任务，优先速度与成本 |
旧模型边界
使用 ChatGPT 登录时，gpt-5.2 和 gpt-5.3-codex 已被 Codex 标记为弃用。本版不再发布显示 GPT-5.2-Codex 的旧 App 图。API Key 或自定义模型提供方是否仍支持旧 ID 是另一套可用性判断，不能从 ChatGPT 登录状态直接外推。
认识四个核心区域
| 区域 | 主要用途 | 你要检查什么 |
|---|---|---|
| 项目与任务侧栏 | 切换项目、搜索任务、管理并行工作 | 当前项目、任务名称、是否进错仓库 |
| 任务记录与输入框 | 描述目标、查看工具动作、追加约束 | Codex 正在读什么、改什么、运行什么 |
| Review 面板 | 查看 Git diff、行内反馈、stage、unstage 或 revert | 改动是否越界，哪些修改原本就存在 |
| 底部面板与终端 | 运行验证、查看本地服务或命令输出 | 命令目录、退出码、错误是否被忽略 |
常用快捷键：
| 动作 | macOS / Windows |
|---|---|
| 打开文件夹 | Cmd/Ctrl + O |
| 新任务 | Cmd/Ctrl + N |
| 搜索历史任务 | Cmd/Ctrl + G |
| 任务内查找 | Cmd/Ctrl + F |
| 打开 Review | Ctrl + Shift + G |
| 切换底部面板 | Cmd/Ctrl + J |
| 切换终端 | `Ctrl + `` |
| 打开设置 | Cmd/Ctrl + , |
快捷键可以在 Settings > Keyboard Shortcuts 中搜索、修改或恢复默认值。
流程一：在 Local 完成一次小改动
1. 打开正确项目
- 在 ChatGPT 桌面 App 的产品下拉框选择 Codex。
- 按
Cmd/Ctrl + O，选择仓库根目录，而不是它的上级目录。 - 新任务输入框下方选择 Local。
- 开始前让 Codex 报告当前目录、Git 分支和未提交文件。
选择前先分清运行位置：Local 直接在当前项目目录工作，Worktree 在本机 Git worktree 中隔离修改，Cloud 在已配置的云环境中远程运行；Local 和 Worktree 都在你的电脑上运行。
预期结果：任务绑定到本地 checkout；Review 能识别仓库状态。
失败分支：
- 看不到 Review：项目可能不是 Git 仓库，或打开的不是仓库目录。
- 项目路径不对：关闭当前任务并重新打开目录，不要继续授权写入。
- 存在陌生未提交修改：暂停，让 Codex 只读说明它们，不要自动清理。
2. 先调查，再让它动手
先不要修改。检查登录页提交逻辑、对应请求封装和现有测试。
复现“连续点击登录会发出重复请求”的问题，给出：
- 已确认事实；
- 仍待验证的假设；
- 最小修改方案；
- 需要运行的验证。预期结果：先出现文件读取、搜索和必要的只读命令；在你确认方案前没有源代码 diff。
如果 Codex 过早修改，直接输入：
停下。先说明已经改了哪些文件，恢复到调查阶段；不要覆盖我原有的修改。3. 审批工具动作
审批前逐项看：
- 动作是什么： 读文件、写文件、运行命令还是访问网络。
- 范围在哪里： 是否仍在当前仓库，是否扩大到上级或其他目录。
- 为什么需要： 是否直接服务于当前任务。
- 后果是什么： 会不会删除、覆盖、提交、推送、安装全局软件或访问账号。
对 git status、读取项目文件和已知测试命令可以更快确认；对删除、回滚、仓库外写入、发布、推送和凭据访问保持人工确认。
4. 在 Review 面板检查完整 diff
- 打开 Review 面板。
- 先看 Unstaged；需要时切换 Staged、Commit、Branch 或 Last turn。
- 展开每个文件，检查是否有无关格式化、依赖更新、调试日志或敏感内容。
- 对具体行悬停并选择
+，留下行内反馈。 - 发送明确跟进：
处理行内评论，保持改动范围不变；完成后重新验证。
预期结果：你能把每一处改动对应到原始需求。Review 展示整个仓库的 Git 状态，并不只包含 Codex 产生的修改。
Revert 前先辨认所有者
Review 支持按整个 diff、文件或 hunk stage、unstage 和 revert。Revert 会丢弃对应修改；如果其中包含你原先的工作，不能直接执行。
5. 在集成终端验证
从右上角终端按钮或 `Ctrl + `` 打开终端。终端跟随当前 Local 或 Worktree 项目。
git status --short --branch
npm test -- --runInBand
npm run typecheck
npm run lint只运行项目真实存在的命令。先从 package.json、Makefile、任务配置或项目文档确认，不要照抄示例。
验证完成后要求 Codex 报告：
- 实际执行的命令和退出结果；
- 哪些检查没有执行以及原因；
- diff 中每个文件的作用；
- 仍需人工检查的界面或外部系统状态。
流程二：用 Worktree 隔离并行任务
Worktree 适合后台开发、实验或当前 Local 已有未完成工作时的独立任务。
创建 Worktree 任务
- 新任务输入框下选择 Worktree。
- 选择起始分支；它可以是
main、功能分支或当前带未提交改动的分支。 - 如项目需要依赖安装，选择已经配置好的 Local Environment。
- 提交任务。Codex 默认在托管 worktree 的 detached HEAD 上工作。
预期结果：侧栏出现独立任务；Local checkout 不直接出现该任务的文件修改。
在 Worktree 创建分支
- 先在 Worktree 的集成终端或 IDE 中验证改动。
- 确认要继续保留这份工作后，在任务头部选择 Create branch here。
- 在对话框中确认分支名并创建分支。
- 继续在这个 Worktree 中提交、推送或创建 Pull Request；只在你确认改动和远端目标后执行这些动作。
同一个 Git 分支不能同时签出到 Local 和另一个 Worktree。需要回到日常本地环境时，使用 Handoff，不要在两个 checkout 中强行切到同一分支。
Hand off 到 Local
- 在 Worktree 任务头部选择 Hand off，目标选择 Local。
- 在对话框中确认要接收任务的本地 workspace。
- 完成交接后，在熟悉的本地 IDE、开发服务或终端中继续检查和验证。
- 之后若 Hand off 回 Worktree，任务会回到原来关联的 Worktree。
Handoff 会处理在两个 checkout 之间移动任务和代码所需的 Git 操作。被 .gitignore 忽略的文件不会随任务移动，除非它们按官方规则通过 .worktreeinclude 复制到本地托管 Worktree。
常见失败
| 现象 | 原因 | 处理 |
|---|---|---|
| 项目不能选择 Worktree | 不是 Git 仓库，或当前没有选择 Codex | 确认 Git 根目录和产品入口 |
| 新 worktree 缺依赖或本地配置 | Git 只带 tracked 文件 | 配置 Local Environment；只对确有必要的忽略文件使用 .worktreeinclude |
| 分支无法在 Local checkout 切换 | 同一分支已经被另一个 worktree 使用 | 使用 Handoff，或让两个 worktree 使用不同分支 |
| 两个任务仍互相影响 | 共用了数据库、端口、缓存或外部账号 | 分配独立端口、测试数据和外部资源 |
.worktreeinclude 不是密钥同步清单
官方支持把必要的忽略文件复制到托管 worktree，但列入 .env 或 secret 文件会扩大暴露面。优先使用测试凭据、短期凭据或环境初始化方式，并确保文件永不进入 Git。
流程三：让 /review 做专门审查
在 Git 仓库任务中输入 /review，按需要选择：
- Review against a base branch：检查当前分支相对基线的完整变化。
- Review uncommitted changes：检查 staged、unstaged 和 untracked 修改。
- Review a commit：检查一个明确提交。
- Custom review instructions：只关注权限、并发、数据一致性等标准。
审查任务应要求每个发现包含严重程度、文件位置、触发条件和影响。对没有证据的风格偏好不做“问题”报告。
审查结果默认出现在当前任务；可在设置中把 Code review 调整为单独任务。无论哪种模式，审查本身不会自动修改工作树；要求修复后仍会遵守现有 sandbox 和 approval。
流程四：用 Subagents 并行调查
在 App 任务中明确要求 Codex 把互不依赖的读密集工作交给 subagents，例如一个检查安全、一个找测试缺口、一个核对文档。App 会显示子代理 thread，主任务在它们完成后汇总结果。
把这次审查分给三个 subagents：安全与权限、行为回归、测试缺口。
只读，不修改文件。等全部完成后去重，并按严重程度汇总带文件位置的发现。打开每个 thread 检查证据，不只看主任务摘要。子代理继承当前 permission mode 并各自消耗 Token；多个 agent 同时写同一 Worktree 容易冲突，所以 App 中也应优先并行探索、测试与审查，写入任务要先划分互不重叠的文件范围。
流程五：配置 Local Environment
Local Environment 只在 ChatGPT 桌面 App 的 Codex 中使用，通过 App 设置配置，并保存到项目根目录的 .codex 文件夹；需要团队复用时可以把不含凭据的配置提交到仓库。
它包含两类行为，不能混为“每个 Local 任务都会自动运行”：
- Setup scripts：仅在 Codex 为新任务创建新 Worktree 时自动运行，用于安装依赖、生成代码或做初始构建。
- Actions：显示在 App 顶栏，由用户手动触发，在当前项目的集成终端中运行，例如启动开发服务或执行测试。
配置并运行一个 Action：
- 确认桌面 App 当前选择的是 Codex，并打开项目根目录。
- 打开 App 设置，为这个项目配置 Local Environment；配置文件会保存在项目根目录的
.codex文件夹。 - 在 Actions 中添加常用命令，例如把项目真实存在的启动命令配置为
Run，把测试命令配置为Test。 - 如果命令在 macOS、Windows 和 Linux 上不同，分别配置对应平台脚本；为 Action 选择容易辨认的图标。
- 回到任务，从顶栏选择该 Action。它会在当前项目的集成终端中运行；检查命令、工作目录、输出和退出结果。
设置原则：
- setup 只做可重复、可审查的准备工作。
- 不把长期密钥硬编码进脚本或文档。
- 常用测试、开发服务和格式化命令做成明确 Action，需要时人工调用。
- setup 失败时保留原始输出，不让任务在半配置状态继续修改。
终端和 Codex agent 的环境可能不同；出现“终端能运行、任务里找不到命令”时，检查 shell 初始化、PATH 和 Local Environment 设置。
流程六：创建 Scheduled 任务
Scheduled 适合周期性、结果可复核的工作，例如每天汇总失败测试、每周检查依赖公告或定期生成只读报告。
创建前先确认：
- 任务是否可以在无人即时监督时安全运行。
- 本地 Git 项目使用 Local 还是 Worktree，以及依赖是否可复现；不要把 Cloud 当成本地计划任务的运行位置。
- 运行时电脑是否保持开机、ChatGPT App 是否保持运行、项目路径是否仍可访问。
- 需要的网络、插件和账号权限是否最小化。
- 失败后输出保存在哪里，谁负责处理。
- 是否可能重复写入、重复通知或产生费用。
从 App 的 Scheduled 入口创建任务，写清频率、工作项目、目标、允许动作和成功标准。第一次先手动运行同一提示词并检查完整结果，再启用周期执行。
WARNING
本地 Scheduled 在 Git 项目中只选择 Local 或独立 Worktree；非 Git 项目直接在项目目录运行。它会无人值守地使用默认 sandbox。组织允许时通常采用 approval_policy = "never"，超出 sandbox 的动作会失败，不会停在那里等待一次性人工审批。网页 Scheduled 可以使用上传内容、连接工具和插件，但不能直接访问电脑上的本地文件夹。
账号套餐、工作区策略和项目类型仍可能影响可用性。涉及发布、付款、删除或生产变更的任务不应只靠定时提示词控制。
搜索、恢复和管理任务
Cmd/Ctrl + G搜索历史任务；当前版本可能同时匹配任务内容和 Git 分支名。Cmd/Ctrl + F只在当前任务内查找。- 重要任务可以置顶；完成任务应归档，避免侧栏失去可读性。
- 已归档任务可在 Settings > Archived tasks 中恢复。
- 任务名称写结果而不是写工具，例如“修复登录重复提交”，比“Codex 测试”更容易搜索。
Appshots：把前台窗口交给任务
macOS 的 Appshots 可以把当前最前面的 App 窗口作为附件加入任务。适合展示错误、设置页、设计稿或预览状态。
- 把需要分享的窗口放到最前面。
- 按两个 Command 键，或使用你在设置中定义的 Appshots 快捷键。
- 检查系统的 Screen Recording 和 Accessibility 授权请求。
- 发送前确认画面和可读取文本没有邮箱、账号、密钥或私人数据。
Appshot 只应提供当前任务真正需要的范围。CLI 可以继续包含 Appshot 的历史任务，但不能创建新的 Appshot。
App 交付检查清单
- 当前交互任务使用了正确项目和 Local / Worktree / Cloud 环境；本地 Scheduled 只使用 Local / Worktree。
- 所有权限请求都能解释为什么需要。
- Review 中没有无关文件、密钥、生成物或调试代码。
- 测试命令在当前环境真实运行，退出结果被记录。
- Worktree 任务说明了分支、Handoff 和外部资源隔离状态。
- 没有把 stage、commit、push 或发布误当作“代码已完成”的必要自动步骤。