1. 引言Codex 不是另一个「聊天窗口」很多 Plus / Pro 用户在开通订阅后第一反应是把 Codex 当成网页版 ChatGPT 的平替——丢个问题进去、复制答案出来。这种用法只发挥了它不到三成的功力。Codex 真正的定位是代理式编程智能体coding agent它能直接读写你的文件系统、执行 shell 命令、运行测试、在失败后自我修正并在你的审批下完成一个完整的多文件改动。对已经熟悉 Git、终端和工程化流程的开发者来说Codex 的价值在于「把重复的、可拆解的开发任务外包出去」而不是「生成一段孤立的代码」。本文假设你已开通 ChatGPT Plus / Pro跳过一切开通流程直接进入实战部分从 CLI 环境配置、真实项目接入到 Spec-Driven Development规格驱动开发、自定义AGENTS.md与审批模式最后用一个完整案例串起整条工作流。2. 先选对入口网页、IDE 插件还是 CLICodex 有三个主要入口它们的适用场景完全不同入口适合场景局限网页版 ChatGPT 内嵌 Codex快速验证想法、小段代码生成无文件系统访问无法持续改项目VS Code / JetBrains 插件边写边改、局部重构上下文受当前文件限制多文件联动弱Codex CLI重点真实项目、多文件改动、代理式迭代需要一点配置成本但收益最大对于非小白用户我的建议是一旦任务涉及「跨多个文件、需要运行测试、需要读取项目结构」直接上 CLI。下面重点围绕 CLI 展开。3. Codex CLI 环境搭建与关键配置3.1 安装与认证# macOS / Linux推荐使用 npm 安装更新及时npminstall-gopenai/codex# 确认安装成功codex--version首次运行需要认证。Codex CLI 支持两种认证方式建议优先使用 API Key 方式因为它可以解耦模型选择# 方式一ChatGPT 账号登录适用于 Plus / Pro 订阅用户codex login# 方式二使用 API Key与订阅套餐并存时可灵活切换模型exportOPENAI_API_KEYsk-...登录后CLI 会默认使用与你订阅套餐绑定的模型。对于 Pro 用户可以在配置中显式指定更强模型codex login# 进入交互界面后可以用 /model 切换模型3.2 核心配置文件config.tomlCodex 的全局配置位于~/.codex/config.toml以下是面向工程化开发的推荐配置model gpt-5-codex model_provider openai approval_policy on-request # on-request: 仅在执行可能产生副作用的命令前请求审批推荐 # never: 完全自动执行仅限完全隔离的沙箱环境 sandbox_mode workspace-write # read-only: 只读不写 # workspace-write: 可写当前工作区推荐 # danger-full-access: 完全无沙箱谨慎使用 [spinner] render dotsapproval_policy是 CLI 里最容易被忽视、却又最重要的设置。建议保持on-request让 Codex 在执行git commit、rm、安装依赖等高风险命令前停下来等你确认。3.3 基础交互模式CLI 有两种运行模式建议先熟悉非交互模式再进入交互模式# 非交互模式直接执行一次任务codexexec为 src/utils/logger.ts 补充单元测试# 交互模式进入持续对话支持多轮代理式执行codex交互模式下有几个高频命令值得记住/model切换模型/approvals查看待审批的操作/compact压缩上下文清理历史/undo撤销上一次改动/help查看全部命令4. 代理式编码的核心让 Codex 真正「跑起来」Codex 与普通补全工具的本质区别在于执行循环agentic loop它会自己规划步骤、执行命令、检查结果、修正错误直到任务完成或需要你审批。4.1 给它一个可验证的目标质量差的任务指令往往是这样帮我优化一下代码。这种模糊指令会让 Codex 自由发挥结果往往不可控。好的指令必须包含可验证的验收标准重构src/api/client.ts把重复的请求重试逻辑抽成src/utils/retry.ts的withRetry函数保持原有导出接口不变重构完成后运行pnpm test确保所有测试全部通过。关键区别在于最后一句用测试作为验收标准。这让 Codex 有了自我纠错的依据——它改完代码后会自己跑测试测试失败就会继续修。4.2 项目上下文AGENTS.md是最高杠杆配置Codex 会自动读取项目根目录下的AGENTS.md作为持久化指令。这是目前最被低估的功能。一个高质量的AGENTS.md应该包含# 项目编码规范 ## 技术栈 - Node.js 20使用 ES Modules - 测试框架Vitest禁止引入 Jest - 包管理器pnpm禁止使用 npm 或 yarn ## 命令 - 运行测试pnpm test - 类型检查pnpm typecheck - 构建pnpm build ## 规范 - 所有 TS 文件使用严格模式类型必须显式标注禁用 any - 错误处理统一使用自定义 AppError 类不抛出裸异常 - 每提交一个可工作的小改动不要跨越无关模块有了这份指令Codex 在每次任务中都会遵循你的技术栈约定不会擅自把 Electron 应用改成 Vite 项目、运行正确的命令、遵守代码规范。这一步的投入产出比极高。5. Spec-Driven Development把「改代码」升级为「走流程」对于已经熟悉工程化流程的开发者直接让 Codex「改这个文件」还不够过瘾。更进阶的用法是规格驱动开发Spec-Driven Development——先写规格说明再让 Codex 按规格实现。5.1 工作流编写规格文档在spec/目录下用 Markdown 描述功能需求、边界条件、验收标准。让 Codex 实现规格把规格文档作为上下文交给 Codex。Codex 自测利用规格中的验收标准驱动测试。人工审查重点审查边界条件和安全相关改动。5.2 实战一个带缓存的 API 客户端假设规格文档spec/cached-api-client.md内容如下# 带缓存的 API 客户端 ## 需求 实现 src/api/cachedClient.ts对 GET 请求结果做内存缓存。 ## 验收标准 - 相同 URL 和参数的 GET 请求在 TTL 内只请求一次后端 - POST / PUT / DELETE 请求不缓存且会清除同路径的 GET 缓存 - TTL 默认 60 秒可通过构造参数覆盖 - 缓存命中时返回值的引用必须深拷贝防止外部修改污染缓存 - 必须通过 pnpm test 的全部用例然后执行codexexec读取 spec/cached-api-client.md按规格实现 src/api/cachedClient.ts并编写单元测试验证所有验收标准实现完成后运行 pnpm test 确认通过Codex 会读取规格、实现代码、生成测试、运行测试并在失败时自行修复。你最终需要做的只是审查 diff 和跑一次完整测试。这种模式的收益在于规格即契约。即使中途切换模型或换人来审查验收标准始终是明确的。6. 审批模式的工程化实践代理式编码最大的信任问题来自「它会不会乱执行命令」。针对非小白用户建议建立一套分层审批策略命令类型策略配置方式读操作cat / ls / grep自动放行默认写操作写入文件 / 编辑代码自动放行工作区内sandbox_mode workspace-write高风险命令git push / rm / npm install必须审批approval_policy on-request网络请求下载脚本 / curl 执行必须审批审批时重点看 URL一个典型的安全审批场景是 Codex 执行以下命令前的暂停# Codex 试图安装新依赖CLI 会弹出审批npminstallaxios# 你的判断依据# 1. 这个依赖真的是任务需要的吗# 2. 版本号是否被锁死是否应该写成 axios1.7.2# 3. 是否引入了不必要的供应链风险审批不是纯被动的「点同意」而是一个审查环节。把审批当成 Code Review 的一部分每次确认命令与你对任务的理解一致后再放行。7. 完整实战用 Codex 完成一个真实功能下面用一个贴近真实工作的案例把前面的所有环节串起来。7.1 任务背景你在维护一个 TypeScript 的 REST API 服务需要新增一个「用户列表分页查询」接口。要求路由GET /api/users?page1pageSize20参数校验page 为正整数pageSize 范围 1-100返回结构{ data: User[], total: number, page: number, pageSize: number }必须做 SQL 注入防御使用参数化查询补充集成测试覆盖正常与异常参数7.2 阶段一让 Codex 探索项目不要一上来就让它写代码。先给它一个探索性任务codexexec阅读项目结构找到以下信息1) 路由如何注册2) 现有的数据库访问方式3) 错误处理中间件如何工作4) 现有测试的写法。输出一份简短的实现建议。这一步让 Codex 建立对项目的理解也让你确认它对技术栈的判断是否正确。7.3 阶段二规格化任务把需求整理成带验收标准的指令codexexec实现 GET /api/users 分页查询接口。要求 1. 按项目现有路由风格注册 2. 使用参数化查询全程禁止字符串拼接 SQL 3. 参数校验失败返回 400结构符合现有错误响应格式 4. 编写集成测试覆盖正常分页、page 为 0、pageSize 超过 100、page 为非数字 5. 实现后运行项目的测试命令确保全部通过7.4 阶段三审查与收尾Codex 完成后重点审查三个风险点SQL 是否真的参数化——不要只看它声称「已参数化」要直接看生成的查询代码参数校验是否覆盖边界——特别是page0和超大pageSize测试是否真实有效——检查测试断言是否真的验证了响应结构而不是只断言 200。审查确认无误后手动执行最终验收pnpmtestpnpmtypecheck8. 常见坑与避坑指南以下是我自己在深度使用 Codex CLI 过程中总结的几个高频问题坑 1上下文过长导致「遗忘」规格。多轮代理执行后Codex 可能丢失早期需求。缓解方式把关键验收标准写进AGENTS.md或规格文档而不是只放在对话历史里上下文膨胀时用/compact。坑 2擅自扩大改动范围。让它改 A 文件结果顺手重构了 B、C 文件。缓解方式在指令中明确「只允许修改与本次任务直接相关的文件」并开启审批模式审查每一条写操作。坑 3测试「虚假通过」。Codex 可能为了让测试通过而修改测试本身导致测试失去验证价值。缓解方式在指令中声明「禁止修改测试文件以适配实现」并人工抽查关键测试断言。坑 4依赖版本漂移。Codex 可能安装一个不兼容的最新版依赖。缓解方式在AGENTS.md中固定关键依赖版本审批安装命令时注意版本号。9. 总结Codex 的上限不取决于模型本身而取决于你如何给它设定边界和验收标准。对于已经熟悉开发流程的非小白用户最有价值的三个实践是写好AGENTS.md——把项目规范、命令、技术栈约束一次性沉淀成持久化指令用测试驱动验收——让 Codex 有自我纠错的客观依据而不是靠「感觉改好了」把审批当 Code Review——每一次放行都是一次质量审查而不是流程负担。当你把这三件事固化进工作流后Codex 才会从「偶尔生成代码的聊天工具」变成「能独立跑完一个完整开发任务的代理」这才是 Plus / Pro 订阅真正解锁的能力。