Codex CLI 调试指南

# 以详细模式启动交互会话
$ codex --verbose

# 简写
$ codex -v

$ codex exec --verbose "给 auth.py 补充单元测试"

# 同时指定模型
$ codex exec -v --model o4-mini "优化这个 SQL 查询"

# 当次会话临时生效
$ CODEX_LOG_LEVEL=debug codex

# 持久写入 shell 配置
$ echo 'export CODEX_LOG_LEVEL=info' >> ~/.zshrc

# 非交互模式也有效
$ CODEX_LOG_LEVEL=debug codex exec "生成 API 文档" 2> debug.log

[debug] POST https://api.openai.com/v1/chat/completions 200 (1243ms)
[debug] usage: { prompt_tokens: 3842, completion_tokens: 156, total_tokens: 3998 }
[debug] tool_call: write_file { path: "src/auth.test.ts", content: "..." }
[debug] sandbox: run_command "npm test" exit=0

# 查看 Codex 会如何重构，不实际修改
$ codex exec --dry-run "将 user_controller.py 中所有同步函数改成 async"

# 危险操作前必须预演
$ codex exec --dry-run "删除 src/ 下所有 .bak 文件"

# 配合 verbose 获取更多细节
$ codex exec --dry-run --verbose "重构数据库连接池"

📋 Planned actions (DRY RUN — nothing will be executed):

Step 1: Read user_controller.py
Step 2: Identify synchronous function definitions (found 7)
Step 3: Rewrite functions with async/await patterns
Step 4: Update import: add 'asyncio'
Step 5: Write modified file → user_controller.py

Files that WOULD be modified: [user_controller.py]
Commands that WOULD run: none
Total estimated tokens: ~4200

[debug] usage: {
  prompt_tokens: 12453,   ← 发送给模型的 token（含上下文）
  completion_tokens: 892, ← 模型生成的 token
  total_tokens: 13345     ← 本轮总消耗
}

[debug] tool_call: read_file { path: "src/api/users.ts" }
[debug] tool_call: write_file {
  path: "src/api/users.ts",
  content: "import { ... }" ← 截断显示
}
[debug] tool_call: run_command { command: "npx tsc --noEmit" }
[debug] sandbox: exit=2, stderr: "error TS2345: ..."

# 步骤 1：开启 verbose，看有没有网络请求
$ codex --verbose

# 步骤 2：测试代理是否工作
$ curl -v https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# 步骤 3：确认代理变量已设置
$ env | grep -i proxy

# 步骤 1：用 dry-run 验证 Codex 的执行计划
$ codex exec --dry-run "[你的任务]"

# 步骤 2：查看 debug 日志中的 prompt 内容
$ CODEX_LOG_LEVEL=debug codex exec "[任务]" 2> prompt-debug.log

# 步骤 3：添加 AGENTS.md 明确约束
$ codex /init  # 生成 AGENTS.md 草稿

# 查看哪个模型在触发 429
$ CODEX_LOG_LEVEL=info codex exec "..." 2>&1 | grep -i "429\|model\|rate"

# 切换到使用率低的模型
$ codex exec --model gpt-4.1-mini "..."

# config.toml 设置默认模型
# model = "gpt-4.1-mini"

# 在 verbose 日志中查看沙箱命令输出
$ codex --verbose
# 查找类似：[debug] sandbox: exit=1, stderr: "..."

# 在 AGENTS.md 中指定测试命令，让 Codex 能自我验证
# ## 测试
# - 始终运行 `npm test` 验证修改
# - TypeScript: `npx tsc --noEmit` 检查类型

# 检查两种认证方式是否冲突
$ env | grep OPENAI_API_KEY  # 有输出说明用 API Key
$ cat ~/.codex/auth.json 2>/dev/null  # 有内容说明用 OAuth

# 冲突时清除 OAuth，只用 API Key
$ rm ~/.codex/auth.json
$ export OPENAI_API_KEY="sk-..."

# 或只用 OAuth，不设 API Key
$ unset OPENAI_API_KEY
$ codex login