`codex review` 的三种评审范围怎么挑：--uncommitted、--base 与 --commit

2026-08-09

用 Codex（OpenAI Codex）做代码评审，第一件要想清楚的事不是”用哪个模型”，而是”让它看哪一段改动”。范围划大了，评审报告里一半内容是在讲你根本没碰过的老代码；范围划小了，最该被抓出来的那处改动压根没进入视野。

在 codex-cli 0.147.0（Windows 11）上执行 codex review --help，这个子命令的专有选项只有五项，其中三项是用来划范围的：

选项	官方说明
`--uncommitted`	评审已暂存、未暂存和未跟踪的改动
`--base <BRANCH>`	与指定基线分支比较
`--commit <SHA>`	评审某个 commit 引入的改动
`--title <TITLE>`	评审摘要里显示的可选提交标题
`[PROMPT]`	自定义评审说明，写 `-` 表示从 stdin 读

顶层命令表里 review 的官方说明是 “Run a code review non-interactively”——它是一个非交互的子命令，不是把你丢进 TUI 里聊天。这决定了它天然适合塞进脚本和钩子。

三种范围各自对应什么处境

--uncommitted 对应”我手上这摊还没提交的活儿”。 它的官方说明里逐字写了三类内容：已暂存、未暂存、未跟踪。注意最后那一类——新建但还没 git add 的文件也在范围里。这是三个选项中唯一在说明里明确提到未跟踪文件的。你刚从别处拷了个新模块进来还没入库，只有这个范围能看到它。

--base <BRANCH> 对应”我这条分支整体想合回去”。 它做的是与指定基线分支比较，也就是把你分支上累积的所有改动当成一个整体来看。提 PR 之前自查用它最合适，因为它的范围和 reviewer 在网页上看到的那一坨大致是同一个概念。

--commit <SHA> 对应”这一次提交到底改坏了什么”。 范围锁死在某个 commit 引入的改动上。定位回归、复盘线上事故、或者对着一段别人的历史提交做学习式阅读时用它。

有个细节值得先说破：官方对 --base 和 --commit 的说明里，都没有提到未跟踪文件。所以别指望这两个范围会捎带上你没入库的新文件。要让新文件进入评审，要么用 --uncommitted，要么先把它纳入 Git 管理再走 base 或 commit。

至于什么范围选项都不给时它默认评什么，codex review --help 的输出里没有写死，事实层面我们也没有验证过——真要用无参形式，请自己先在一个无关紧要的仓库里跑一次 codex review --help 确认当前版本的说明，别凭猜。

命令怎么写

三种范围的最小可用形式：

# 1) 提交前自查：手上所有没提交的改动，含未跟踪文件
codex review --uncommitted

# 2) 提 PR 前自查：本分支相对 main 的整体改动
codex review --base main --title "重构导出模块"

# 3) 事后定位：某一次提交引入了什么
codex review --commit 4f2a9c1

--title 只影响评审摘要里显示的标题，但在 --base 场景下强烈建议带上：一条分支往往对应一个明确的意图，把意图写进标题，比让模型从 diff 里反推你想干什么要靠谱。

范围选项之外，顶层选项也可以叠上来。评审本身是”读”的活儿，把沙箱压到只读是合理的默认：

codex review --base main -s read-only -m gpt-5.6-sol --title "重构导出模块"

这条命令里三个附加选项各自的理由：-s read-only 把沙箱压到只读，评审不需要写文件的权限；-m 指定本次会话用的模型，这里填的 gpt-5.6-sol 是官方《Models》页当前列出的旗舰档（能力 5 星 / 速度 2 星，核对日 2026-08-09），到底有哪些取值可填请以官方《Models》页为准，别照抄旧文章里的模型名——模型会退役；--title 给评审摘要一个明确的意图标签。如果你不确定该选哪个模型，直接把 -m 去掉，用会话默认的就行，范围选对比模型选贵重要得多。

-s 的三个合法取值在 codex-cli 0.147.0（Windows 11）上实测就是 read-only / workspace-write / danger-full-access——传错会直接被 clap 拦下，报 error: invalid value '...' for '--sandbox <SANDBOX_MODE>' 并把三个候选值列出来，这一步不会静默降级，可以放心。

Windows 上有个引号坑要提一句。带自定义评审说明时，Git Bash 里用单引号包住，PowerShell 里用双引号：

# Git Bash
codex review --base main '重点看并发和错误处理，不用管命名风格'

# PowerShell
codex review --base main "重点看并发和错误处理，不用管命名风格"

写自定义说明的价值远大于换个更贵的模型。范围决定”看哪里”，PROMPT 决定”看什么”，两者是正交的——--commit 加上一句”只看这次改动有没有破坏向后兼容”，比不带说明跑十遍都有用。

产出物往哪里接

codex review 自己的选项表里没有 --json，也没有写文件的选项，所以它的输出就是打在终端上给人看的。

要拿到能被脚本消费的东西，得换一条路：在 codex-cli 0.147.0 上，codex exec 支持 review 子命令，而 codex exec 这一层有两个和产出物直接相关的选项——--json 把事件以 JSONL 打到 stdout，-o, --output-last-message <FILE> 把 agent 的最后一条消息写到指定文件。前者是流式事件，适合喂给管道边跑边解析；后者只落最终结论，适合当成一份报告文件收着。

需要提醒的是：这两个选项列在 codex exec 的独有选项里，它们对 review 子命令是否全部生效，我们没有实测过，请以你机器上 codex exec review --help 的实际输出为准。另外，具体的 JSONL 事件里有哪些字段，我们没有采集过，任何声称”字段叫什么”的说法都请自己 dump 一次再信。

所以这条路的第一步不是抄命令，而是先在你自己的机器上看一眼当前版本到底认哪些选项：

codex exec review --help

看清楚 --base / --commit / --uncommitted 这几个范围选项在 codex exec review 这一层是否被接受、-o 能不能和它们同时给，再决定要不要把它写进脚本。下面这条是按 help 里已有的选项拼出来的形态，供你对照：

codex exec review --base main -o review-report.md

以上为按官方 help 中的选项拼装的示例，未逐项实测，以 codex exec review --help 为准。如果你机器上的版本不接受这种组合，退回到最保守的做法：用 codex review 跑，人在终端里读结论，需要归档就自己重定向或复制粘贴。

怎么验收

第一处：范围是不是你以为的那个范围。 跑 Codex 之前先用 Git 自己核一遍——--uncommitted 对应 git status --short 列出来的东西，--base main 对应 git diff --stat main...HEAD。如果 Git 那边显示的文件数就和你预期不符，那不是评审的问题，是你的分支基线或工作区状态有问题，先修这个。这一步最容易翻车的场景是：本地 main 很久没 fetch，--base main 比出来的是几十个文件的巨大差异，里面绝大部分是别人的提交。

第二处：配置到底加载上了没有。 如果你为评审专门改过 ~/.codex/config.toml，改完先跑一次：

codex doctor --summary

在 codex-cli 0.147.0（Windows 11）上，我们故意用 -c 传了一段语法不合法的 TOML，结果是命令没有崩溃退出，doctor 照常跑完，只是在结果里多了一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

也就是说，配置写坏了 Codex 不会当面骂你，它会带着”没加载上配置”的状态继续跑。所以”我明明改了配置怎么没生效”这类问题，第一步就该是看 doctor 的 config 那一行。

顺带一提 --strict-config 的边界：它的作用是配置里出现本版本不认识的字段时直接报错退出。但在 codex-cli 0.147.0（Windows 11）上实测，codex -c model_reasoning_effortt=high --strict-config exec --help 正常打印了 help，并没有报未知字段——校验发生在真正加载配置去跑会话的路径上，--help 这类不进入会话的路径不触发。别把它当成”任何情况下都能拦住拼写错误”的保险丝。

第三处：报告里提到的文件是不是都在你划的范围内。 如果评审开始点评一些你这次根本没动的文件，多半是范围选宽了（典型是 --base 指向了过时的本地分支），换 --commit 或 --uncommitted 收窄再跑。

什么情况别指望这三个范围

不在 Git 仓库里的目录。 这三个范围全部建立在 Git 的概念上——已暂存、基线分支、commit SHA，没有仓库就无从谈起。顺便说一句，--skip-git-repo-check（允许在非 Git 仓库里运行）是 codex exec 的独有选项，不在 codex review 的选项表里。

指望它顺手把问题改掉。 review 的官方定位就是跑一次代码评审。要落改动是另一条链路：顶层命令里 apply（别名 a）的说明是 “Apply the latest diff produced by Codex agent as a git apply to your local working tree”——注意是”最新一次 diff”，不是”你刚才那份评审报告”。评审归评审，改动归改动，中间那一步该由人来决定。

跨度极大的一次性评审。 我们没有任何 token 消耗或响应耗时的实测数据，不给具体阈值建议。但官方配置里存在 model_context_window（当前模型可用的上下文 token 数）和 model_auto_compact_token_limit（触发自动压缩历史的 token 阈值）这两个键，说明长上下文被压缩是真实存在的机制。基于这一点，把”半年没评审过的分支”一次性丢给 --base 并不是个好主意，按 commit 或按模块拆几次更稳。

安全合规审计。 官方文档另有《Security Review》页，我们没有取过其内容，不能替它下结论。这三个范围选项解决的是”改动评审”，别当成安全审计用。

远端 PR 与云端任务。 官方文档给的做法是另有专门页面覆盖（《Review GitHub pull requests with Codex》《Codex cloud》），这部分我们完全没有实测，不在本文的经验范围内。

两个容易写串的地方

review_model 说的是 /review。 官方配置参考里 review_model 这个键的说明是”/review 专用模型；不设则继承会话模型”——写的是斜杠命令 /review。它是否同样作用于 codex review 这个子命令，事实层面我们没有验证。想指定评审模型，最没有歧义的做法是在命令行上直接用 -m。

approvals_reviewer / auto_review.policy 不是这个 review。 这两个键在官方配置参考里被归在沙箱与审批那一节：approvals_reviewer 默认 user、可设 auto_review，auto_review.policy 是自动评审的本地 Markdown 策略（受管配置优先）。它们描述的是”审批请求由谁来复核”，和 codex review 划范围做代码评审是两条链路。名字撞车，配置别写串。