Codex 教程

用 Codex 排查报错

用 Codex 排查构建、测试、运行时、SDK、API、网络、CI 和 Codex App 状态问题的完整指南，覆盖日志脱敏、最小复现、排错分层、Goal Prompt、验证命令和 FAQ。

预计阅读: 6 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

用 Codex 排查报错，关键不是把一大段错误丢给它，而是把失败命令、完整日志、运行环境、最近改动、期望行为和验证方式组织成可复现问题。只给末尾一行错误，通常会让 Codex 走向猜测。

高质量排错要把问题拆成层：命令是否正确、目录是否正确、依赖是否一致、环境变量是否存在、代码是否变更、SDK 参数是否匹配、API 请求是否能最小复现、CI 环境是否和本地不同。Codex 擅长沿着这些线索读文件、跑命令、缩小范围和给出最小修复。

项目	说明
阅读时间	约 6 分钟
更新时间	2026-07-03
适合读者	开发者、独立项目维护者、正在用 Codex 排查本地项目、CI、SDK 或 API 报错的人
你会获得	排错分层表、日志脱敏清单、最小复现包、可复制 Goal Prompt、API 验证方法、Codex App 状态排查路径

使用场景

报错类型	需要提供	Codex 应先做什么	推荐验证
构建失败	完整命令、日志、依赖版本、锁文件	找到最早的错误和相关配置	重新 build
测试失败	失败用例、stack trace、输入数据	复现单个失败，再扩到相关套件	单测和全量测试
运行时报错	复现步骤、浏览器或终端日志	定位触发路径和调用栈	手动路径或端到端测试
SDK 报错	SDK 版本、脱敏请求、状态码	区分 SDK 参数错误和 API 错误	最小脚本或 cURL
API 报错	Base URL、端点、状态码、响应体	用最小请求复现	`curl -i` 或最小请求
CI 失败	job 日志、runner、环境变量差异	对比本地和 CI 命令	重新运行失败 job
Codex App 状态异常	当前目录、线程状态、终端状态	检查是否等待授权或目录错误	`pwd`、`git status`

排错流程图

排错分层表

层级	先看什么	常见线索	交给 Codex 的任务
命令层	失败命令、cwd、shell	脚本不存在、路径错误	确认当前目录和可用脚本
依赖层	锁文件、安装日志、版本	模块缺失、版本冲突	对比本地和 CI 安装方式
配置层	`.env`、配置文件、变量名	变量为空、路径拼接错误	列出需要的配置项
代码层	调用栈、最近 diff	空值、类型变化、边界遗漏	定位最小修改点
测试层	失败用例、fixture	断言过时、测试数据不一致	单个用例复现后修复
SDK/API 层	状态码、请求体、响应体	401、404、429、5xx	用最小请求排除 SDK 干扰
网络层	代理、DNS、超时	本地成功、CI 失败	用 cURL 或最小脚本验证
Codex 状态层	线程、授权、工作树	终端卡住、工作树依赖缺失	检查授权、目录和工作树

日志脱敏清单

信息	脱敏方式	不要这样做
API Key	保留前缀和用途，例如 `sk-xxxx`	粘贴完整 Key
Authorization	改成 `Bearer sk-xxxx`	截图完整请求头
Cookie / Session	删除整行或改成 `[redacted]`	保留浏览器登录态
用户数据	用示例 ID 和示例文本替换	粘贴真实姓名、邮箱、文档内容
内部 URL	保留路径结构，隐藏域名或 IP	暴露内网地址
请求体	保留字段名，隐藏敏感值	把客户数据当样例
CI Secret	只写变量名	在日志里 echo 值

脱敏后仍要保留足够上下文：状态码、错误类型、请求路径、失败命令、stack trace、相关配置名和最近改动。删得太干净，Codex 也无法判断根因。

最小复现包

内容	示例	作用
失败命令	`npm run build`	让 Codex 知道复现入口
当前目录	`pwd` 输出	排除目录错误
版本信息	`node -v`、`python --version`	排除环境差异
完整日志	`logs/failing-command.txt`	找最早错误
最近改动	`git diff --stat`	缩小范围
期望行为	构建通过、接口返回 200	定义完成条件
验证命令	`npm run check`	证明修复有效

OpenAI Codex 官方手册建议在提示词里包含可复现步骤、验证方式、lint 或 pre-commit 检查。排错时尤其要把“原失败命令再次通过”写进完成条件。

可复制 Goal Prompt

Goal: 排查并修复下面的报错，使用最小改动让原失败命令通过。

失败命令：
[粘贴命令]

完整错误日志：
[粘贴脱敏日志，或说明日志文件路径]

背景：
- 最近改动：[说明文件、PR、commit 或功能]
- 期望结果：[说明正确行为]
- 当前环境：[系统、Node/Python、包管理器、浏览器、CI runner]
- 已尝试方法：[列出尝试过但失败的方法]

要求：
- 先定位最早的根因，不要只看日志末尾。
- 按命令、依赖、配置、代码、SDK/API、网络和 CI 分层排查。
- 先给出 2-3 个假设和验证步骤，再修改文件。
- 做最小修复，不做无关重构。
- 运行原失败命令和相关验证命令。
- 如果日志里信息不足，列出缺失信息，不要编造原因。

Done when:
- 原失败命令通过，或明确说明无法在当前环境复现。
- 相关测试、构建或最小请求通过。
- diff 中没有无关改动。
- 给出根因、修复点和后续预防建议。

执行步骤

保存完整失败命令和日志，不只复制末尾几行。
脱敏密钥、Cookie、用户数据、内部 URL 和 CI Secret。
让 Codex 确认当前目录、分支、包管理器和可用脚本。
要求 Codex 找最早的根因，并列出验证假设。
针对一个问题做最小修复，不把多个报错混成一个任务。
运行原失败命令，再运行相关构建、测试或最小请求。
审查 diff，确认没有泄露密钥、扩大范围或掩盖错误。

API 报错最小验证

如果报错来自 OpenAI-compatible API，先检查 Base URL、请求路径、API Key、模型名、状态码和响应体。使用 OfApp.cn 时，OpenAI / Codex 生态 Base URL 可配置为 https://api.ofapp.cn/v1。

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"

如果这个最小请求失败，优先排查 Key、Base URL、网络、账号状态和控制台配置；如果最小请求成功，再回到 SDK 参数、业务代码、代理、超时和请求体。模型、额度、价格和具体能力请以 OfApp.cn 控制台或官方文档为准。

常见错误矩阵

错误	表现	常见根因	修复路径
`command not found`	本地或 CI 找不到命令	依赖未安装、脚本名错误、PATH 不同	查 `package.json` 和安装步骤
`module not found`	构建或测试中断	依赖缺失、路径大小写、alias 错误	安装依赖或修 import
测试偶发失败	重跑有时通过	时间、随机数、网络、共享状态	固定输入并隔离副作用
401 / invalid key	API 鉴权失败	Key 错、变量未注入、请求头缺失	查环境变量和 Authorization
404 / not found	路径或资源不存在	Base URL 重复 `/v1`、端点错误、模型名不匹配	用最小请求确认路径
429 / rate limit	短时间大量失败	并发过高、额度或限流	降并发、退避、查控制台
5xx	上游或网络异常	服务短暂不可用、代理超时	有限重试并记录请求 ID
CI 通过不了	本地正常，远端失败	版本、Secret、缓存、系统差异	对齐 runner 和本地命令

Codex App 状态排查

有些问题不是业务代码错误，而是 Codex 所处状态不对。官方手册提醒：Codex App 和 CLI 使用同一底层 agent 与配置，但版本和实验功能可能不同；工作树也可能在不同目录，依赖和忽略文件需要单独处理。

状态	先检查	处理方式
终端像卡住	是否等待授权、终端面板状态	重新打开终端，运行 `pwd` 或 `git status`
当前目录不对	`pwd`、项目根目录、分支	切回项目目录再运行命令
worktree 运行失败	依赖、忽略文件、`.worktreeinclude`	运行安装脚本或补齐需要的本地文件
App 和 CLI 表现不同	两边版本号和配置	分别确认 Codex App 与 CLI 版本
侧边栏出现非 Codex 改动	Git 工作树里有其他未提交变化	用 review 面板切换范围，必要时看 Last turn changes
需要反馈或上报	日志和 session 是否可分享	先脱敏，再按官方路径提供日志

官方手册列出 macOS App 日志位于 ~/Library/Logs/com.openai.codex/YYYY/MM/DD，会话记录默认在 $CODEX_HOME/sessions。分享前要检查是否包含敏感信息。

注意事项

风险	处理方式
日志不完整	保存完整命令输出，尤其是最早错误和 stack trace。
密钥泄露	粘贴给 Codex 前先脱敏 Key、Cookie、请求头和用户数据。
多个错误混在一起	一个失败命令一个任务，修完再处理下一个。
网络问题误判为代码问题	用 cURL 或最小脚本复现。
为了变绿跳过测试	禁止无解释地 `skip`、删除断言或吞掉异常。
修复范围失控	要求最小 diff，并在完成后 review 改动。

资料来源

OpenAI Codex 官方手册：Codex 提示词、验证、排错、AGENTS.md、review 和日志路径建议。
OfApp.cn API 文档：Base URL、API Key、Codex / OpenAI 生态接入入口和最小示例。
OfApp.cn 天才游乐场：聊天、图片和参数调试入口。
OfApp.cn：普通用户入口、天才游乐场和 Codex 工作流定位。

常见问题

报错很长，要全部给 Codex 吗？

建议提供完整日志，尤其是最早错误、stack trace、失败命令和环境版本。可以让 Codex 先提取关键线索，再决定要不要继续收集更多信息。

API 报错应该从代码查还是从网络查？

先用最小请求复现。若 cURL 也失败，多半是鉴权、Base URL、路径、账号状态或网络配置；若 cURL 成功，再查 SDK 参数和业务代码。

Codex 修复后还需要人工检查吗？

需要。至少检查 diff、验证命令、是否引入无关改动，以及是否泄露密钥或放宽权限。涉及生产数据时必须人工复核。

CI 报错本地复现不了怎么办？

让 Codex 对比 CI runner、依赖安装、缓存、Secret、系统版本和脚本命令。必要时把失败 job 日志保存到 logs/ci-job.log，再做最小复现。

Codex 判断原因错了怎么办？

要求它回到证据：错误行、调用栈、配置文件、最近 diff 和最小复现结果。没有证据的猜测应暂时放下。

什么时候应该停止自动修复？

如果涉及密钥、权限、生产数据、数据库迁移、支付、用户隐私或无法复现的线上事故，应停止自动修改，先整理证据和人工评审计划。

API 错误排查中心：查看通用 API 和 SDK 错误。
401 鉴权失败排查：排查 API Key 和请求头问题。
404 Not Found 错误排查：检查 Base URL、端点和路径。
429 Rate Limit：处理限流和重试。
context length exceeded：排查上下文超限。
invalid API key：检查 Key、Bearer 和部署 Secret。
用 Codex 修 Bug：从报错进入最小修复流程。
用 Codex 生成测试：把修复变成回归测试。
Codex 本地项目使用指南：确认工作目录、脚本和项目规则。
Codex Goal 提示词模板：复制排错类 Goal 模板。
OfApp.cn 常见错误排查：定位 API Key、Base URL、模型名和网络请求。

带走什么

用 Codex 排查报错时，信息质量决定修复质量。完整日志、脱敏请求、环境版本、最小复现和原始失败命令，比一句“帮我看看报错”可靠得多。把错误变成可验证任务，Codex 才能稳定地把问题收束到根因。