Codex 教程
用 Codex 修 Bug
用 Codex 修 Bug 的完整指南，覆盖复现步骤、根因定位、最小修复、回归测试、日志脱敏、API 报错边界、Diff 审查和常见误区。
用 Codex 修 Bug 的关键不是让它“随便看看哪里错了”，而是把问题变成一个可 复现、可定位、可验证的小闭环。你给出的复现步骤、错误日志、期望行为和验证 命令越清楚，Codex 越容易做出范围小、风险低、能通过测试的修复。
| 项目 | 内容 |
|---|---|
| 阅读时间 | 约 6 分钟 |
| 更新时间 | 2026-07-03 |
| 适合人群 | 开发者、产品经理、运营、学生、老师，以及需要让 Codex 帮忙排查项目问题的人 |
| 你会得到 | 修 Bug Prompt、复现模板、根因定位矩阵、回归测试策略、API 报错边界和 Diff 审查清单 |
| Bug 类型 | 适合用 Codex 吗 | 需要提供什么 |
|---|---|---|
| 前端交互异常 | 适合 | 浏览器、页面路径、操作步骤、截图、控制台报错 |
| API 请求失败 | 适合 | 请求路径、状态码、脱敏请求头、响应体、Base URL |
| 测试失败 | 适合 | 失败命令、完整错误栈、相关测试文件 |
| 数据格式错误 | 适合 | 输入样例、输出样例、字段含义、边界数据 |
| 性能回退 | 可用，但要谨慎 | 慢在哪个操作、基准数据、复现命令、性能日志 |
| 部署或 CI 失败 | 适合 | CI 链接、失败 job、环境变量名、构建日志 |
修 Bug 闭环图
Section titled “修 Bug 闭环图”什么时候先别修
Section titled “什么时候先别修”有些问题不适合直接进入代码修改。让 Codex 先补调查，比立刻动手更稳。
| 情况 | 推荐动作 |
|---|---|
| 没有复现步骤 | 请 Codex 列出缺失信息，并帮助你设计最小复现 |
| 预期行为不清楚 | 先让产品、业务或题主确认正确结果 |
| 同一段日志包含多个问题 | 拆成独立任务，一个 Prompt 只解决一个根因 |
| 涉及生产数据或真实用户信息 | 先脱敏，再只提供必要字段 |
| 怀疑是权限、额度、套餐或模型可用性 | 先用控制台或官方文档确认当前状态 |
| 需要大规模重构才能修 | 先做止血修复，再单独安排重构任务 |
推荐目录结构
Section titled “推荐目录结构”project/ AGENTS.md src/ tests/ scripts/ logs/ bug-2026-07-03-redacted.log package.json把复现日志放到本地文件里，再在 Prompt 中引用路径。日志必须先脱敏：
Authorization、Cookie、API Key、用户 ID、邮箱、手机号、内部 IP、订单号
等字段都不应原样交给 Codex。
如果团队经常让 Codex 修 Bug，可以在 AGENTS.md 里写清：
- 项目结构和关键目录。
- 常用测试、构建、Lint 命令。
- 日志脱敏规则。
- 修改范围限制。
- 修复完成前必须运行的检查。
OpenAI Codex 手册建议把目标、上下文、约束和完成标准写清楚；AGENTS.md
适合沉淀长期规则，Prompt 适合表达这一次 Bug 的具体信息。
可复制 Goal Prompt
Section titled “可复制 Goal Prompt”Goal:修复 [Bug 标题]。保持改动范围小。补充能证明问题不再复现的验证。
Context:- 复现步骤： 1. [操作或命令] 2. [操作或命令]- 实际结果：[看到的错误、状态码、页面表现或测试输出]- 预期结果：[正确行为]- 错误日志：[脱敏日志路径或粘贴片段]- 相关文件：[可选，列出怀疑文件或模块]- 验证命令：[例如 npm test -- bug-name]
Constraints:- 先复现；如果无法复现，说明缺少什么信息。- 用证据说明根因，不要只猜测。- 只做最小修复，不做无关重构。- 不删除错误处理，不跳过测试，不吞掉异常。- 不把 API Key、Cookie、真实用户数据写进代码或日志。
Done when:- 原始失败命令通过。- 相关回归测试通过。- Diff 中没有无关格式化或重命名。- 说明修改了什么、为什么有效、还剩哪些风险。这类 Prompt 的重点是让 Codex 有足够信息验证自己的工作。官方 Codex 手册也 强调：提供复现步骤、验证方式、Lint 或预提交检查，会让输出更可靠。
- 收集复现步骤、输入数据、环境版本、错误日志和期望结果。
- 让 Codex 读取相关文件、测试、配置和
AGENTS.md。 - 要求它复现问题，或明确说明无法复现的原因。
- 让它列出根因证据，例如失败断言、异常位置、请求差异或配置缺口。
- 只修改与根因直接相关的代码。
- 补一个能在旧代码上失败、在新代码上通过的回归测试。
- 运行原始失败命令、相关测试、类型检查或构建，再审查 Diff。
根因定位矩阵
Section titled “根因定位矩阵”| 表现 | 可能层级 | 该找什么证据 | 可以交给 Codex 的任务 |
|---|---|---|---|
| 点击按钮无反应 | UI 状态或事件绑定 | 控制台报错、事件处理函数、禁用状态 | 追踪点击路径，找出事件没有触发的原因 |
| API 返回 401 | 鉴权或 Key | Authorization、Base URL、Key 是否脱敏但格式正确 |
对比最小 cURL 与项目代码的请求头 |
| API 返回 404 | 路径或代理 | 实际 URL、路由前缀、网关转发日志 | 找出项目拼接出的最终请求路径 |
| 单测突然失败 | 行为变化或测试假设过期 | 失败断言、最近变更、Mock 数据 | 判断是实现问题还是测试需要更新 |
| 构建失败 | 依赖、类型或配置 | 构建命令、完整错误栈、锁文件变化 | 定位哪个依赖或类型声明引发失败 |
| 线上偶发错误 | 数据边界或并发 | 输入样例、时间范围、环境差异 | 把偶发条件还原成可重复用例 |
最小修复原则
Section titled “最小修复原则”好的修复通常很克制。你可以要求 Codex 按下面规则审查自己的改动：
| 原则 | 为什么重要 |
|---|---|
| 一个根因对应一个补丁 | 避免把多个风险混到同一个 Diff |
| 保留原有正确行为 | 修复不能让正常路径退化 |
| 不静默吞异常 | 错误需要被处理或暴露，不能假装不存在 |
| 不随意放宽类型 | any、空判断和默认值可能掩盖真实问题 |
| 不删除失败测试 | 测试是问题证据，不是障碍 |
| 配置问题不硬编码 | Base URL、Key、模型等配置应留在环境变量或工具配置中 |
示例：API 401 Bug 的修复路径
Section titled “示例：API 401 Bug 的修复路径”如果项目调用 OpenAI-compatible API 时返回 401，不要一开始就让 Codex 大改 SDK 封装。先让它用最小请求确认外部入口是否可用。
export OPENAI_BASE_URL="https://api.ofapp.cn/v1"export OPENAI_API_KEY="sk-xxxx"
curl -i "$OPENAI_BASE_URL/models" \ -H "Authorization: Bearer $OPENAI_API_KEY"排查顺序可以这样写给 Codex：
- 如果最小 cURL 失败，检查 Key、Base URL、账户状态、网络和当前官方文档。
- 如果最小 cURL 成功，检查项目代码是否覆盖了
OPENAI_BASE_URL。 - 对比 SDK 实际发出的 URL、请求头、代理和运行环境变量。
- 修复配置读取、请求头拼接或部署环境变量，而不是硬编码真实 Key。
OfApp.cn 官方页面展示的 OpenAI / Codex 生态 Base URL 是
https://api.ofapp.cn/v1。真实模型、套餐、额度和价格会变化，接入前请以
OfApp.cn 控制台或官方文档为准。
回归测试怎么补
Section titled “回归测试怎么补”修复 Bug 后，最有价值的测试是能证明“同一个问题不会再回来”。
| Bug 来源 | 回归测试写法 | 验证方式 |
|---|---|---|
| API 请求头丢失 | Mock 请求，断言 Authorization 被传入 |
运行相关单测 |
| Base URL 拼接错误 | 输入不同 Base URL，断言最终 URL | 运行配置测试 |
| 表单提交重复 | 模拟连续点击，断言只发送一次请求 | 运行组件测试 |
| 数据字段为空 | 给空值、缺字段、边界值样例 | 运行单元测试 |
| 解析失败 | 固定一段错误响应体 | 运行解析器测试 |
| CI 环境才失败 | 用 CI 同款命令在本地复现 | 运行构建或类型检查 |
更多测试 Prompt 可以继续看：用 Codex 生成测试。
Diff 审查清单
Section titled “Diff 审查清单”让 Codex 修完后，再让它按这个清单自查一次：
- 这次 Bug 的根因是否被写清楚。
- 修复是否只触碰相关文件。
- 是否新增或更新回归测试。
- 原始失败命令是否已经通过。
- 是否有 API Key、Cookie、用户信息或内部地址进入代码。
- 是否把配置写死到源码里。
- 是否删除了错误处理、日志或测试。
- 是否引入了与 Bug 无关的格式化、重命名或依赖升级。
Codex App 的 Review 面板会展示 Git 仓库里的未提交变化，包括你和 Codex 的 改动。仓库已经有其他未提交内容时，要按文件和 Diff 逐项确认，不要把无关变 更混入同一次修复。
常见错误排查
Section titled “常见错误排查”| 错误 | 表现 | 更好的做法 |
|---|---|---|
| 只说“页面坏了” | Codex 难以定位入口 | 提供页面路径、操作步骤和截图 |
| 只贴报错末尾一行 | 根因可能在上游栈 | 提供完整 stack trace，并脱敏 |
| 一次修多个 Bug | Diff 变大，测试难覆盖 | 拆成多个小任务 |
| 没有验证命令 | 修复无法被证明 | 写清要运行的命令 |
| 让 Codex 顺手优化 | 引入无关改动 | 修复完成后再开优化任务 |
| 真实 Key 出现在日志里 | 安全风险 | 立即撤销 Key，并使用脱敏日志重跑 |
| 风险 | 处理方式 |
|---|---|
| 日志含密钥 | 脱敏后再交给 Codex；公开仓库里不要提交原始日志 |
| 修改范围过大 | 要求 Codex 把非必要改动撤回或拆出新任务 |
| 只修表象 | 要求说明根因证据和修复为什么有效 |
| 测试不稳定 | 让 Codex 解释不稳定来源，不要简单跳过 |
| API 兼容边界不清 | 同时检查 Base URL、路径、请求头、模型参数和状态码 |
| 线上环境差异 | 对比本地、CI、服务器的环境变量和依赖版本 |
- OpenAI Codex Manual：Codex Prompt、验证、Review、
AGENTS.md等工作方式。 - OfApp.cn 官网：OfApp.cn 入口、天才游乐场、Base URL 与生态说明。
- OfApp.cn API 文档：Codex 接入、OpenAI-compatible API 示例与
/v1/models最小请求。 - OfApp.cn 天才游乐场：Key、聊天参数、图片参数和网页体验入口。
Codex 无法复现 Bug 怎么办？
Section titled “Codex 无法复现 Bug 怎么办？”不要急着让它修改代码。让 Codex 列出缺失信息，例如环境变量、测试数据、浏 览器版本、请求样例、依赖版本或登录状态。补齐条件后再进入修复。
生产日志可以直接给 Codex 吗？
Section titled “生产日志可以直接给 Codex 吗？”不建议。先删除用户信息、API Key、Cookie、内部 IP、订单号、邮箱、手机号 和任何可识别个人或业务的数据。必要时只保留字段名、状态码、错误类型和脱敏 后的样例。
修 Bug 时可以顺便重构吗？
Section titled “修 Bug 时可以顺便重构吗？”多数情况下不建议。先用最小修复关闭问题，并用测试证明修复有效。重构可以 作为独立任务处理，这样更容易回滚和审查。
修复 API Bug 要先查代码还是先查请求？
Section titled “修复 API Bug 要先查代码还是先查请求？”先用最小请求确认外部入口，再查项目代码。最小请求失败时，重点检查 Key、 Base URL、账户状态和官方文档；最小请求成功时，再检查 SDK 封装、代理、部 署环境变量和业务参数。
Codex 修好后为什么还要补回归测试？
Section titled “Codex 修好后为什么还要补回归测试？”因为测试能把这次错误固定成可验证的事实。没有回归测试时，Bug 可能在后续 重构、依赖升级或配置调整中再次出现。
多个报错同时出现怎么办？
Section titled “多个报错同时出现怎么办？”按最早出现、最稳定复现、影响链路最上游的报错拆任务。一个 Prompt 只解决 一个明确根因，修完并验证后再处理下一个。
- 用 Codex 排查报错：处理构建、测试和运行时报错。
- 用 Codex 生成测试：为修复补回归测试。
- 用 Codex 重构项目：在修复后再做结构性整理。
- Codex 本地项目使用指南：让 Codex 理解项目目录和本地环境。
- Codex Goal Prompt 写法：把复杂任务写成可执行目标。
- 用 Codex 配置 GitHub Actions：让验证流程进入 CI。
- API 错误排查中心：查看 API 与 SDK 常见错误排查。
- 401 Unauthorized：排查 Key 和鉴权问题。
- 429 Rate Limit：排查限流与重试策略。
- 快速排查指南：从 Key、Base URL、模型和日志开始定位。
用 Codex 修 Bug 的高质量流程是：复现清楚、根因有证据、补丁范围小、测试能 证明、Diff 经得起审查。只要把问题压缩成可验证的小闭环，Codex 就更像一个 可靠的工程搭档，而不是只会猜测的代码生成器。