用 Codex 修 bug：给报错原文、复现步骤和约束，让它先复现再改，最后重跑复现和测试，附 4 段提示词

本文根据 Codex 官方文档《Prompting Codex》和斜杠命令页整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是软件截图。本站（bigolab.com）不是 OpenAI 官方网站。安装与配置见 /guides/codex-getting-started，本文只讲怎么描述 bug。

适用于谁

• 代码跑出报错，自己卡住了，想让 Codex 帮忙定位和修复的人；
• 提示词总是写成“这里有 bug，帮我修一下”，结果越修越乱的人；
• 修好之后不知道怎么确认的人。

结论先说

1. 官方说，复现步骤和约束比高层描述更重要。 “登录页有问题”远不如“点击登录后，控制台报 Cannot read properties of undefined，期望跳转首页”。
2. 要给四样东西：复现步骤、怀疑的文件、约束、验证方式。
3. 让它先复现再修。 官方示例写的是：先在本地复现 bug，然后提出补丁并运行检查。
4. 约束写明白。 官方示例的约束包括不改 API 的形状、最小修复、可行时补一条回归测试。
5. 修完让它重跑复现，并运行 lint 和最小相关的测试套件，报告用了什么命令、结果如何。

图：本站根据 Codex 官方文档《Prompting Codex》 整理的示意图

一、先把线索收集好

动手前，先备齐下面这些，哪怕只有一部分：

• 报错原文：完整复制，不要截取半句，更不要自己转述；
• 复现步骤：从哪个页面或命令开始，做了什么，看到什么，期望看到什么；
• 出现条件：是总是出现，还是特定数据、特定环境才出现；
• 最近改了什么：如果是某次提交之后才出现的，告诉它大概的时间或提交；
• 怀疑的文件：知道就用 @ 指给它，不知道就写“我不确定”。

官方在命令行里的做法是在仓库根目录启动 Codex；在 IDE 里，则是打开可能出问题的文件和最近的调用方。

二、4 段可以直接复制的提示词

方括号里是要你自己填的内容。

1. 标准格式：复现、定位、修复、验证

有个 bug 需要修复。
现象：[点击“提交订单”后页面白屏]
报错原文：
[粘贴完整报错]
复现步骤：[1. 打开 /cart；2. 选择一个商品；3. 点击提交]
期望：[跳转到订单确认页]
怀疑的文件：@[文件路径]
约束：不改接口的返回格式；改动尽量小；可行的话加一条回归测试。
请先在本地复现，确认能看到同样的报错；再解释原因，然后提出补丁；最后重新跑一次复现步骤，再运行相关的 lint 和最小范围的测试，告诉我命令和结果。

2. 只有报错，不知道从哪查

我在运行 [命令] 时遇到下面的报错，不知道原因。请先只读不改：
1. 解释这个报错通常是什么原因；
2. 在代码里找出最可能触发它的位置，说明理由；
3. 列出 2 到 3 种可能的原因，每种怎么验证。
先不要改文件。
[粘贴完整报错]

3. 偶发问题：先加日志，不乱改

这个问题只是偶尔出现，我没有稳定的复现步骤。请不要直接改逻辑。
请先帮我在 [相关函数] 附近加几处临时日志，记录关键变量的值，告诉我怎么运行和观察。拿到日志后我再发给你一起分析。
改动完成后列出你加了哪些日志，方便我之后删除。

4. 修完后让它自我复盘

请总结这次修复：1. 根本原因是什么；2. 改了哪些文件、各改了什么；3. 你运行了哪些命令，结果分别是什么；4. 还有哪些相关的地方可能有同样的问题；5. 我还应该手动检查什么。

如果想让它再做一遍代码审查，官方斜杠命令页写明 /review 会对未提交的改动或与基础分支的差异启动审查模式，详见 /guides/codex-code-review。

三、修完之后，你怎么判断

图：本站根据 Codex 官方文档《Prompting Codex》 整理的示意图

• 用你自己的复现步骤再走一遍，不要只看它的总结；
• 看改动范围：用 Git 查看改了哪些文件，和 bug 无关的改动要让它撤销；
• 看测试：是新增了回归测试，还是为了让测试通过而放宽、删除了原有测试；
• 上线前：涉及支付、权限、数据删除的改动，自己逐行审查，并先在测试环境验证；
• 失败了就回退：先确认工作区状态，改坏了用 Git 退回，再用更小的请求重试。

命令被拒绝或需要审批时的处理见 /guides/codex-permissions-sandbox。

四、几种常见 bug 怎么描述

下面是本站按开发经验整理的描述要点，不是官方清单：

• 页面白屏或点击没反应：给浏览器控制台的完整报错、点击了哪个按钮、是否每次都出现。只说“没反应”，它只能猜；
• 接口返回错误：给请求的地址、参数（去掉密钥）、返回的状态码和响应内容，以及你期望的返回；
• 数据不对：给一条具体的输入和实际输出、期望输出，比“数据有问题”有用得多；
• 命令行或脚本报错：给你运行的完整命令、完整输出，以及运行环境，比如系统和语言版本；
• 只在线上出现：线上日志先去掉用户信息再给它，并说明本地能否复现；不能复现时，先按第 3 段提示词加日志，不要让它盲改。

描述得越具体，它越不需要猜，越不容易改到不该改的地方。同一个 bug 描述清楚之后，也可以顺手让它检查有没有别处存在同样的写法，但这类批量修改要分开确认，不要和修复混在一次改动里。

常见问题

Q：它说修好了，但我的问题还在？

把你的复现步骤和现在的现象告诉它，并要求“先复现，再说明为什么上一次的修复没有覆盖这个情况”。

Q：报错信息里有密钥、内部地址怎么办？

先去掉。贴日志前的检查见 /guides/ai-privacy-data-safety-checklist。

Q：需要选更强的模型吗？

复杂 bug 可以提高推理强度，见 /guides/codex-switch-model-reasoning-effort。Codex 随 ChatGPT 套餐提供，额度以官方页面为准，需要更多额度可以看看 /chongzhi/chatgpt-plus 里的说明。

参考资料

• Codex 官方文档：Prompting Codex — https://learn.chatgpt.com/docs/prompting
• Codex 官方文档：Slash commands — https://learn.chatgpt.com/docs/reference/slash-commands