Headless Agent CLI 独立评审实战：Codex 子代理配置与避坑指南

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不妨从独立评审开始这大概率是最不容易翻车、也最容易看到效果的切入点。