Codex 工程实践(一):个人与企业如何减少使用漂移
用 Coding Agent 做事,最让人困惑的往往是:同一个仓库、看起来一样的要求,昨天能完成,今天却走了另一条路。终端里能改文件,自动化任务只会读;自己的电脑遵守规范,同事那里又多了一套习惯。
读完《Codex 源码分析》的第 2~5 章,我更倾向于先把这些问题当作运行条件和任务约束的漂移来排查。模型输出存在波动,但入口、配置、工作目录和验收标准的不一致,通常更容易定位和修正。
一、先把“漂移”分成四类
| 漂移类型 | 常见表现 | 优先检查什么 |
|---|---|---|
| 入口漂移 | TUI、IDE、自动化任务行为不同 | 实际版本、启动参数、工作目录、认证方式 |
| 配置漂移 | 换个人就换模型、权限或工具 | 用户配置、项目配置、profile、运行时覆盖及组织要求 |
| 任务漂移 | 修一个错误,最后重构整个模块 | 当前目标、允许修改范围、用户最新纠正 |
| 验收漂移 | 代理说完成,流水线仍然失败 | 检查命令、产物要求、失败条件 |
这四类经常叠加。例如,个人终端选过一个宽松的权限配置,CI 没有;任务只写“修好测试”,没有说能否修改接口。结果两次运行不但能做的事不同,对“完成”的理解也不同。
因此,减少漂移的第一步是记录这次运行的条件。只保存最后一条提示词,很难解释差异。
二、多个入口共享核心,也要核对入口契约
参考第 2 章把启动路径拆成了包装入口、原生运行时和子命令分发。这个拆法提醒我:看到相同的 codex 名字,不能直接认定实际执行条件相同。
以修复一个 Node.js 仓库的日期排序为例。可以用自己的项目,也可以在临时目录搭一个练习仓库,供后面四篇的命令使用。需要 Git 和支持 node --test 的 Node.js(建议 20 或更新)。
1 | repo=$(mktemp -d) |
起始版本按字符串排序,测试预期失败。接下来先在复现问题的终端记录下面几项。IDE 侧从 Codex 扩展的设置打开配置文件,同时核对扩展版本和它选中的工作目录。CI 则把这些命令放到启动 Codex 的同一步执行。
1 | command -v codex |
交互式 CLI 可以用 /status 核对本次会话的模型、工作目录和权限。脚本使用 codex exec 时,我会显式传 -C,并用末尾的 - 让任务只从 stdin 进入。某些 CLI 版本同时收到位置参数和管道输入时会把 stdin 附加到任务后面,排查时要把两个输入都算进去。CLI 命令参考
1 | # 在仓库根目录执行。 |
events.jsonl 用来查工具调用和回合状态,result.txt 供调用方读取最终回答。先检查 Codex 的退出码,再读取结果文件,并从事件里确认测试本身的退出码。两者对应不同的进程。每次使用新的输出目录,失败时就不会误读上一次的产物。
三、配置选择与组织约束要分别理解
启动时,Codex 从配置层解析本次想用的值,再用管理策略约束安全相关选项。仓库指令走另一条路径,由运行时读取并加入模型上下文。遇到同名或相似的设置,先确认自己在改哪一层。
| 文件或来源 | 谁创建、怎样加载 | 日常应该改什么 |
|---|---|---|
$CODEX_HOME/config.toml | 用户维护,CODEX_HOME 默认是 ~/.codex。CLI 和 IDE 扩展使用这套本地配置 | 改个人模型、常用审批方式或私人 MCP。更换机器后先核对 CODEX_HOME |
$CODEX_HOME/audit.config.toml | 用户手动创建,以 codex --profile audit 选中,叠加在用户配置上 | 只放审查场景与默认值不同的字段,例如 sandbox_mode = "read-only" |
<repo>/.codex/config.toml | 仓库维护者创建并提交。可信项目中,运行时从项目根向启动目录加载,更近的设置优先 | 改团队共享的运行默认值,例如 web_search = "disabled"。检查项目是否可信及启动目录是否正确 |
/etc/codex/config.toml(Unix)或云端下发的 config.toml | 管理员或设备管理系统设置,作为本地客户端的默认值来源 | 改组织希望用户默认采用的值,给个人和项目保留覆盖空间 |
requirements.toml 和托管要求 | 管理员通过系统文件、Agent Security 或设备管理下发,由运行时校验 | 改允许的审批方式、沙箱范围或托管能力。需要例外时由管理员改对应策略 |
AGENTS.md | 项目维护者写入仓库,或用户在 Codex home 写个人指令,由运行时发现并拼进上下文 | 改测试命令、目录约定、兼容要求等开发流程 |
普通配置从高到低依次取 CLI 参数和 -c 覆盖、可信项目配置、选中的 profile、用户配置、云端默认、系统默认和内置默认。比如个人 profile 要只读,可信项目却设置了 workspace-write,项目值优先。这次只做审查时可以显式传 --sandbox read-only,再用 /status 确认。若组织已经限定沙箱选项,命令行也只能请求允许的模式。配置层与优先级
管理员实际改哪一个文件
以仍用 sandbox_mode 的本地部署为例,管理员可以把以下内容写入 Unix 设备的 /etc/codex/requirements.toml,或 Windows 设备的 %ProgramData%\OpenAI\Codex\requirements.toml。使用工作区策略的团队,可以在 Agent Security 的 Policy guardrails 设置相同的允许项。普通项目维护者在仓库创建同名文件,不会获得管理员策略的加载位置。
1 | allowed_sandbox_modes = ["read-only", "workspace-write"] |
第一行限制可选沙箱,第二行只允许按需审批。采用命名权限配置的团队,应配置 allowed_permission_profiles 和托管的 default_permissions。下发后在测试设备上运行 codex --sandbox read-only -a on-request,用 /status 核对生效值。再把 -a 后面的值改为 never,查看启动诊断,并确认当前会话没有得到 never。如果 CI 需要无人值守,应由管理员针对 CI 执行环境设置允许项,再重新验证。托管配置及下发位置
本地执行时,系统 requirements、Agent Security、旧版 managed_config.toml 转换出的要求、macOS MDM 依次提高优先级。旧版 Unix 设备检查 /etc/codex/managed_config.toml,使用 MDM 的 macOS 设备则由管理员检查 com.openai.codex 域下的 requirements_toml_base64 配置项。普通标量和列表可以由高层覆盖,命令规则、hooks、文件限制有各自的合并方式。参考第 3 章的旧实现对 requirements 使用逐字段填空,所以下发后应使用团队实际部署的客户端复测。配置加载器中的合并实现
我建议运行记录至少保留以下信息,凭据只记录方式和来源,不记录密钥:
1 | 运行身份:客户端版本、运行时版本、仓库提交、工作目录 |
这份记录是排障用的快照。即使不追求逐次完全复现,它也能把“好像一样”变成可以比较的条件。
四、个人使用:把稳定规则留在仓库里
个人最容易遇到的是规则散落:测试方法在前一个聊天里,目录约定在另一个笔记里,当前任务还继承了过时的决定。
在仓库根目录手写 AGENTS.md,也可以用 TUI 的 /init 生成初稿后再核对。下面以自带 Node 测试的项目为例,把测试路径换成仓库真实路径。每次修什么、临时允许改哪些文件,则写进当次任务。
1 | # 项目约定 |
运行时先找 Codex home 下的个人指令,再沿项目根到启动目录逐级发现文件。每级优先用 AGENTS.override.md,其次是 AGENTS.md,再查 project_doc_fallback_filenames 指定的文件名。每级取一份,后拼入的近目录规则可以覆盖前面的项目指导。假设 src/AGENTS.md 额外要求同一时刻的日期保持输入顺序,分别从根目录和用 codex -C src 开新会话,让它先复述已载入的指令与测试命令,观察这条规则在哪个启动目录出现。规则太长时还要检查 project_doc_max_bytes,以及近层是否被 AGENTS.override.md 取代。项目指令发现规则
对长任务,我会在阶段切换时核对三个东西:当前要解决的问题、已经验证的事实、下一步动作。用户改变方向时,把旧决定标成已替代,避免新旧要求同时看起来有效。
五、企业使用:基线、例外和结果都要可审查
企业可以在个人做法上增加三层管理。
第一层是运行基线。固定经过验证的版本和配置组合,为终端、IDE 与 CI 建立一组共同的验收任务。这里的固定是升级前有验证依据,并非永远不升级。
第二层是例外机制。临时增加写目录或外部访问时,记录用途、适用范围和结束条件。任务完成后回收例外,避免一次排障变成长期扩大权限。
第三层是结果契约。让自动化任务分别输出过程事件与最终结果,再由调用方检查产物和验收条件。即使请求使用 JSON Schema,也应检查任务是否成功结束、字段是否齐全、引用文件是否真实存在。结构正确只能说明格式可消费,不能说明工作已经完成。
如果 CI 还负责修复,可以把只读审查的启动模式换成组织允许的 workspace-write,并在任务里限定只改排序实现。调用方可以维护一份结果 Schema,通过 --output-schema /path/to/result.schema.json 约束最终回答的格式。下面是一个可能的结果。随后由 CI 自己读 git diff --name-only,并运行 node --test tests/sort-dates.test.mjs,用实际文件范围和测试退出状态决定是否通过。
1 | { |
升级时,可以从团队常见任务中挑选少量固定样例:一个局部修复、一个跨目录修改、一个权限应被拒绝的操作、一个需要恢复的任务。比较的不只是答案,还包括修改范围、工具使用、检查结果与拒绝行为。
这种做法无法消除模型的全部随机性,但能帮助团队判断:差异来自能力波动、运行条件变化,还是任务定义不清。
六、从一次偏航中恢复
如果代理已经改偏,继续补一大段“以后注意”通常收效有限。我更愿意先检查当前差异,明确哪些修改保留、哪些撤回,再用现有文件与检查结果重建下一步。
例如任务原本只要求修正日期排序,却引入了新的时间库。恢复时应明确是否允许新增依赖,核对现有排序测试,并把下一步收敛到具体文件和行为。不要让代理为了维护先前方案而继续扩大修改。
个人可以从一份简短的项目约定开始;企业则需要把运行基线、组织约束与验收记录接起来。每次出现差异时,都能回答“本次究竟在哪些条件下执行了什么”,漂移才有机会被稳定地治理。
参考阅读
下一篇:上下文管理:怎么压缩,怎么拼接。