一教程定位很多开发人员第一次接触 Codex会把它理解为一个更强的代码补全工具写一个用户注册接口。然后直接让 Codex修改项目。这种使用方式虽然可能快速生成代码但很容易出现没有先理解现有项目 没有确认功能边界 修改范围过大 重复实现已有能力 没有创建独立分支 没有运行完整测试 测试失败后仍然提交 生成代码无法解释和追踪 多个并行任务互相覆盖Codex 工程化使用的重点不是生成了多少代码而是建立一套稳定工作流分析 ↓ 计划 ↓ 编码 ↓ 测试 ↓ 审查 ↓ 提交本篇将介绍 Codex 的主要产品形态并建立适合真实项目的基础开发模式。二教程信息目标读者Codex 初学者、开发人员、DevOps 工程师 预计时长约 1 小时 难度等级★☆☆ 案例项目城市随手拍平台三学习目标完成本篇后你应该能够理解 Codex CLI、IDE、桌面应用和云端任务的区别 判断一个任务应该本地执行还是云端委派 理解本地任务对当前仓库和开发环境的依赖 理解云端任务的隔离运行方式 建立分析—计划—编码—测试—提交工作流 避免让 Codex 在没有边界的情况下直接修改项目 完成一次小型功能的完整开发闭环 检查 Codex 的代码变更和测试证据第一部分Codex 是什么四Codex 不只是代码生成器Codex 是面向软件开发工作的智能编码 Agent。它可以在获得授权的环境中读取项目文件 理解代码结构 搜索调用关系 修改代码 新增文件 执行终端命令 运行单元测试 运行 Lint 和类型检查 检查 Git Diff 分析报错 审查代码 准备 Commit 或 Pull RequestCodex 可以在本地工具中与你配合也可以接收任务后在云端环境中独立执行。官方将其定位为帮助开发人员编写、审查和交付代码的编码 AgentCLI 和 IDE 可以在仓库中读取文件、修改代码、运行命令和执行测试。([OpenAI Help Center][1])因此Codex 更接近可以操作开发环境的虚拟工程师而不是只根据一段描述输出代码片段的聊天机器人五Codex 的能力边界Codex 很适合理解陌生项目 实现范围明确的小功能 修复可复现的 Bug 补充单元测试 重构局部代码 更新依赖 生成迁移脚本 检查 Pull Request 分析错误日志 更新技术文档Codex 不应该在没有人工控制的情况下直接承担未经评审的生产数据库变更 使用生产管理员凭证 直接修改 main 分支 执行不可逆数据删除 跳过测试强行发布 自行决定重大架构迁移 删除无法理解的历史代码Codex 可以执行复杂任务但最终代码仍需要开发人员审查和验证。OpenAI 官方也建议用户检查 Agent 生成的代码、终端日志和测试结果再决定是否合并。([OpenAI][2])第二部分Codex 的主要产品形态六产品形态总览目前可以把 Codex 的常用形态分为形态运行位置主要特点适合任务Codex CLI本地终端接近真实开发环境命令能力强后端、脚本、测试、构建IDE 扩展VS Code 等编辑器可使用打开文件和选中代码作为上下文日常编码、局部修改桌面应用中的 Codex本地电脑多任务、Worktree、Diff、终端统一管理多 Agent 和并行项目Codex Cloud云端沙箱独立环境执行可并行委派长任务、独立修复、PRGitHub 代码审查GitHub PR自动检查变更和潜在回归团队代码审查这些形态不是相互替代关系而是面向不同开发场景。七Codex CLICodex CLI 运行在终端中。典型工作方式cd city-snapshot-platform codex进入项目后可以让 Codex阅读仓库 搜索代码 编辑文件 执行 npm、pnpm、mvn、pytest、go test 等命令 检查 Git 状态 生成和审查修改Codex CLI 是开源命令行工具可以在本地读取、修改和运行代码。当前官方安装方式之一是npm install -g openai/codex([OpenAI Help Center][3])CLI 的优势与真实构建环境接近 可以直接运行项目命令 方便查看终端输出 适合 Linux、WSL2 和服务器开发 适合后端与基础设施项目 容易接入脚本和 CI/CDCLI 的不足不如 IDE 直观 需要熟悉终端 多个任务同时运行时管理成本较高 查看复杂 Diff 不如图形界面方便推荐使用场景后端接口开发 数据库迁移 Docker 构建 测试和构建失败修复 批量代码修改 项目结构分析 自动化脚本八Codex IDE 扩展Codex IDE 扩展可以在 VS Code、Cursor、Windsurf 等兼容编辑器中使用。它可以结合当前打开的文件、选择的代码和编辑器上下文完成任务也能够查看本地修改并衔接云端任务。([OpenAI Help Center][1])IDE 的优势可以边看代码边提问 可以选择具体代码作为上下文 修改前后差异更直观 适合局部功能开发 适合前端和组件开发 人工调整更加方便IDE 的不足大型终端任务不如 CLI 直接 多个并行任务仍可能争用同一工作区 开发人员容易只关注当前文件忽略全局影响推荐使用场景修改一个 React/Vue 组件 调整接口参数 修复 TypeScript 类型错误 补充局部测试 解释当前文件 进行小范围重构九桌面应用中的 Codex截至 2026 年 7 月Codex 已包含在新的 ChatGPT 桌面应用中支持 macOS 和 Windows。原独立 Codex 应用更新后会转为包含 Chat、Work 和 Codex 的新桌面应用。([OpenAI Help Center][4])桌面应用适合把 Codex 作为多个开发 Agent 的管理中心。它支持按项目管理任务 同时运行多个 Agent 查看代码 Diff 查看终端和测试输出 使用 Git Worktree 隔离任务 在编辑器中继续修改 管理 Skills 和自动化任务桌面应用内置 Worktree 支持可以让多个 Agent 在同一仓库的隔离副本中并行工作降低修改互相覆盖的风险。([OpenAI][5])桌面应用的优势图形界面直观 适合多任务管理 适合长时间任务 Worktree 隔离方便 查看 Diff 和任务历史清晰桌面应用的不足复杂命令仍需要理解终端结果 多个 Agent 并行会增加合并成本 没有良好任务拆分时容易产生重复代码推荐使用场景前端、后端、数据库并行开发 同时处理多个 Bug 为不同方案建立独立任务 运行较长的重构任务 管理多个项目十Codex CloudCodex Cloud 适合把任务委派给云端 Agent。云端任务会在独立沙箱中运行并加载指定仓库和配置好的开发环境。Agent 可以读取和修改代码、运行测试、Lint 和类型检查任务完成后开发人员可以审查变更、继续修改、创建 Pull Request或者将结果拉回本地。([OpenAI][2])典型流程选择仓库和分支 ↓ 提交任务说明 ↓ 云端创建隔离环境 ↓ Agent 修改代码并执行测试 ↓ 输出 Diff 和执行证据 ↓ 开发人员审查 ↓ 创建 PR 或拉回本地云端任务的优势不占用本地终端 可以并行运行多个任务 每个任务环境相互隔离 适合等待时间较长的任务 方便生成 Pull Request 不会直接扰乱本地工作区云端任务的不足需要正确配置云端开发环境 依赖、环境变量和服务可能与本地不同 访问内网数据库和内部服务需要额外配置 任务范围不明确时可能产生较大修改 最终仍需人工审查推荐使用场景修复独立 Bug 补充大量测试 更新一批重复代码 依赖升级 文档更新 代码审查 明确边界的重构第三部分本地任务与云端任务十一什么是本地任务本地任务是指 Codex 直接在你的电脑、WSL2、远程开发机或 IDE 工作区中执行。它使用的是当前真实环境本地源码 本地 Git 分支 本地安装的依赖 本地数据库或 Docker 本地环境变量 本地网络 本地测试命令例如请分析当前项目为什么启动失败并运行实际启动命令验证。这种任务需要访问当前电脑的.env Docker 容器 本地数据库 企业内网服务 尚未提交的代码因此更适合本地执行。十二什么是云端任务云端任务运行在独立环境中不直接使用你的当前本地工作区。它更适合代码已经推送到仓库 任务不依赖本地未提交文件 测试环境可以通过脚本重建 任务边界清晰 可以独立产生一个 PR例如在当前仓库中为用户 Service 补充单元测试 要求覆盖手机号重复、密码为空和注册成功场景。 不要修改生产代码除非测试暴露真实缺陷。十三本地与云端选择规则优先使用本地任务当任务涉及尚未提交的代码 本地 Docker 服务 内网数据库 本地设计稿 需要频繁人工调试 需要立即查看浏览器效果 当前机器独有的工具链优先使用云端任务当任务满足代码已经推送 任务可以独立完成 开发环境可以自动安装 测试可以在沙箱中执行 希望并行处理 希望直接生成 PR推荐判断方式是否依赖本地未提交内容 是 → 本地是否依赖本地服务或内网资源 是 → 本地或远程开发机是否能通过仓库脚本重建环境 是 → 可以云端是否适合单独形成一个 PR 是 → 优先云端是否需要频繁人工视觉调整 是 → IDE 或桌面应用十四常见错误选择错误一把依赖本地数据库的任务交给云端结果云端没有数据库 迁移无法运行 集成测试失败 Agent 只能猜测错误二在本地同时启动多个任务修改同一分支结果文件互相覆盖 Git Diff 混在一起 测试结果无法归属 Commit 难以拆分解决使用独立分支 使用 Git Worktree 或把独立任务委派到云端错误三云端任务没有配置安装脚本结果依赖不存在 测试无法启动 构建环境与项目要求不一致错误四认为云端完成就可以直接合并云端完成表示Agent 已完成其认为正确的修改不表示代码一定满足业务要求 代码一定没有安全问题 代码一定适合生产第四部分标准工程化工作流十五分析—计划—编码—测试—提交模型推荐把所有 Codex 开发任务拆成五个核心阶段分析 ↓ 计划 ↓ 编码 ↓ 测试 ↓ 提交复杂项目可以增加审查 发布 验证形成分析 ↓ 计划 ↓ 编码 ↓ 测试 ↓ 审查 ↓ 提交 ↓ 发布十六阶段一分析分析阶段只理解问题不修改文件。需要确认用户需求是什么 当前功能是否已经存在 相关代码在哪些目录 涉及哪些接口 涉及哪些数据库表 有哪些测试 有哪些公共模块 可能影响哪些功能 当前工作区是否干净推荐提示词请先分析当前任务不要修改任何文件。任务为城市随手拍平台增加手机号格式校验。请输出当前手机号处理逻辑所在位置。已有注册接口和验证逻辑。可能需要修改的文件。已有测试情况。对其他功能的影响。风险和不确定项。建议实施方案。所有结论必须基于实际代码。 无法确认的内容标记为待确认。分析阶段的验收没有修改文件 没有安装依赖 没有创建无关文件 能够指出实际代码位置 能够说明影响范围 没有凭空假设项目结构十七阶段二计划计划阶段把需求转化为可执行步骤。一个合格计划应包含修改文件 新增文件 数据库变化 接口变化 测试范围 执行顺序 风险 验收标准推荐提示词基于刚才的分析输出实施计划暂时不要修改代码。计划必须包含修改范围。每个文件的修改目的。实施顺序。测试方案。回归范围。不会修改的模块。完成验收标准。本任务只做手机号格式校验 不增加短信验证码 不修改登录流程。计划阶段需要阻止的问题顺便重构整个用户模块 顺便更换验证框架 顺便修改登录接口 顺便升级全部依赖计划必须与当前任务范围保持一致。十八阶段三编码编码阶段按照计划逐步修改。推荐原则一次完成一个可验证的小步骤 优先复用项目现有模式 不擅自更换技术方案 不修改无关代码 不删除无法理解的逻辑 新增行为必须补充测试编码提示词按照已确认的计划开始实现。要求只修改计划中列出的文件。使用项目现有验证方式。不引入新的生产依赖。不修改登录和密码逻辑。补充手机号合法和非法场景测试。每完成一个阶段汇报修改结果。暂时不要 Commit。十九阶段四测试Codex 完成编码后不能只做静态说明。必须运行项目真实命令例如npm run lint npm run typecheck npm test npm run build或者mvn test mvn package或者pytest ruff check . mypy .推荐提示词实现完成后执行验证。请先检查 package.json 和项目文档 确认项目真实可用的命令。依次运行与当前功能相关的单元测试。完整单元测试。Lint。类型检查。构建。如有失败分析失败原因。只修复与本次修改有关的问题。重新执行失败命令。不得隐藏、跳过或删除失败测试。最后输出每条命令、退出码和结果。不允许的测试报告测试应该可以通过。由于时间原因未运行测试。从代码上看没有问题。合格的测试报告npm test -- user-register.test.ts 退出码0 结果8 个测试通过npm run typecheck 退出码0npm run build 退出码0二十阶段五审查和提交提交前检查git status git diff --stat git diff需要确认当前分支正确 只有当前任务相关修改 没有 .env 和 Secret 没有调试日志 没有无关格式化 没有大范围锁文件变化 测试已经通过用户当前的工程规则是新功能分支 fea-{功能简介拼音}允许 自动 Commit 自动 Push禁止 直接修改 main Force Push 测试失败后提交 自动合并 main推荐提示词请执行提交前检查。要求输出当前分支。执行 git status。执行 git diff --stat。检查是否有无关修改。检查是否包含 Secret。汇总测试结果。确认全部通过后只添加当前功能相关文件。使用 Conventional Commit。自动 Commit。自动 Push 当前功能分支。禁止 Force Push。禁止合并 main。最后输出分支名称Commit messageCommit IDPush 结果测试结果第五部分不同产品形态的推荐工作流二十一CLI 工作流进入项目目录 ↓ 检查 Git 状态 ↓ 启动 Codex ↓ 分析仓库 ↓ 输出计划 ↓ 创建功能分支 ↓ 修改代码 ↓ 执行测试 ↓ 检查 Diff ↓ Commit 和 Push适合后端开发 脚本任务 数据库迁移 工程配置 Docker 项目二十二IDE 工作流打开项目 ↓ 选择相关文件或代码 ↓ 让 Codex解释调用关系 ↓ 确认修改范围 ↓ 进行局部修改 ↓ 在 IDE 查看 Diff ↓ 运行测试 ↓ 提交适合前端组件 类型修复 局部重构 接口调整 代码解释二十三桌面应用工作流添加项目 ↓ 为每个功能建立独立线程 ↓ 为并行任务创建 Worktree ↓ 让多个 Agent 独立执行 ↓ 分别审查 Diff 和测试 ↓ 选择保留的方案 ↓ 合并到目标功能分支适合并行开发 多方案探索 多个 Bug 修复 长任务管理二十四云端工作流推送基础分支 ↓ 创建边界明确的云端任务 ↓ 配置安装和测试环境 ↓ Agent 在隔离环境执行 ↓ 查看执行日志和测试 ↓ 审查 Diff ↓ 要求继续修改或创建 PR ↓ 人工合并适合独立测试补全 文档更新 依赖升级 可隔离 Bug 批量但规则明确的修改第六部分一小时实操二十五实操任务本次使用一个低风险任务为城市随手拍平台后端添加健康检查接口。接口要求GET /health返回{ status: UP, service: city-snapshot-api }要求不访问数据库 不需要登录 不修改业务接口 补充接口测试 测试通过后提交功能分支二十六时间安排010 分钟选择使用形态推荐后端项目 → Codex CLI 前端局部调整 → IDE 并行多个任务 → 桌面应用 独立测试补全 → Cloud本次使用Codex CLI 或 IDE 本地任务1020 分钟分析请先分析当前后端项目不修改文件。目标增加 GET /health 健康检查接口。请确认后端技术栈。路由或 Controller 目录。统一响应格式。测试框架。需要修改的文件。是否已有类似接口。2030 分钟计划请输出健康检查接口的实施计划不修改代码。约束GET /health。不要求登录。不访问数据库。不新增生产依赖。返回 status 和 service。补充自动化测试。不修改其他业务接口。3045 分钟编码按照计划实现健康检查接口。要求使用项目现有路由和响应方式。只修改必要文件。添加自动化测试。暂时不要 Commit。4555 分钟测试和审查请执行健康检查接口相关测试。完整测试。Lint。类型检查。构建。然后执行git status git diff --stat git diff输出实际命令和结果。5560 分钟提交功能分支fea-jiankangjiancha提交要求Commit feat: add application health check endpoint提交提示词确认测试全部通过且没有无关修改后当前分支必须为 fea-jiankangjiancha。只添加当前功能相关文件。Commit message feat: add application health check endpoint自动 Push 当前分支。禁止 Force Push。不要合并 main。输出 Commit ID 和 Push 结果。第七部分任务完成报告二十七标准完成报告模板Codex 完成任务后应输出完成内容新增 GET /health。返回应用健康状态。添加接口测试。修改文件src/...tests/...测试结果npm test通过npm run typecheck通过npm run build通过Git分支fea-jiankangjianchaCommitabc1234Push成功风险当前接口只检查应用进程不检查数据库和 Redis。二十八人工验收清单开发人员最后检查接口地址是否正确 是否无须登录 是否意外访问数据库 返回结构是否符合要求 测试是否真实运行 是否修改无关代码 是否在正确功能分支 是否已经 Push 是否没有提交 Secret第八部分常见错误二十九上来就让 Codex修改代码错误给项目加上健康检查。更好先分析现有路由、响应格式和测试框架 输出计划后再实现健康检查。三十一个任务包含多个目标错误增加健康检查、重构用户模块、升级依赖并修复所有警告。应该拆成任务 1健康检查 任务 2用户模块重构 任务 3依赖升级 任务 4警告清理三十一没有说明禁止事项如果没有边界Codex 可能增加新框架 修改公共返回格式 格式化大量文件 升级锁文件 重写已有模块任务中应明确不新增依赖 不修改公共接口 不重构无关模块 不修改生产配置三十二只看结果不看过程不能只看任务完成。应查看修改文件 Git Diff 测试命令 测试输出 退出码 Commit 远程分支三十三把所有任务都交给云端以下任务通常更适合本地依赖本地数据库 依赖本地 Docker 依赖当前未提交代码 需要频繁视觉调整 需要企业内网服务三十四在同一工作区并行修改多个 Codex 任务同时修改同一目录时容易产生代码覆盖 冲突 测试混乱 提交污染应使用不同分支 Git Worktree 桌面应用隔离工作区 云端独立任务第九部分企业使用原则三十五Codex 不应绕过现有工程流程Codex 应遵守需求评审 分支策略 代码规范 测试要求 Pull Request 代码审查 CI/CD 生产审批不应因为使用了 Agent就取消测试 审查 权限控制 变更记录 回滚方案三十六先把项目变得适合 Agent一个适合 Codex 的项目通常具备清晰 README 明确启动命令 可靠测试 统一目录结构 AGENTS.md 独立开发分支 可重复安装环境 稳定构建命令云端和本地 Agent 都更依赖良好的环境配置、测试和项目文档。官方也建议使用AGENTS.md告知 Codex 如何导航仓库、执行测试和遵守项目规范。([OpenAI][2])三十七工程化使用核心原则简单任务可以直接执行 复杂任务必须先分析 大范围修改必须先计划 所有功能必须独立分支 所有修改必须运行测试 所有提交必须可审查 所有失败必须如实说明 所有生产操作必须有人类审批第十部分练习与验收三十八练习一选择正确产品形态为下列任务选择 Codex 形态任务 A修复当前本地 Docker 环境中的数据库连接错误。推荐CLI 本地任务任务 B修改当前 Vue 页面按钮布局。推荐IDE 或桌面应用任务 C为 30 个工具函数补充单元测试。推荐Codex Cloud任务 D前端、后端和数据库三个模块并行开发。推荐桌面应用 Worktree三十九练习二完成健康检查接口验收已完成分析 已输出计划 已创建 fea-jiankangjiancha 已实现 GET /health 已添加测试 测试通过 已检查 Diff 已自动 Commit 已自动 Push 未修改 main四十本篇验收标准完成本篇后应达到已理解 Codex 是编码 Agent而不只是代码补全工具 已理解 CLI、IDE、桌面应用和 Cloud 的区别 已能区分本地任务和云端任务 已知道什么时候使用 Worktree 已掌握分析—计划—编码—测试—提交工作流 已能要求 Codex先分析再修改 已能检查测试证据和 Git Diff 已完成一个小型功能闭环 已理解 Agent 结果仍然需要人工审查四十一本篇总结需要重点记住CLI 适合终端和工程任务 IDE 适合局部编码和交互修改 桌面应用适合多 Agent、Worktree 和多项目管理 Cloud 适合隔离、并行和可独立审查的任务 依赖本地环境的任务优先本地执行 能独立形成 PR 的任务适合云端 Codex 开发必须先分析、再计划、后编码 代码完成不等于任务完成 测试、Diff、Commit 和审查都是交付的一部分 不要让多个 Agent 在同一分支和工作区无隔离修改 不要让 Codex 绕过团队原有工程规范