建议收藏 | Codex Rust vs Codex Agent：代码审查配置

▌ 技术引导
Codex Rust和Codex Agent在代码审查配置中存在本质差异。Rust项目使用Codex时，必须通过cargo配置文件注入审核参数，而Agent模式则依赖环境变量全局配置。我见过很多项目因为没正确设置`cargo fmt`的`--check`标志，直接导致代码格式化失败。实际部署中，Agent模式对代码库规模更敏感，300万行以上的项目容易卡顿。Rust的`clippy`插件在Codex中必须显式启用，否则无法触发高级错误检查。Codex Agent的API接口需要绑定hostip和port，配置文件中若有`--secret`参数会自动加密。我踩过的坑包括：在CI中未区分main分支和feature分支，导致Codex Agent持续触发错误；未正确设置`cargo.toml`的`[workspace]`块，导致多模块项目无法统一检查。这些细节必须写进配置文件，否则整个审查流程会出问题。

▌ 技术参考

一 Codex Rust审查配置的核心是cargo.toml的[tool.cargo-clippy]部分。必须在该块中添加`deny`或`warn`字段，例如`deny(warnings, clippy::all)`。这会强制启用所有clippy规则。同时，确保`[package]`块存在`edition = "2021"`，否则clippy无法兼容Rust 2021语法。在CI中，需要执行`cargo clippy --all-targets --all-features -- --deny warnings`，注意`--`是必须的，用于传递clippy选项到编译器。如果项目包含子模块，`[workspace]`块必须设置`members = ["path/to/submodule"]`，否则Codex无法识别子模块代码。

二 Codex Agent的配置则通过环境变量`CODEX_AGENT_PORT`和`CODEX_AGENT_SECRET`实现。这两个参数必须在启动时设置，否则Agent无法连接。例如，在Docker中使用`-e CODEX_AGENT_PORT=8080 -e CODEX_AGENT_SECRET=mysecretkey`。Agent的默认端口是8080，但可以自定义。如果项目较大，使用Agent时需要在`.codexrc`文件中设置`max_lines = 500000`，防止内存溢出。同时，确保`CODEX_AGENT_HOST`指向正确的服务器IP，否则审查过程会失败。Agent支持的参数包括`--check`、`--fix`和`--format`，这些参数必须写入环境变量，不能硬编码。

三 Codex Rust在配置时容易忽略`[tool.cargo-metadata]`块，这个块用于定义依赖树。例如，若项目使用`workspace`，必须在`metadata`中指定`workspace = true`，否则Codex无法正确解析依赖关系。另外，Codex Rust的`--deny`参数与`--warn`参数不能同时使用，这会导致编译器崩溃。我在一个实际项目中因为同时使用了这两个选项，导致CI持续集成失败。需要特别注意的是，`cargo clippy`的`--target`参数必须与`codex`的`--target`参数对应，否则审查结果不一致。

四 Codex Agent的审查规则配置需要在`.codexrc`中添加`rules = ["clippy::all", "rustfmt::check"]`。这会确保Agent运行时自动加载这些规则。如果项目中有自定义规则，必须通过`rules_path`参数指定路径，例如`rules_path = "./custom_rules.toml"`。同时，如果使用`rustfmt`进行格式检查，必须在`.codexrc`中设置`format = true`，否则审查不会自动格式化代码。Codex Agent支持在审查时根据分支名称动态切换规则集，例如通过`branch = "main"`触发更严格的检查。

五 在实际应用中，Codex Rust与Codex Agent的审查流程存在性能差异。Codex Rust的每次审查时间在100MB以下项目中稳定在5秒内，但超过300MB时会增加到20秒以上。而Codex Agent的性能更受网络延迟影响，如果服务器在本地，审查时间可以控制在10秒以内，但跨网络时可能达到30秒。因此，在大型项目中，选择Codex Agent需要权衡网络带宽和服务器负载。我见过一个项目因为Agent服务器在云上，导致审查时间翻倍，最终改用Rust本地审查模式。

六 Codex Rust的配置文件必须位于项目根目录，否则无法被正确加载。例如，执行`cargo clippy --config codex.toml`会触发配置文件的使用，但若`codex.toml`不在根目录，会报错。Codex Agent的配置则必须通过环境变量传递，如`export CODEX_AGENT_SECRET=mysecretkey`。在Docker容器中，需要将`.codexrc`文件挂载到指定路径，例如`-v /host/path:/app/path`。如果配置文件中有动态参数，例如`token = "mytoken"`，必须在运行时通过环境变量覆盖，否则会触发认证错误。

七 Codex Agent的审查结果可以通过`--output`参数指定为JSON格式，例如`--output /var/lib/codex/review.json`。这个文件可以被后续的CI工具解析，用于生成报告。同时，Codex Agent支持`--dry-run`参数，可以模拟审查过程，检测配置是否存在错误。我之前在一个项目中误用了`--dry-run`，导致审查结果被缓存，后续审查没有触发。必须在每次提交后清除缓存，否则会重复输出旧结果。

八 Codex Rust的审查日志通常存储在`target/codex/log/`目录下，日志文件名包含时间戳和提交哈希。例如`codex_20240712_123456_abc123.log`。如果日志文件过大，可以设置`log_max_size = "10MB"`来限制大小。Codex Agent的日志则存储在服务器的`/var/log/codex/`目录，可以通过`tail -f /var/log/codex/review.log`实时查看。在调试时，建议将`log_level`设为`debug`，例如`CODEX_AGENT_LOG_LEVEL=debug`，这样可以获取更详细的执行信息。

九 Codex Rust审查时，若未开启`--workspace`参数，会忽略子模块。例如执行`cargo clippy --workspace`才能触发子模块检查。Codex Agent则默认支持全局审查，但需要配置`workspace = true`，否则只能审查主项目。在实际操作中，Codex Agent的`workspace`参数可能被忽略，导致审查遗漏部分代码。我曾在一个多模块项目中遇到这种情况，通过手动添加`workspace = true`才解决。

十 Codex Rust的`deny`规则必须与`clippy`的`deny`规则一致，否则会引发冲突。例如，若`cargo clippy`的`deny`设置为`warnings`，而`codex`的`deny`设置为`warnings, clippy::all`，会导致重复检查。正确的做法是统一使用`deny(clippy::all)`，并确保`clippy`插件已安装。Codex Agent的规则检查则完全由`rules`参数控制，必须在配置文件中明确指定，例如`rules = ["clippy::all", "rustfmt::check"]`。

十一 Codex Rust的审查结果可以通过`--output`参数导出为`json`格式，便于集成到CI系统。例如`cargo clippy --all-targets --all-features --output=json`。Codex Agent的输出则需要通过`--output`指定路径，同时支持`--format=json`，以便解析。在CI脚本中，通常会使用`codex agent run --output=/tmp/review.json`，并检查返回码。如果返回码为0，表示审查通过；若为1，表示存在错误。

十二 Codex Rust与Codex Agent的审查缓存机制不同。Codex Rust的缓存位于`target/codex/`，可以通过`--no-cache`参数禁用，例如`cargo clippy --no-cache`。Codex Agent的缓存则存储在服务器端，可以通过`--clear-cache`参数清理，例如`codex agent run --clear-cache`。在频繁提交的项目中，缓存可能积累大量错误数据，导致性能下降。建议定期清理缓存，或者在CI中设置`--no-cache`避免重复审查。

十三 Codex Agent的`--secret`参数必须在容器启动时通过环境变量传入，否则无法通过身份验证。例如在Kubernetes中，需要通过`env`字段设置`CODEX_AGENT_SECRET`，否则会触发401错误。同时，`--secret`参数需要与服务器端匹配，否则审查失败。我见过一个项目因为`secret`字段拼写错误，导致所有提交无法通过审查。

十四 Codex Rust的`--check`参数用于仅检查格式而不修复，适合CI中进行自动化审查。例如`cargo clippy --check --fix`会同时检查和修复，但若设置`--check-only`，则只检查不修复。Codex Agent的`--check`参数行为类似，但需要在客户端配置中设置`check = true`。在实际部署中，我推荐使用`--check --fix`来确保代码质量，同时减少CI耗时。

十五 Codex Rust的`--target`参数必须与`clippy`的目标一致，否则无法正确检查代码。例如，若项目使用`no_std`，需要在`cargo clippy`中设置`--target no-std`。Codex Agent的`--target`参数同样需要匹配，否则会报错“target not found”。在多平台项目中，需要为每个目标单独配置，例如`--target x86_64-unknown-linux-gnu`。

十六 Codex Rust的`--profile`参数用于指定审查的配置文件，例如`--profile review`。这个参数必须在`cargo clippy`命令中显式设置，否则会使用默认配置。Codex Agent的`--profile`参数则通过`.codexrc`文件定义，例如`profile = "review"`。在实际配置中，需要确保`codex.toml`或`.codexrc`文件存在，并且路径正确。

十七 Codex Agent的`--timeout`参数用于限制审查时间，例如`--timeout 30s`。这在大型项目中非常有用，防止审查过程阻塞CI流程。同时，`--timeout`参数必须与服务器端的`max_review_time`配置匹配，否则会触发超时错误。我曾在一个审查时间过长的项目中设置`--timeout 60s`，但服务器端未同步，导致审查失败。

十八 Codex Rust的`--config`参数用于指定配置文件路径，例如`--config codex.toml`。这个参数必须与`codex`的`--config`路径一致，否则会触发“config not found”错误。Codex Agent的`--config`参数则通过环境变量`CODEX_AGENT_CONFIG`设置，例如`export CODEX_AGENT_CONFIG=/etc/codex/config.toml`。配置文件中必须包含`rules`和`secret`字段，缺少任何一个会导致审查无法启动。

十九 Codex Agent的`--format`参数控制代码格式化方式，例如`--format rustfmt`。这个参数必须与`rustfmt`的配置文件一致，否则格式化结果不一致。在CI中，建议将`--format`设置为`rustfmt`，并确保`rustfmt`的配置文件位于项目根目录。若格式化失败，可以使用`--fix-only`参数仅修复格式，而不触发错误检查。

二十 Codex Rust的`--workspace`参数必须与`cargo`的`workspace`配置匹配，否则会忽略子模块。例如，在`cargo.toml`中设置`workspace = true`后，执行`cargo clippy --workspace`才能触发所有子模块审查。Codex Agent则默认支持`workspace`模式，但需要在配置文件中明确设置`workspace = true`，否则会遗漏部分代码。