Codex 完整使用指南：从提问、协作到自动化交付

1. Codex 到底是什么

Codex 是快速迭代中的产品，具体功能、模型、权限和价格会变化。本文侧重使用方法和工作流，功能细节请以 OpenAI 官方文档为准。

Codex 可以理解为 OpenAI 面向真实工作的 AI 代理，最核心的能力是：它不只回答问题，还能在一个具体工作环境里读文件、理解上下文、修改内容、运行命令、调用工具、检查结果，并把过程和结论反馈给你。

很多人第一次接触 Codex，会把它当成“更强的代码补全”或“会写代码的 ChatGPT”。这个理解太窄了。Codex 更像一个可以被派任务的协作者：你给它目标、边界、项目资料和验收标准，它负责把任务拆开、执行、验证，再把结果交还给你审阅。

在软件工程里，它可以读代码库、修 bug、写功能、做重构、生成测试、审查 PR、迁移旧系统、更新文档、跑构建、分析日志。在更宽的工作场景里，它也可以处理数据、整理表格、生成报告、制作幻灯片、梳理会议纪要、管理收件箱、分析反馈、执行重复工作流，甚至在启用相关工具后操作浏览器、Figma、Canva、GitHub、Slack、邮箱或本地应用。

一句话：Codex 的价值不是“替你打字”，而是把一个模糊任务推进成一个可检查、可验证、可交付的结果。

2. Codex 和普通聊天机器人的区别

普通聊天机器人主要是回答问题。Codex 的重点是完成任务。

普通聊天机器人常见工作方式是：

• 你问一个问题
• 它给一个答案
• 你自己判断答案是否可用
• 你自己复制、修改、运行、验证

Codex 的典型工作方式是：

• 你描述目标
• 它读取项目和相关文件
• 它提出计划或直接执行
• 它修改文件、运行命令、调用工具
• 它根据输出继续修正
• 它总结修改、验证结果和剩余风险

所以，Codex 更适合“有环境、有上下文、有交付物”的任务。越是需要读资料、跨文件推理、反复运行检查、保持工程约束的事情，越适合交给 Codex。

3. Codex 能做什么

下面按工作类型整理。实际能力取决于你使用的界面、安装的插件、授权的连接器、网络权限、本地环境和项目配置。

3.1 理解代码库

Codex 可以帮助你进入一个陌生项目：

• 总结项目结构
• 找入口文件
• 梳理模块职责
• 解释某个函数、类、接口或服务
• 追踪一次请求从前端到后端的路径
• 找出某个配置从哪里读取、在哪里生效
• 分析依赖关系
• 解释构建、测试、部署脚本
• 根据代码生成架构说明
• 把复杂实现改写成面向人的说明文档

适合的提示词：

请先阅读这个项目的目录结构和关键文件，告诉我它的主要模块、启动方式、测试方式，以及如果我要改登录流程应该从哪里开始。

3.2 写功能

Codex 可以实现从小功能到复杂功能的开发任务：

• 新增 API
• 新增页面或组件
• 增加表单、筛选、排序、分页
• 接入第三方服务
• 加权限判断
• 加缓存
• 加状态管理
• 加日志和埋点
• 补充错误处理
• 增加配置项
• 把产品需求拆成可执行的开发步骤

但复杂功能不要只丢一句“帮我做个系统”。更好的方式是给出目标、边界、验收标准和不能破坏的约束。

我要给后台订单列表增加按状态筛选和按创建时间排序。
要求：
1. 保持现有接口兼容；
2. 前端筛选条件要反映在 URL query；
3. 后端需要加测试；
4. 先给计划，等我说 GO 再改代码。

3.3 修 bug

Codex 很适合处理有日志、有复现步骤、有测试失败输出的 bug。

它可以：

• 阅读错误日志
• 找到异常来源
• 复现失败
• 分析最近改动
• 写最小修复
• 补回归测试
• 运行验证命令
• 说明根因和风险

好的 bug 提示词应该包含：

• 发生了什么
• 期望是什么
• 实际是什么
• 错误日志
• 复现步骤
• 最近改过什么
• 你希望它只分析还是直接修

这个接口在 status=archived 时返回 500。下面是日志和复现请求。请先定位根因，确认后给最小修复方案，等我说 GO 再改。

3.4 重构代码

Codex 可以做重构，但重构要有边界。

适合 Codex 的重构：

• 拆分过大的文件
• 提取重复逻辑
• 改善命名
• 降低模块耦合
• 把旧 API 调用迁移到新 API
• 统一错误处理
• 清理死代码
• 把脚本改成可维护模块
• 在不改变行为的前提下整理结构

不适合的做法是让它“一次性把整个项目重构成最佳实践”。这种任务范围太大，容易引入不可控变化。

更好的说法：

请只重构 src/services/billing.ts。目标是拆出 invoice、subscription、payment 三个职责，不能改变外部导出的函数签名。先列出当前耦合点和计划。

3.5 写测试和验证

Codex 不只是写测试代码，还可以帮你建立验证闭环。

它可以：

• 找出缺失测试
• 写单元测试
• 写集成测试
• 写端到端测试
• 根据 bug 补回归测试
• 增加测试数据
• 运行测试并根据失败修正
• 解释测试失败原因
• 设计验证清单
• 给人工验收步骤

提示词示例：

请为这个修复补回归测试。测试要先能证明旧逻辑会失败，再证明新逻辑通过。完成后运行相关测试，不要跑全量测试，除非你判断有必要。

3.6 代码审查

Codex 可以像代码审查员一样阅读 diff。

它可以重点发现：

• 逻辑 bug
• 回归风险
• 边界条件遗漏
• 并发问题
• 安全问题
• 数据兼容问题
• 迁移风险
• 测试缺口
• 命名和结构问题

高质量 review 提示词：

请 review 当前 git diff。按严重程度排序，优先指出真实 bug、回归风险和缺失测试。不要泛泛评价代码风格。

3.7 前端和 UI

Codex 可以做前端，但前端任务必须给清楚视觉目标。它可以：

• 根据截图实现页面
• 把 Figma 设计转成代码
• 修改布局
• 做响应式适配
• 修文字溢出
• 调整交互状态
• 增加表单校验
• 实现 dashboard、编辑器、工具面板、数据表格
• 使用浏览器截图做视觉检查
• 修复移动端样式问题

提示词示例：

请根据这张截图实现设置页。要求桌面端两栏布局，移动端单栏；按钮和输入框遵循项目已有组件；完成后用浏览器检查 1440px 和 375px 两个视口。

3.8 网站、应用和游戏原型

Codex 可以从一个想法做出可运行原型：

• landing page
• 管理后台
• 小工具
• 数据可视化页面
• 浏览器小游戏
• 交互式 demo
• MVP
• 静态网站
• 可部署 Web 应用

它可以安装依赖、启动开发服务器、截图检查、修正页面空白或交互问题，并给出本地访问 URL。

3.9 原生和移动开发

在具备对应环境和工具时，Codex 可以参与：

• iOS SwiftUI 应用开发
• macOS 应用开发
• React Native / Expo 应用
• App Intents
• 原生 UI 重构
• Xcode 构建和模拟器调试
• macOS telemetry
• 移动端 bug 复现和修复

这类任务尤其需要告诉它：目标平台、Xcode 或 Node 环境、启动命令、模拟器目标、验收方式。

3.10 数据、表格和报告

Codex 不只处理代码，也能处理数据文件和知识工作。

它可以：

• 读取 CSV、TSV、XLSX
• 清洗脏数据
• 做数据汇总
• 查询表格
• 生成图表
• 做预算 vs 实际分析
• 做现金流预测
• 生成 DCF 模型
• 输出可编辑工作簿
• 写分析报告
• 把数据结论转成演示文稿

提示词示例：

请分析这个销售 CSV，找出过去 6 个月增长最快和下滑最快的产品线，生成一个摘要报告，并输出一个带图表的 Excel 文件。

3.11 文档、知识库和学习

Codex 可以把复杂材料变成结构化知识：

• 写 README
• 更新开发文档
• 生成 API 文档
• 生成变更日志
• 写 PRD
• 写技术方案
• 写会议纪要
• 把论文或长文整理成学习笔记
• 把内部资料整理成 onboarding 文档
• 把反馈归类成行动项
• 把项目经验沉淀成可复用指南

3.12 幻灯片、设计和视觉材料

如果启用了文档、演示文稿、Canva、Figma 或图像生成相关工具，Codex 可以：

• 生成 PPTX
• 修改演示文稿
• 生成 Canva 设计
• 从模板批量填充设计
• 翻译 Canva 设计
• 调整社交媒体尺寸
• 生成或编辑图片
• 把 Figma 节点转成代码
• 生成 FigJam 图表
• 创建设计系统或组件映射

这类任务要明确输出格式：PPTX、Canva 链接、Figma 文件、图片、Markdown，还是网站页面。

3.13 自动化和跨应用工作流

Codex 可以通过工具和连接器处理重复性事务：

• 从 Slack 线程生成任务
• 整理邮件并草拟回复
• 从会议记录生成 follow-up
• 从 bug 报告生成优先级队列
• 定期检查某些状态
• 创建提醒、监控和自动化任务
• 把重复工作沉淀为 Skills
• 调用 MCP 工具访问外部系统
• 在启用 Computer Use 时点击、输入和导航应用

这里的关键是：你要告诉它“输入来自哪里、输出去哪里、什么时候运行、如何判断成功”。

3.14 安全相关任务

Codex 可以辅助安全工作，例如：

• 审查代码变更中的安全回归
• 分析依赖漏洞公告
• 对授权仓库做深度安全扫描
• 建立代码库威胁模型
• 尝试复现漏洞
• 生成修复补丁
• 把补丁提交成人工可审查的 PR

安全任务必须保持人工审查。不要让 AI 自动把安全补丁直接推到生产环境。

4. Codex 的工作界面

Codex 可以出现在不同地方。不同界面的能力会有差异。

常见形态包括：

• ChatGPT 或 Codex Web 中的云端任务
• Codex CLI
• IDE 扩展
• Codex 桌面应用
• GitHub / PR / CI 工作流
• 移动端或跨应用任务入口
• 通过 API、SDK 或 App Server 集成进自己的工具

云端任务适合让 Codex 在隔离环境里做较完整的工程任务。本地 CLI 和 IDE 更适合与当前项目即时协作。GitHub 和 CI 适合代码审查、自动检查和工作流触发。桌面应用适合统一管理多个任务、工具和上下文。

5. 如何给 Codex 一个好任务

一个好任务通常包含 7 个要素。

5.1 目标

告诉 Codex 最终要得到什么。

差：

帮我优化一下。

好：

请把订单列表的首屏加载时间从 3 秒左右降到 1 秒以内，优先分析接口请求、数据库查询和前端渲染瓶颈。

5.2 背景

告诉它为什么做、影响哪些人、当前约束是什么。

这是给运营后台用的页面，用户每天会反复筛选和导出订单，所以交互稳定性比炫酷动画更重要。

5.3 范围

明确哪些可以改，哪些不能改。

可以改前端页面和订单查询接口，但不要改数据库 schema，也不要改导出逻辑。

5.4 验收标准

告诉它什么叫完成。

验收标准：
1. status、dateRange、keyword 三个筛选条件可组合；
2. 刷新页面后筛选条件保留；
3. 现有测试通过；
4. 新增至少 2 个后端测试和 1 个前端测试。

5.5 工作方式

告诉它先计划还是直接执行。

先给计划，等我说 GO 再改代码。

或：

/quick 这是小改动，直接完成并验证。

5.6 风险边界

告诉它不要碰什么。

不要删除用户数据，不要运行生产部署命令，不要修改鉴权逻辑。

5.7 验证方式

告诉它应该跑什么命令。

完成后运行 npm run test:unit 和 npm run lint。如果某个命令失败，先分析失败是否与本次修改有关。

6. 推荐工作流

6.1 普通开发工作流

请先阅读项目上下文，给我一个分步骤计划。等我说 GO 再改代码。完成后运行相关测试，并总结修改内容、验证结果和剩余风险。

这个流程适合大多数功能开发和重构。

6.2 快速修复工作流

/quick 把这个按钮文案从「提交」改成「保存」，只改必要文件，完成后确认页面没有其他文案被误改。

适合很小、低风险、边界明确的改动。

6.3 热修复工作流

/hotfix 线上登录失败。下面是错误日志和最近发布记录。请直接定位最小修复，补回归测试，并说明是否需要回滚。

适合生产问题，但仍然要尽量验证。

6.4 代码审查工作流

请 review 当前改动。优先找真实 bug、回归风险、安全问题和缺失测试。按严重程度排序，给出文件和行号，不要写泛泛的风格建议。

6.5 复杂任务工作流

这是一个多文件复杂任务。请先拆解任务，必要时使用可用的 MCP、Skills 或多代理工具。先输出计划和风险点，等我确认后再执行。

6.6 学习和解释工作流

请把这个模块讲给一个刚加入团队的工程师听。先解释业务目的，再解释关键文件、数据流、容易踩坑的地方，最后给一个阅读顺序。

6.7 自动化工作流

请把这个每周重复工作整理成可复用流程：输入是周报数据和 GitHub issue，输出是优先级列表、风险摘要和下周行动项。先设计流程，不要立刻创建自动化。

7. AGENTS.md：给 Codex 的项目说明书

如果 README 是给人看的项目说明，那么 AGENTS.md 就是给 AI 代理看的项目说明。

你可以在 AGENTS.md 里写：

• 项目结构
• 启动命令
• 测试命令
• 代码风格
• 命名规则
• 哪些文件不能改
• 常见坑
• 部署注意事项
• 修改代码前必须遵守的流程
• 安全和隐私规则

示例：

# AGENTS.md

## 开发流程

- 修改代码前先阅读相关文件并给出计划。
- 没有用户明确说 GO，不要修改代码。
- 小改动可以在用户使用 /quick 时直接执行。

## 测试

- 后端修改运行 npm run test:api。
- 前端修改运行 npm run test:ui。
- 如果测试失败，先说明失败是否与本次修改有关。

## 禁止事项

- 不要写入真实 API key。
- 不要运行生产部署命令。
- 不要修改数据库迁移，除非用户明确要求。

好的 AGENTS.md 可以显著提升 Codex 的稳定性，因为它把你的偏好从“每次都要说一遍”变成“项目默认规则”。

8. Skills、MCP 和连接器

Codex 的能力很大程度取决于它能使用什么工具。

8.1 Skills

Skills 是可复用的专业流程。比如：

• 文档写作流程
• 代码审查流程
• 调试流程
• 前端实现流程
• 演示文稿制作流程
• 表格分析流程
• Figma 工作流
• Canva 工作流

当你经常重复某类任务，可以把它沉淀成 Skill，让 Codex 以后按固定步骤执行。

8.2 MCP

MCP 可以理解为让 Codex 连接外部工具和数据源的协议。通过 MCP，Codex 可以访问文档、数据库、设计工具、项目管理工具、浏览器、搜索、内部系统等。

例如，OpenAI 官方提供 Docs MCP，让 Codex 在处理 OpenAI API、ChatGPT Apps SDK、Codex 等问题时可以直接检索官方开发文档。

8.3 连接器和插件

连接器让 Codex 访问具体应用。比如：

• GitHub：读 PR、查 issue、开分支、提交建议
• Figma：读设计、生成界面、建立 Code Connect
• Canva：生成或修改设计
• 文档和表格工具：创建、分析和修改文件
• 浏览器工具：打开页面、截图、检查 UI
• 自动化工具：创建提醒、监控和后台任务

你给 Codex 的任务越接近真实工作流，工具就越重要。

9. 如何控制 Codex 的风险

Codex 很强，但不能无脑放权。尤其是代码、数据、安全和生产系统相关任务。

9.1 明确审批规则

你可以要求：

• 修改代码前先计划
• 删除文件前先确认
• 运行危险命令前先确认
• 不允许自动部署生产
• 不允许改数据库结构
• 不允许接触真实密钥

9.2 保持 git 干净

在开发任务前，最好让 Codex 先看 git 状态：

请先检查 git status，区分已有改动和你接下来要做的改动。不要覆盖我已有的修改。

9.3 让它最小化修改

请做最小改动，不要顺手重构无关文件。

9.4 要求验证证据

完成后请告诉我你运行了哪些命令、结果是什么、还有哪些没法验证。

9.5 高风险任务保持人工审查

这些任务不要完全自动化：

• 生产部署
• 数据删除
• 权限系统修改
• 安全补丁合并
• 支付逻辑变更
• 大规模迁移
• 合同、法律、医疗、财务结论

Codex 可以帮你分析和准备，但最终责任仍然在使用者。

10. 常见错误用法

10.1 只给一句模糊目标

帮我把项目优化一下。

这会导致范围失控。应该明确优化对象、指标和限制。

10.2 让 Codex 一次做太多事

帮我重构全项目、改 UI、接支付、上线部署。

复杂任务应该拆成阶段：先评估，再方案，再实现，再验证。

10.3 不给错误日志

只说“报错了”远远不够。日志、复现步骤、环境信息越完整，Codex 越可靠。

10.4 不要求验证

AI 写出的代码不等于可交付代码。必须运行测试、构建、lint 或人工验收步骤。

10.5 把 Codex 当成最终责任人

Codex 是执行和分析工具，不是责任主体。重要决策仍然需要人审查。

11. 一套可复用的 Codex 提示词模板

11.1 项目理解

请阅读当前项目，输出：
1. 项目用途；
2. 技术栈；
3. 目录结构；
4. 启动方式；
5. 测试方式；
6. 主要模块；
7. 新人最应该先读的 5 个文件。

11.2 功能开发

我要实现：[目标]
背景：[为什么做]
范围：[可以改什么，不能改什么]
验收标准：[完成的判断方式]
验证方式：[需要运行的命令]

请先给计划，等我说 GO 再修改代码。

11.3 Bug 修复

问题：[实际现象]
期望：[正确行为]
复现步骤：[步骤]
日志：[粘贴日志]
最近改动：[如果有]

请先定位根因，再给最小修复方案。不要修改无关代码。

11.4 代码审查

请 review 当前 git diff。
要求：
1. 先列问题；
2. 按严重程度排序；
3. 给文件和行号；
4. 重点关注 bug、安全、回归和缺失测试；
5. 不要泛泛表扬。

11.5 重构

请重构 [文件/模块]。
目标：[降低重复/拆分职责/改善可测试性]
约束：
1. 不改变外部 API；
2. 不改变业务行为；
3. 保留现有测试；
4. 修改前先说明计划。

11.6 文档整理

请把这些资料整理成一篇给团队内部使用的文档。
要求：
1. 先讲结论；
2. 再讲背景；
3. 给操作步骤；
4. 列常见问题；
5. 最后给检查清单。

11.7 数据分析

请分析这个表格。
目标：[你想知道什么]
输出：
1. 关键发现；
2. 支撑数据；
3. 异常点；
4. 图表；
5. 可执行建议。
不要修改原始文件，输出一个新的分析文件。

11.8 自动化

我每周都要做这个流程：[描述流程]
输入：[数据来源]
输出：[交付物]
频率：[什么时候运行]
成功标准：[如何判断完成]

请先设计自动化流程和风险点，不要直接创建自动化。

12. 不同人群怎么用 Codex

12.1 程序员

把 Codex 当成会读项目的 pair programmer。适合让它做探索、计划、低风险实现、测试补充、代码审查和文档更新。

12.2 技术负责人

把 Codex 当成工程执行代理。适合让它拆任务、评估技术债、审查 PR、生成迁移计划、维护文档、推动重复性工程工作。

12.3 产品经理

把 Codex 当成从需求到原型的助手。适合写 PRD、整理反馈、生成用户故事、做 UI mock、把会议内容变成行动项。

12.4 设计师

把 Codex 当成设计到实现之间的桥。适合从 Figma 提取结构、生成前端代码、检查响应式、整理组件规范。

12.5 数据和运营人员

把 Codex 当成数据分析和自动化助理。适合清洗表格、生成报告、分析预算、整理邮件、处理重复工作流。

12.6 创作者和知识工作者

把 Codex 当成可操作文件和工具的写作伙伴。适合整理知识库、写长文、做幻灯片、生成图表、维护网站内容。

13. 我的推荐使用原则

原则一：先让 Codex 读，再让 Codex 写

不要一上来就让它改。先让它理解上下文，能减少大量误改。

原则二：让 Codex 给计划

计划不是形式主义。计划能暴露它是否理解任务、是否漏掉边界、是否会碰危险区域。

原则三：给验收标准

没有验收标准，Codex 只能猜什么叫完成。

原则四：让它验证

能运行测试就运行测试。不能运行测试，就给人工验证步骤。

原则五：把规则写进 AGENTS.md

重复说三次以上的偏好，就应该写成项目规则。

原则六：复杂任务拆小

一个任务只解决一个清晰问题。大任务拆成设计、实现、测试、上线、复盘。

原则七：不要交出最终审查权

Codex 可以提高速度，但不替你承担判断责任。

14. 一句话总结

Codex 最好的使用方式，不是把它当成“会写代码的搜索框”，而是把它当成一个需要上下文、规则、工具和验收标准的执行型协作者。

你给它的不是一句愿望，而是一份任务说明；它回给你的也不该只是一段答案，而应该是一个经过执行、检查和说明的结果。

真正高效的 Codex 工作流是：

目标清楚 -> 上下文充分 -> 边界明确 -> 计划先行 -> 小步执行 -> 运行验证 -> 人工审查 -> 沉淀规则

做到这一步，Codex 就不只是帮你“快一点写代码”，而是帮你把复杂工作变得更可控、更可复用、更容易交付。

参考资料

• OpenAI Codex 产品页
• Introducing Codex
• OpenAI Codex CLI Getting Started
• OpenAI Codex Use Cases
• OpenAI Code generation guide
• OpenAI Docs MCP
• Codex Security
• AGENTS.md open format