第一次打开 Codex 桌面 App，最容易卡在眼前这些区域各管什么：项目和任务有什么区别？新建任务时 Local、Worktree、Cloud 该选哪个？Plan 什么时候该开？权限给到哪一档？Plugins、Skills、MCP 为什么同时存在？

这篇文章按实际操作顺序整理，先讲清界面布局、工作区选择、权限控制与 Diff 审查，再讨论扩展功能什么时候值得接。文中包含排错提示、上手练习与手绘图解，帮你快速建立可落地的操作直觉。

一、先认清 Codex 到底能做什么

Codex 是 OpenAI 推出的桌面执行型 Agent。它不仅能给出文字回复，还能直接读取本地文件、修改代码和文档、在终端运行命令、查看 Git 改动、通过内置浏览器审查网页，并调用配置好的外部工具。

给 Codex 分配任务，需要具备三项基本输入：

  1. 明确材料：任务所需文件集中在工作区内，不需要跨目录搜寻；
  2. 清晰边界：明确说明修改哪些文件、禁止碰哪些文件；
  3. 可验证标准：给出具体的验收指标，例如“单元测试全部通过”或“页面在 375px 宽度下无横向滚动条”。

如果只发一句“帮我改一下登录页”，它容易自行扩散修改范围；如果改为“修复登录页报错：错误提示居中显示，表单提交后跳转到首页，保持现有测试通过”，执行边界就清晰得多。涉及敏感账号凭据、外部公开账单支付或需要人为主观拍板的决策，不要直接交给它自动运行。

四步循环：Prompt → Plan → Execute → Verify

Codex 的基本执行逻辑由四个环节构成：

Prompt 提出任务，Plan 规划步骤，Execute 读写文件并运行命令，Verify 检查结果。第四步是整个流程的关键：Codex 回复“已完成”只代表它结束了当前轮次的动作，并不证明逻辑正确、构建成功或页面可用。

例如让它“把文章里所有英文引号替换成中文引号”，它跑完脚本后汇报完成，但可能漏掉了 Markdown 表格里的内容。这类遗漏模型通常不会主动发现，必须由人工在 Diff、本地服务或测试中验证。

五个入口的选择

Codex 提供五个运行入口：命令行 CLI、桌面 App、IDE 插件、Chrome 扩展和云端会话。

  • 桌面 App 提供完整的图形化工作台，包含项目管理、任务并行、Diff 查看与内置浏览器；
  • 习惯在终端工作的开发者可以选择 CLI；
  • 需要在写代码时顺手调用的使用 IDE 插件；
  • 需要操作在线 SaaS 应用的使用 Chrome 扩展；
  • 不想占用本机资源的长任务使用云端会话。

刚接触时建议先从桌面 App 熟悉基本逻辑，后续按工作流补充对应入口。

上手练习：查看项目结构

  1. 打开 Codex App，添加一个熟悉的本地文件夹；
  2. 新建一个任务，输入：“读取当前目录结构，说明每个主要文件夹的用途。只做分析，不要修改任何文件”；
  3. 观察它读取了哪些路径、执行了什么命令；
  4. 检查右侧 Diff 面板：未修改文件的任务，Diff 面板应为空。

排错：初次运行常见问题

  • 找不到目录：确认添加项目时选择的本地路径真实存在且具备读取权限；
  • 频繁弹出权限请求：这是默认安全策略在生效，优先选择最窄的批准范围，不要直接开启全局权限。

二、Codex App 界面结构

Codex App 的窗口主体分为三栏：左侧管理项目与任务，中间处理对话与执行控制，右侧审查文件变动。

左侧：项目和任务

  • 项目（Project）：对应电脑上的一个工作目录。添加项目相当于确定了 Codex 的默认读取范围和沙盒写入边界。单个 App 窗口支持添加多个项目并随时切换；
  • 任务（Thread）：项目下的一条具体对话线。建议每个任务只针对一个确定目标，例如“修复导航栏折叠 Bug”或“整理接口文档”。

当旧任务已经产生大量无关上下文、且新需求与之前没有连续性时，建议新建任务，避免历史对话干扰判断。如果只是对当前修改做微调，直接在原任务中跟进。

左侧常用操作：

  • 添加或切换项目；
  • 新建任务或查看历史任务；
  • 检查运行中、等待审批或已结束的任务状态；
  • 将任务弹出为独立窗口，方便分屏对照代码或浏览器。

中间：对话区与控制台

中间区域展示 Codex 的完整执行记录：读取的文件路径、执行的 Shell 命令、工具调用、权限审批弹窗以及阶段性总结。

底部的输入框兼具任务控制台的功能：

  • 发送 / 停止：提交指令或随时中断当前执行；
  • 模型切换：选择处理当前任务的基础模型；
  • 权限设置：在只读、工作区可写等权限档位间切换；
  • 附件：添加图片或参考文档作为上下文；
  • 语音输入：按住 Ctrl+M 录音转文字；
  • 工作模式：在 Local、Worktree、Cloud 之间选择运行位置。

在执行过程中不必等待完全结束才纠正。如果发现它正在改动无关文件，可以直接发送补充要求，例如“停止修改样式，只修复逻辑判断”。

右侧：Diff 与文件审查

右侧 Diff 面板展示当前任务产生的所有文件变更，通常绿色表示新增，红色表示删除。支持按单个文件查看，也支持查看整个任务累积的改动。

Diff 面板主要功能：

  • 查看所有未提交的代码变动；
  • 在具体的代码行旁添加 inline 评论；
  • 暂存、撤销特定文件或改动块；
  • 直接在界面内完成 Commit、Push 或创建 Pull Request。

需要修改局部代码时，在 Diff 面板的那一行留下一条行内评论，再在输入框补充：“按刚才的 inline 评论修改，其他部分不要变动”，比在对话框里长篇描述修改位置更准确。

上手练习：行内评论修改

  1. 在测试项目中让 Codex 把 README.md 的第一行标题改为指定名称；
  2. 执行完毕后，在右侧 Diff 面板查看改动行；
  3. 点击该行旁边添加评论，例如“调整为二级标题”；
  4. 发送“处理刚才的 inline 评论，不要修改其他文件”，验证它是否准确修改。

排错：界面显示异常

  • Diff 面板为空但提示已改动：确认任务是否已真正完成，并检查顶部的 Diff 筛选条件（“本轮改动”与“整体分支改动”）；
  • 任务停滞：检查中间区域是否有等待审批的权限弹窗，未处理的审批会导致任务一直处于等待状态。

三、工作区选择与目录边界

工作区是 Codex 在本次任务中的活动目录。选错目录往往会导致找不到文件、改错位置或读取过多无用上下文。

最小目录原则

选择工作区时，将范围限制在完成该任务所需的最小文件夹内。不要将包含多个不相关项目的上级目录或整台电脑的根目录直接添加给 Codex。目录越大，它读取的无关材料越多，模型上下文越容易被稀释，误操作的影响范围也会成倍增加。

常见场景建议：

  • 独立项目：打开该项目的根目录；
  • 多包仓库（Monorepo）：将各个独立的子应用或子包分别添加为单独的项目；
  • 前后端分离但放在相邻目录：以主要修改的一方作为项目目录，需要时通过配置追加另一个目录的读取权限；
  • 纯分析任务：打开目标目录，并将权限模式切换为 Read-only；
  • 需要隔离环境的大型任务：选择 Cloud 模式，而非在本地放开整机权限。

在 CLI 中，可以使用 –cd 指定当前任务目录，使用 –add-dir 追加允许访问的外部目录。运行 /status 可以随时确认当前工作区包含的具体路径。

排错：目录相关问题

  • 提示找不到文件：通过 /status 或项目设置核对工作区根路径，确认目标文件是否包含在当前目录下；
  • 改动扩散到其他工程：工作区设得太宽，应立即中断任务，重新将工作区收敛到目标子项目。

四、新建任务模式：Local、Worktree、Cloud

新建任务时，需要决定它在哪里运行。这直接决定改动落在哪里，以及是否会对当前工作目录产生影响。

\1. Local：直接修改当前目录

Local 模式直接在选定的本地项目目录内读写，改动实时体现在你的本地文件中。

  • 适用场景：日常单任务修 Bug、写文档、运行测试、调整脚本；
  • 注意：如果你和 Codex 同时在本地编辑相同的文件，可能会互相覆盖。单人单任务直接用 Local 最方便。

\2. Worktree：基于 Git 的隔离工作区

Worktree 模式利用 Git 原生的 git worktree 能力，在后台克隆一份独立的工作副本。Codex 在隔离副本里修改，不会改动你正在编辑的本地目录。

  • 适用场景：多个任务并行修改同一个仓库、尝试具有不确定性的实验性改动；
  • 关键机制：Worktree 只包含 Git 已跟踪提交的文件，未加入版本控制的本地文件与第三方依赖（如 node_modules、Python 虚拟环境）默认不会自动带过去。官方文档建议为项目配置 setup 脚本，在新建 Worktree 时自动执行依赖安装；
  • 任务归宿：任务完成后，可以在隔离目录里建分支提 PR，也可以使用 Handoff 功能将改动合回主目录。

\3. Cloud：云端沙盒运行

Cloud 模式将仓库克隆到云端隔离容器中执行，无需消耗本地算力。

  • 适用场景：耗时较长的异步任务，如全面代码审查、批量重构、大规模测试套件运行；
  • 注意：云端无法访问你本机的未提交修改，也无法直接调用本地桌面应用。任务完成后在 Diff 视图审查并创建 PR。

模式选择速查

任务类型 推荐模式 说明
改文档、修单个 Bug、跑局部测试 Local 本地实时可见，链路最短
多个任务同时改同一个仓库 Worktree 隔离运行，避免文件冲突
实验性重构、验证不确定方案 Worktree 不破坏当前分支，可随时丢弃或合并
耗时较长的全库审查、批量重构 Cloud 云端异步跑，不占本机资源
强依赖本机环境与桌面应用 Local / Worktree 云端无法直接接管本机应用状态

排错：模式运行问题

  • Worktree 提示缺少依赖或构建失败：Git worktree 默认不复制未提交文件与依赖包，在项目配置中加入 setup 脚本（例如 npm install 或环境配置命令），确保新建 worktree 时自动补全环境；
  • Cloud 任务完成后本地没有代码：Cloud 任务需要通过 Pull Request 或合并操作将远端改动拉回本地。

五、Plan 的使用原则与方法

Plan（执行计划）用于在动手之前理清修改范围和操作步骤。

Plan 的作用

对于复杂的跨文件修改，Plan 可以提前暴露三个隐患：

  1. 范围泛化：打算修改超出预期的文件；
  2. 步骤颠倒：未调查原因就先做破坏性改动；
  3. 冗余依赖：无故引入不必要的第三方包。

在 CLI 中可以使用 /plan 命令，在 App 中可以直接提出：“先列出执行计划，明确改动文件和验收方法，确认后再执行”。

什么时候开启，什么时候跳过

  • 建议开启：涉及 3 个以上文件、改动难以直接撤销、原因尚不明确的排查、需要对比不同技术选型；
  • 建议跳过：修改拼写、调整单个函数的局部逻辑、运行一条确定的命令。方案已经明确的简单操作开启 Plan 只会增加交互步骤。

有效 Plan 的四个要点

一份具有参考价值的计划需要交代清楚：

  1. 解决什么具体问题（目标明确）；
  2. 参考哪些已有文件（输入明确）；
  3. 改动哪几个具体文件（范围受控）；
  4. 如何证明改动生效（测试命令或验收指标）。

如果计划仅包含“1. 分析需求；2. 编写代码；3. 进行测试；4. 总结汇报”等泛化描述，直接要求其补充具体文件列表和验证手段。

寻找最短可靠路径

能用已有函数实现就不重新封装，能改单行逻辑就不重构整个模块，能一条命令验证就不新建测试项目。编写 Plan 是为了选择最高效的实现方案，避免为简单问题搭建复杂流程。

六、权限控制与审批弹窗处理

Codex 拥有读写文件和执行终端命令的能力，权限设置直接决定了操作的安全底线。

沙盒的三种级别

  • Read-only：只读模式，禁止修改任何文件和执行破坏性命令。适合代码审计、需求分析与阅读学习；
  • Workspace-write：工作区写入模式，允许修改当前项目目录内的文件并在沙盒中运行命令。这是大多数日常工作的默认推荐档位；
  • Full access：完全访问模式，允许突破工作区边界访问系统其他路径。仅在明确需要跨多个硬盘目录操作时临时使用。

即使在 Workspace-write 模式下，系统对 .git/ 和 .codex/ 路径依然默认保持只读保护，因此执行 git commit 等操作时仍可能触发安全确认。

审批弹窗的四项核对

当界面弹出权限请求时，确认以下四项信息：

  1. 查命令：将要执行的具体 Shell 脚本或操作；
  2. 查目录：命令在哪个文件夹路径下执行；
  3. 查网络：是否包含外网请求或向外部上传数据；
  4. 查必要性：该动作是否为达成当前目标所必需。

安装系统级依赖、删除文件、修改全局环境变量或涉及认证凭据的操作均需审慎确认。遇到“批准一次”与“为本次会话批准”选项时，如果不确定后续影响，优先选择“批准一次”。

运行时调整权限

执行过程中如需调整权限，输入 /permissions 即可随时在 Auto、Read Only 等预设之间切换。

参数 –dangerously-bypass-approvals-and-sandbox（包含早期版本的 –full-auto 或 –yolo）会跳过所有沙盒保护与审批确认，官方明确建议仅在专用的隔离虚拟机内使用，不要在日常开发环境中作为默认配置。

排错：权限受阻处理

  • 权限弹窗过于频繁：通常是由于工作区目录设得过大、或者任务频繁发起网络请求所致。收紧工作区路径并在 Prompt 中明确“不需要联网”；
  • 操作被拒绝：检查是否试图修改 .git/ 等受保护的系统目录，如需访问外部文件夹，使用 –add-dir 显式增加授权目录。

七、扩展功能分工：Skill、Plugin、MCP、Automation、/goal

这五个扩展功能各自处理不同的协同需求：

\1. Skill：固化一类任务的操作规范

Skill 是指导 Codex 执行特定任务的操作指引，核心是 SKILL.md 文件，包含触发条件、操作规范、调用模板和执行脚本。

  • 调用方式：通过

    $skill-name

    显式触发，或由系统根据指令意图隐式匹配；

  • 存放位置：个人通用 Skill 放在本地用户目录，团队共享 Skill 放在仓库的 .agents/skills/ 目录；

  • 使用建议：只有在工作中反复出现、有固定格式与质量要求的任务（如周报生成、PR 审查、特定框架的发布流程），才值得沉淀为 Skill。

\2. Plugin：跨工作区的能力扩展包

Plugin 是面向 App 和 CLI 的分发包，一个插件可以同时打包多个 Skills、MCP 服务的配置以及第三方连接器（Connectors）。在 App 的 Plugins 面板或 CLI 中输入 /plugins 即可浏览安装。常见插件如连接 Jira、GitLab、Slack、Google Drive 等平台。

\3. MCP：打通外部工具与数据源

MCP（Model Context Protocol）是外部服务与 Codex 交互的统一通信协议。接入 MCP 服务后，Codex 可以调用其提供的接口读写外部数据。

  • 常见 MCP：查询官方文档的 OpenAI Docs MCP、读取设计稿的 Figma MCP、控制浏览器的 Playwright MCP、读取线上监控异常的 Sentry MCP；
  • 管理方式：CLI 中使用 codex mcp add 添加，使用 /mcp 查看当前会话的连接状态。

\4. Automation：按时自动唤醒的定时器

App 内置的定时任务调度系统，适合定期执行巡检、未来特定时间运行或分步推进的后台任务。

  • 设置步骤：选择项目 → 编写执行 Prompt → 设定触发时间与周期 → 选择 Local 或 Worktree 环境 → 确认权限；
  • 建议：Git 仓库建议配合 Worktree 模式运行定时任务，避免后台执行污染你正在编辑的本地文件。

\5. /goal：跨会话维护的长周期目标

适用于需要分多次对话、跨多天完成的长线工程。/goal 能在清理对话历史或切换上下文时保持核心目标不丢失。设定的目标需要有明确的完工边界，例如“迁移所有旧组件并保证测试通过”，避免使用“持续维护项目”这种无终止条件的模糊目标。

八、从入门到熟练的四阶段路径

学习使用 Codex 建议遵循渐进式节奏，逐步解锁进阶功能：

第一阶段：掌握基础边界

  • 正确配置工作区目录；
  • 掌握 Local 模式的基本操作；
  • 熟悉 Read-only 与 Workspace-write 权限差异；
  • 养成通过 Diff 面板审查每轮改动的习惯。

第二阶段：引入规划与代码审查

  • 对跨文件修改先列出 Plan 再确认执行；
  • 使用内置终端（macOS 快捷键 Cmd+J）运行本地测试与编译；
  • 执行 /review 启动独立审查会话检查改动质量。

第三阶段：开启多任务与隔离

  • 遇到需要试错或并行的需求，启用 Worktree 模式；
  • 在隔离副本中验证改动，确认无误后通过 PR 或 Handoff 合回主干。

第四阶段：按需工程化扩展

  • 将团队长期规范和构建指令写入 AGENTS.md；
  • 将重复工作流沉淀为 Skill；
  • 对接特定数据源时引入 MCP；
  • 安排周期性巡检时配置 Automation。

常用命令与快捷键速查

功能 操作入口
指定工作目录 CLI 启动参数 –cd <路径>；追加目录 –add-dir <路径>
查看工作区状态 命令行输入 /status
进入规划模式 输入 /plan 或直接说明“先给计划”
改动审查 输入 /review（开启审查代理）或 /diff（查看变更）
调整权限 输入 /permissions（在预设策略间切换）
清除上下文 输入 /clear（Ctrl+L 仅清屏，不清除上下文）
引用工作区文件 输入框输入 @ 检索并插入文件路径
直接运行 Shell 命令 输入框输入 ! 加具体命令
运行中追加要求 Codex 运行过程中按 Enter 键发送补充提示
排队下一轮要求 运行过程中按 Tab 键排队后续指令
重新编辑上一条输入 在空输入框连按两次 Esc
语音输入 按住 Ctrl+M 说话，松开后自动转文字
打开任务集成终端 macOS 快捷键 Cmd+J
管理 MCP 服务 命令 codex mcp list、codex mcp add，会话中输入 /mcp
管理插件 访问 App 中的 Plugins 面板或输入 /plugins