1. 为什么“独立评审”才是 Headless Agent CLI 的正确打开方式
很多人第一次接触 Headless 模式的 Agent CLI，脑子里想的都是“自动化跑任务”——让它自己读代码、自己改文件、自己提交。这个方向没错，但如果你只把它当成一个“无人值守的码农”，那大概率会踩一堆坑：改错文件、删掉不该删的逻辑、生成一堆看似合理实则跑不通的代码，最后你还得花更多时间去擦屁股。
我自己用 Codex 这类 Agent CLI 有一段时间了，从最初的“全自动放手让它干”到后来的“只让它做独立评审”，中间交了不少学费。现在我的核心用法非常明确：Headless Agent CLI 最合适的场景，不是替你写代码，而是替你审代码。也就是标题里说的“独立评审”。
这个定位听起来好像把 Agent 的能力用窄了，但实际上恰恰相反。独立评审这个场景，对 Agent 的要求是“读得多、想得深、说得清”，而不是“动手改”。它不需要写权限，不需要碰你的工作区，只需要把代码、diff、日志、配置读进去，然后输出一份结构化的评审意见。风险极低，收益却极高。
这篇文章我会把“独立评审”这套用法拆开讲透：为什么选 Headless 模式、子代理怎么配、Codex 在评审场景下的参数怎么调、常见报错怎么排查、以及我踩过的那些坑。适合已经装好 Codex CLI、想把它用出真正价值的人，也适合还在观望、想知道这东西到底能干嘛的人。
2. 独立评审的定位与整体设计思路
2.1 为什么是“评审”而不是“生成”
先说一个反直觉的结论：Agent 生成代码的质量，和它评审代码的质量，不在一个量级上。
生成代码时，Agent 要同时做三件事：理解需求、设计方案、写出实现。这三件事里任何一环出偏差，最终产物就是错的。而且生成是“从零到一”，没有参照物，Agent 很容易在细节上自由发挥，写出你根本不想要的抽象层或者依赖。
评审就不一样了。评审是“从一到一”的校验：代码已经在那儿了，需求已经明确了，Agent 只需要做一件事——找出这份实现和预期之间的差距。它的输入是确定的，输出是文本，不涉及任何写操作。这就把风险控制在了最低。
我实测下来的感受是：让 Codex 生成一个模块，十次里有三次需要大改；让它评审一个模块，十次里有八次能指出我自己都没注意到的问题。这个投入产出比的差距，就是我坚持用独立评审的根本原因。
2.2 Headless 模式在评审场景下的天然优势
Headless 这个词，字面意思是“无头”，指的是没有交互式界面、直接以命令行方式运行。很多人觉得 Headless 就是“给 CI 用的”，其实它在评审场景下有独特的优势。
第一，输出可管道化。评审结果是一段文本，你可以直接重定向到文件、传给下一个工具、或者塞进 PR 评论里。交互式界面反而会打断这个流程。
第二，上下文可控。Headless 模式下你可以精确指定喂给 Agent 的文件范围，不会像交互模式那样被历史对话污染。评审最怕的就是“记忆”里混进了无关信息，导致判断失准。
第三，可重复。同一份代码，同样的参数，跑两次结果应该基本一致。这对评审来说很重要，因为你需要的是稳定的判断，而不是每次都不一样的“灵感”。
第四，易于并行。你可以同时起多个 Headless 进程，一个审安全、一个审性能、一个审可读性，互不干扰。这就是后面要讲的“子代理”思路。
2.3 子代理架构：把评审拆成多个独立视角
单个 Agent 做评审，最大的问题是“什么都审，什么都审不深”。你给它一段代码让它评审，它往往会给你一堆泛泛而谈的建议，比如“建议增加错误处理”“建议补充注释”，这种评审没有价值。
我的做法是用子代理把评审拆成多个独立视角。每个子代理只负责一个维度，比如：
- 安全子代理：只看输入校验、权限边界、敏感数据流向
- 逻辑子代理：只看分支覆盖、边界条件、状态机是否闭合
- 性能子代理：只看循环嵌套、重复计算、不必要的 IO
- 可维护性子代理：只看命名、耦合度、函数长度
每个子代理都是独立的 Headless 进程，喂给它的 prompt 只聚焦一个维度。这样出来的评审意见，深度和针对性都远超单个 Agent 的泛泛而谈。
提示：子代理之间不要共享上下文。共享上下文会让它们互相“带偏”，比如安全子代理看到逻辑子代理的结论后，可能会不自觉地附和。独立进程、独立输入，才能保证视角的独立性。
3. Codex CLI 在评审场景下的核心配置与实操要点
3.1 安装与基础环境确认
Codex CLI 的安装本身不复杂，但有几个点容易卡住。我按 Windows 和 macOS/Linux 分别说一下。
Windows 下最常见的两个问题：一是安装卡死，二是提示“windows 设置未完成”。安装卡死通常是网络问题，建议先确认基础环境能正常访问包管理源。设置未完成一般是环境变量没配好，装完之后要确认codex命令能在新的终端窗口里直接调用。
macOS/Linux 下相对顺畅，但要注意 Node 版本。Codex CLI 对 Node 版本有要求，太老的版本会在启动时报错。我一般用node -v先确认一下，低于要求就先升级。
装完之后第一件事是验证：codex --version。能打印出版本号，说明基础安装没问题。如果这一步就报错，后面所有配置都无从谈起。
3.2 配置文件解析：哪些参数真正影响评审质量
Codex 的配置文件是评审质量的关键。很多人装完就用默认配置，结果评审出来的东西很水。我重点说几个真正影响评审质量的参数。
模型选择。这是最核心的。评审任务对模型的推理能力要求高，对生成速度要求低。所以应该选推理能力强的模型，而不是追求快。如果你看到类似the 'gpt-5.6-sol' model is not supported when using codex with a...这种报错，说明你配置的模型名和当前 Codex 版本不匹配，需要换成受支持的模型标识。
上下文窗口。评审大文件时，上下文窗口不够会导致 Agent 只看到片段，评审结论就会片面。我的经验是，评审单个文件时，确保整个文件能完整放进上下文；评审多个文件时，优先保证核心文件完整，次要文件可以只给摘要。
温度参数。评审场景下温度要调低。温度高会让 Agent “发散”，给出很多天马行空但不切实际的建议。低温度让它的判断更稳定、更聚焦。
输出格式。建议在配置里约定输出为结构化格式，比如按“问题等级 / 位置 / 描述 / 建议”四列组织。这样后续处理起来方便，也逼着 Agent 把话说清楚，而不是写一大段散文。
3.3 评审 Prompt 的写法：把“审什么”说死
Prompt 写得好不好，直接决定评审质量。我总结了一个模板，实测下来很稳：
你是一名严格的代码评审员。请只针对以下维度进行评审：[维度名称]。 评审对象： [代码内容或文件路径] 评审要求： 1. 只报告该维度下的问题，不要发散到其他维度 2. 每个问题必须给出具体位置（文件:行号） 3. 每个问题必须说明为什么是问题，以及可能导致的后果 4. 按严重程度排序，严重问题在前 5. 如果该维度下没有问题，明确说“未发现该维度问题”，不要硬凑 输出格式： - [严重程度] 位置：描述。后果：...。建议：...这个模板的关键在于“把审什么说死”。你不说死，Agent 就会自由发挥；你说死了，它就只能在这个框里干活。实测下来，加了“只报告该维度”和“不要硬凑”这两条之后，评审意见的噪音大幅下降。
3.4 输入范围控制：别把整个仓库喂进去
新手最容易犯的错，是把整个仓库路径丢给 Agent 让它自己看。结果就是它要么看不过来，要么随机挑几个文件看，评审结论完全不可控。
正确做法是精确控制输入范围。评审一个改动，就只喂这个改动的 diff 加上相关的上下文文件。评审一个模块，就只喂这个模块的文件加上它的直接依赖。
我一般会先自己过一遍，确定这次评审的“最小必要文件集”，然后只把这些文件喂进去。这样 Agent 的注意力集中，评审深度也够。文件太多时，宁可分多次评审，也不要一次性全塞进去。
4. 独立评审的完整实操流程
4.1 第一步：准备评审输入
评审输入的准备，决定了后面所有环节的质量。我的流程是这样的：
先确定评审目标。是要审一个新功能、一次重构、还是一个 bug 修复？目标不同，关注点不同。
然后收集材料。至少要有：改动后的代码、改动前的代码（用于对比）、相关的需求或 issue 描述。如果有测试用例，也一并带上，因为测试能反映预期行为。
最后做一次预处理。把无关的格式化改动、自动生成的代码、第三方库文件剔除掉。这些内容会干扰 Agent 的判断，让它在无关紧要的地方浪费注意力。
注意：不要把包含敏感信息的文件喂给 Agent，比如密钥、凭证、内部配置。评审前先做一次脱敏，这是基本纪律。
4.2 第二步：启动 Headless 评审进程
启动命令的核心是把 prompt、输入文件、输出目标三样东西串起来。以 Codex CLI 为例，大致结构是：
codex --headless \ --prompt-file ./review-prompt.txt \ --input ./src/changed-module.ts \ --input ./src/changed-module.test.ts \ --output ./review-result.md这里有几个实操细节。--prompt-file比直接传 prompt 字符串好，因为 prompt 往往很长，写在文件里便于维护和复用。--input可以多次指定，把需要评审的文件都列上。--output指定输出文件，方便后续处理。
如果你要做子代理并行评审，就起多个进程，每个进程用不同的 prompt 文件和不同的输出文件。比如：
codex --headless --prompt-file ./prompt-security.txt --input ./src/*.ts --output ./review-security.md & codex --headless --prompt-file ./prompt-logic.txt --input ./src/*.ts --output ./review-logic.md & codex --headless --prompt-file ./prompt-perf.txt --input ./src/*.ts --output ./review-perf.md & wait&让它们后台并行，wait等全部结束。这样三个维度的评审同时进行，总耗时约等于最慢的那个，而不是三个相加。
4.3 第三步：结果汇总与人工复核
Agent 评审完，不要直接采信。我的做法是先把多个子代理的结果合并，去重，然后按严重程度排序。合并时要注意，不同子代理可能对同一个位置给出不同维度的意见，这些要保留，因为它们是从不同角度看同一个问题。
然后做人工复核。复核的重点是：Agent 指出的问题是否真实存在、严重程度判断是否合理、建议是否可落地。我实测下来，Agent 的“发现问题”能力很强，但“判断严重程度”有时会偏，需要人工校准。
复核完之后，把确认的问题整理成最终的评审意见。这时候可以再让 Agent 做一次“元评审”——把整理后的意见喂给它，让它检查有没有遗漏或误判。这一步能进一步降低漏报率。
4.4 第四步：把评审接入日常工作流
独立评审要真正产生价值，必须接入日常工作流，而不是偶尔想起来才跑一次。
我的做法是把它挂在提交前。每次准备提交代码前，先跑一遍独立评审，把结果作为提交的一部分。这样评审就成了习惯，而不是负担。
另一个做法是挂在 CI 里。每次 PR 创建时自动触发评审，结果作为 PR 评论贴出来。这样团队里所有人都能看到评审意见，评审的透明度也高了。
提示：接入 CI 时要注意控制评审耗时。如果评审太慢，会拖慢整个流水线。我的经验是，把评审拆成“快速评审”和“深度评审”两档，快速评审只审改动文件，深度评审审全模块，按需触发。
5. 常见问题与排查技巧实录
5.1 启动类问题
问题：codex命令找不到。这是环境变量没配好。装完之后要确认安装路径加进了 PATH，并且在新终端里验证。Windows 下尤其容易出这个问题，因为安装程序有时不会自动改 PATH。
问题：一直显示 reconnecting。这通常是网络或认证问题。先确认基础网络能正常访问，再检查认证信息是否有效。如果认证过期，重新登录一次通常能解决。
问题：提示“无法加载组织设置”。这是配置读取失败。检查配置文件路径是否正确、格式是否合法。配置文件里如果有拼写错误，Codex 会报ignoring 1 unrecognized configuration setting这类警告，虽然不一定致命，但最好修掉。
5.2 评审质量问题
问题：评审意见很泛，没有具体位置。这是 prompt 没写死。加上“必须给出文件:行号”这条要求，泛泛而谈的情况会大幅减少。
问题：评审意见里有大量误报。这是输入范围太宽，或者温度太高。缩小输入范围、调低温度，误报率会明显下降。
问题：评审漏掉了明显的问题。这是上下文不够，或者模型推理能力不足。确保核心文件完整放进上下文，必要时换推理能力更强的模型。
5.3 常见问题速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 命令找不到 | PATH 未配置 | 检查环境变量，新开终端验证 |
| 一直 reconnecting | 网络或认证问题 | 检查网络连通性，重新登录 |
| 无法加载组织设置 | 配置文件路径或格式错误 | 检查配置路径，校验格式 |
| 模型不支持 | 模型名与版本不匹配 | 换成受支持的模型标识 |
| 评审意见泛泛 | prompt 未约束输出 | 加上位置、后果、建议的强制要求 |
| 误报多 | 输入范围宽或温度高 | 缩小输入，调低温度 |
| 漏报明显问题 | 上下文不足 | 确保核心文件完整入上下文 |
5.4 我踩过的几个坑
第一个坑是把评审当生成用。早期我让 Agent 评审完直接改代码，结果它改出来的东西和评审意见对不上，还引入了新问题。后来我严格分开：评审只输出文本，改代码我自己来。这个边界一划清，问题少了一大半。
第二个坑是prompt 写得太长。我以为 prompt 越详细越好，结果写了两千字，Agent 反而抓不住重点。后来我精简到几百字，只保留最关键的约束，效果反而更好。prompt 的关键是“约束清晰”，不是“信息量大”。
第三个坑是忽略子代理的独立性。我一开始让所有子代理共享一个上下文，结果它们互相影响，评审结论趋同。后来改成完全独立的进程，每个子代理只看自己该看的，评审的多样性一下就出来了。
6. 把独立评审用出复利效应
独立评审这套用法，最大的价值不在于单次评审省了多少时间，而在于它能形成复利。
每次评审的结果，我都会归档。时间长了，就积累出一个“问题模式库”——哪些类型的改动容易出哪类问题，哪些位置是历史高发区。这个库反过来可以优化 prompt，让评审越来越准。
另一个复利点是评审意见可以反哺生成。当我知道 Agent 在评审时特别关注某几类问题，我在让它生成代码时就会提前规避这些模式。生成质量上去了，评审的负担就下来了，形成一个正向循环。
还有一点，独立评审让团队协作更顺。以前代码评审靠人，人的精力有限，容易漏。现在 Agent 先过一遍，人只需要复核 Agent 的结论，效率高很多，而且评审标准也更统一。
最后分享一个小技巧：如果你觉得单个维度的评审还不够深，可以试试“递归评审”——让 Agent 评审自己的评审意见，找出其中的逻辑漏洞和遗漏。我试过几次，确实能挖出一些第一轮没注意到的问题。这个用法比较耗资源，适合对质量要求极高的场景。
这套用法我用了大半年，从最初的磕磕绊绊到现在基本稳定，核心就一句话：让 Agent 做它最擅长的事——读和判断，而不是写和改。独立评审这个定位，把 Agent 的能力用在了刀刃上，风险可控，收益明确。如果你还在纠结怎么用 Headless Agent CLI，不妨从独立评审开始，这大概率是最不容易翻车、也最容易看到效果的切入点。
