围绕 Codex 配合 Harness 工作流做工程实践时我见过太多人在“审批模式”“沙箱模式”“AGENTS.md 怎么组织”这三个开关之间反复横跳。单项大家都能说出个大概一旦要组合起来12 种排列摆在面前就彻底不知道怎么选了。这篇文章不是给你讲 UI 按钮在哪里而是把三套机制拆开揉碎结合我实际跑项目时踩过的坑把每一种组合背后的代价、适用场景和配置方法一次说清楚。看完你就能按自己的风险偏好和项目阶段直接抄一份配置走。1. 先把三个开关各自的“管辖范围”搞清楚很多人把审批、沙箱、AGENTS.md 当成同一类东西其实它们管理的根本不是同一个维度。用个不太严谨但很好记的说法审批管的是“谁拍板”沙箱管的是“能碰哪些地方”AGENTS.md 管的是“AI 脑子里预装的工作手册”。三者正交互相不能替代。1.1 审批档位谁说了算的问题审批解决的是“AI 要做一件有副作用的操作时要不要先问我”。比如它要执行一条写文件的命令、调用一次外部 API、或者跑一个 package 安装脚本这些操作发生后不可轻易回退这时候就需要一道人工闸门。实操中常见的审批档位大致有四种自动接受全部操作AI 说什么就是什么操作直接执行。适合完全信任的场景比如纯读代码、没有任何写操作的会话。按类别审批区分“读操作、写操作、命令执行、网络访问”等类别读操作放行写操作和命令执行弹出确认。这是我最常用的档位。全部操作均需确认每一步都要点一下包括最简单的文件读取。适合第一次接触某个项目的陌生代码库或者审计需求强的场景。混合模式预置一个“可信命令清单”清单内的命令自动放行清单外的全部拦截确认。这是从“审批”走向“半自动”的关键设计。换句话讲审批档位直接决定你在这场人机协作里“遥控器”按得勤不勤。档位越高安全边际越大但你的注意力被切碎的频率也越高。1.2 沙箱档位AI 改坏了东西能不能收回来的问题沙箱管的是“AI 进程在操作系统层面的活动边界”。它不关心该不该做某个操作只关心“做这个操作在不在允许范围内”。我把沙箱简单理解成给 AI 开了一间带锁的屋子屋子里随便折腾屋子外的东西只能看不能动。实际部署时常见的沙箱档位是这样的沙箱模式读访问写访问命令执行网络访问典型用途完全开放全部全部全部全部本地个人极速验证读写受限全部仅项目目录部分允许白名单日常开发主力档严格只读项目目录可读仅临时目录可写禁止大部分命令禁止代码评审、批量检查沙箱的作用是让你可以放心地让 AI 在项目里跑“折腾型”任务——比如让它重构一个函数、批量替换变量名。即使 AI 改错了它也出不了沙箱边界最多污染项目内文件靠 git 就能回滚不会把你的系统环境搞乱。1.3 AGENTS.mdAI 脑子里预设的“该做什么、别做什么”AGENTS.md 是给 AI 读的项目说明文件相当于给新入职的工程师发一份“团队手册”。它解决的不是权限问题而是“方向问题”。一个好的 AGENTS.md 至少包含四层信息项目身份这是什么项目、用了什么技术栈、目录结构大概什么样。常用命令构建命令、测试命令、Lint 命令、单测跑法写得越具体AI 越不会瞎猜。代码风格与禁区比如“不可修改公共 API 签名”“新增依赖必须经过确认”“错误处理统一用某个模式”。工作流约定比如“改完代码必须跑特定测试”“提交前必须执行 lint”。AGENTS.md 可以由多层级构成全局级放在用户配置目录、项目级放在仓库根目录、目录级放在某个子模块下。Codex 读取时遵循就近合并原则子目录的规则会叠加在项目级之上。2. 十二种组合全览先看代价再谈适配按审批 2 档自动 / 需确认、沙箱 2 档受限写 / 严格只读、AGENTS.md 2 档无手册 / 有完整手册来算正好是 8 种基础组合。再加上按类别审批、混合审批这种细分档位实际会凑出 12 种左右。我按风险从低到高排了一张表后面逐个说明。2.1 组合速查表与风险定价组合编号审批沙箱AGENTS.md风险等级典型场景C1自动开放无极高一次性临时脚本跑完即焚C2自动开放有高个人玩具项目想省事C3自动受限写无高信不过但懒得管C4自动受限写有中高个人项目熟练工C5自动严格只读无中只读型代码搜索C6自动严格只读有中批量读取分析任务C7需确认开放无中半信半疑阶段C8需确认开放有中低正规个人开发C9需确认受限写无中低想加保险丝C10需确认受限写有低个人/小团队标准配置C11需确认严格只读无低审计型只读审查C12需确认严格只读有极低核心资产、严格审查表格只是骨架关键在下面两点判断逻辑。2.2 从风险偏好倒推组合拒绝完美主义先定底线我见过不少人在选型时犯同一个错误总想把三个维度全部拉满最后配出来的组合极其繁琐——每一步操作都弹审批、沙箱限死导致构建命令跑不动、AGENTS.md 写了一大堆互相矛盾的规则AI 直接陷入“啥也不敢干”的状态。正确姿势是先想清楚你在当前项目里最能承受的失败模型是什么。分三种情况如果项目可以随时推倒重来比如学习仓库、demo、原型沙箱和审批都可以大幅度放权重点放在 AGENTS.md 的质量上。如果项目有真实的业务价值但不能出人命比如个人作品、内部工具审批必须保留按类别的档位沙箱建议受限写AGENTS.md 写核心命令和禁区就够。如果是多人协作、有明确交付期限的正式项目那审批建议逐步加强到“需要确认”沙箱锁到受限写AGENTS.md 必须写进团队规范和工作流约定。简单说12 种组合不是让你从里面挑一个最好的而是让你按“最坏情况可接受”来反选然后往下调一档给自己留一点操作弹性。3. 四类典型团队的真实选型经过选型这件事理论讲再多都不如看具体场景。我拿自己带过的四类项目举例每类的约束条件差别很大最后组合出来的方案也完全不同。3.1 个人学习型项目C2 组合重点押注 AGENTS.md这个场景下项目是拿来练手的代码写错了大不了重来毫无心理负担。审批全开、沙箱放开没什么问题唯一值得花时间的是写一份过得去的 AGENTS.md。我实际的做法是把 AGENTS.md 当成“需求速写板”。每次准备让 AI 干活之前先花 5 分钟更新这个文件写清楚本次要完成什么目标、用哪个命令验证结果。AI 每次读到的是最新版手册就不会反复问“我该怎么做”。这种组合看起来风险高实际是我用得最顺的——因为它把节省下来的审批时间和沙箱干扰全部转化成了迭代速度。3.2 个人正式项目C10 组合按类别审批 受限写沙箱 双层 AGENTS.md个人作品想保持稳定我就会把档位拉到 C10。审批模式设为“按类别”读文件自动过写文件和执行命令弹确认。沙箱锁到“仅项目目录可写”网络请求全部白名单化。AGENTS.md 采用双层结构仓库根目录放全局约定关键子目录放专属规则。这套组合的体验很微妙日常小改动几乎不打断我但一旦 AI 想动“不该动的东西”——比如去修改依赖锁定文件、尝试访问项目外的路径——它立刻会被拦下来。我实际统计过一个 8 小时的工作日里大概会有 10-15 次审批弹窗集中在真正有价值的决策点上不会有“审批疲劳”。3.3 团队协作项目C10 升级版混合审批 受限写沙箱 强约束 AGENTS.md团队场景和个人最大的区别是你没法假设每个人都对项目了如指掌。有人只会点审批通过根本不管你弹出来的是什么。这时候就不能用“需确认”这种一刀切的玩法而是要用混合审批——把构建、测试、格式化这类“安全命令”放进白名单自动执行把依赖安装、网络请求、文件批量移动这类“高风险操作”强制拦下。同时 AGENTS.md 要开始写负面清单。我见过最惨痛的例子是一个同事放 AI 跑测试结果 AI 顺手改了数据库迁移文件因为 AGENTS.md 里只写了“请确保测试通过”没写“禁止改动 db/migration 目录”。后来我在团队的 AGENTS.md 里把禁区写成了显式规则“遇到 migration 目录下的任何文件一律停止并报告。” 从那以后类似事故再没发生过。3.4 只读审计场景C12 组合全部确认 严格只读 全量 AGENTS.md有一种特殊场景不需要 AI 写任何代码只需要它做代码审查、安全扫描、架构梳理。这种活儿的核心价值是“只读绝不污染”。我把沙箱开到严格只读审批全部需要确认AGENTS.md 里写清项目背景和审计关注点。这个组合看起来很极端实际上手体验反而安静——因为所有操作都是读操作而严格只读沙箱对读操作不设卡审批弹窗只在 AI 尝试写操作时出现正常审计流程下几乎不会触发。也就是说极端配置不一定等于极端繁琐关键是选对场景。4. 落地实操Codex 环境里的具体配置法光知道选哪种组合还不够关键是把组合落到实际的配置里。这一节给可直接抄的配置方法和 AGENTS.md 模板。4.1 审批与沙箱的落点策略文件加 CLI 参数在 Codex 的配置体系里审批和沙箱实际是由两套东西控制的一套是运行时的策略参数另一套是工作流文件里的执行策略。以我常用的配置为例策略部分大致长这样[approval_policy] mode category # auto / category / all / hybrid auto_allow_categories [read_file, search, glob] [category_policy.requires_approval] write_file true execute_command true network_request true [sandbox] profile restricted_write # open / restricted_write / read_only allowed_write_paths [/path/to/project] allowed_commands [npm run test, npm run lint, git status, git diff] network_whitelist [registry.npmjs.org, api.github.com]这份配置对应的是 C10 组合读文件不需要确认写文件和执行命令、发网络请求都需要我过目沙箱只放行项目目录写入命令白名单自动过。如果要把档位拉到 C2改两个地方approval_policy 的 mode 改成 autosandbox profile 改成 open。如果做 C12就把 category 换 allprofile 改成 read_onlyallowed_commands 里只保留 git 相关命令。4.2 AGENTS.md 推荐结构别写成论文写成速查卡我在多个项目里反复打磨出来的结构核心原则就一句话AI 读的时候 10 秒内能找到关键信息。太长的 AGENTS.md 反而会让 AI 抓不住重点。# 项目Harness 工作流引擎 ## 项目结构速览 - src/ 主业务代码按模块划分 - tests/ 单测目录测试文件名与模块一一对应 - scripts/ 自动化脚本仅 CI 调用 ## 常用命令 - 构建npm run build - 单测npm run test -- --runInBand - Lintnpm run lint - 类型检查npx tsc --noEmit ## 关键约束 1. 禁止修改 src/engine/executor.ts 的公开接口签名 2. 新增依赖必须列出理由并等待确认 3. 错误处理统一使用 AppError 类禁止裸 throw string 4. 修改涉及沙箱配置的文件时必须查阅 docs/security.md ## 工作流约定 1. 所有变更必须添加对应单测 2. 单测跑完才能报告“完成” 3. 需要跨模块改动时先输出改动计划再动手注意最后一条——它实际上给自己的审批策略加了一道前置检查让 AI 先输出计划相当于在“写代码”这一步之前先加了一道隐形审批。这是很多团队忽略的妙用AGENTS.md 不只能写“禁止做什么”还能约定“做事顺序”从流程层面控制风险。4.3 两个高频报错的根源都在配置错位我搜了一下自己团队内部的报错记录有两个问题出现的频率异常高顺带在这里一起拆了“local proxy failed”类错误多半出在沙箱网络白名单配了但没覆盖到 Codex 自身的服务端口。默认配置只放行了业务 API 域名结果 Codex 在回连本地调试服务时被沙箱拦了。解决办法是在网络白名单里把localhost和回环地址放进去而不是去动网络代理的全局配置。这是典型的“沙箱适配”问题不是网络问题。“harness failed to load plugins”类错误出现在审批策略引用了未注册的插件命名时比如策略文件里写了mode auto_approve但实际版本只认autonomous。这类问题跟组合选择没有关系纯粹是版本字段不匹配。我的习惯是在每次升级 Codex 后跑一次旧配置看有没有报 deprecated 提示尽早迁移。5. 选型时最容易被忽略的边界问题讲完配置最后提醒几个我踩过的“隐性坑”。这些东西在文档里几乎不会写但实际影响非常大。5.1 审批和沙箱是两套正交机制千万别当成一个东西我见过有人把沙箱调到最高档于是觉得审批可以放宽一点——这想法很危险。沙箱管的是进程级别的系统调用边界审批管的是“你要做的事值不值得做”。一个恶意或迷路的 AI 程序即使被沙箱限制在项目目录内它也可能做出“删除项目内所有文件”这种操作。沙箱限制不了这种破坏因为删除项目文件是合法写操作。必须有审批或显式命令白名单兜底。反过来审批拦得住大动作但拦不住反复的小动作——比如连续 50 次小范围修改把代码改得面目全非。这时候除了审批还得靠“计划-执行-验证”的流程约束和 git 回滚防线。5.2 AGENTS.md 写得太细AI 会变得极度保守有次我给一个正式项目写了整整 400 行的 AGENTS.md把代码风格、命名规范、目录规则、异常处理全部细化到极端。结果 AI 的行为变得极其僵硬——几乎每个操作都要停下来问“这句代码没在 AGENTS.md 里找到对应规则是否可以执行”效率惨不忍睹。后来我把制度性内容必须做的事、禁止做的事和技术性内容具体的实现方式建议区分开AGENTS.md 只保留前者后者全部移到 docs 里作为参考。效果立刻好转。核心原则AGENTS.md 是控制行为边界的不是控制实现细节的。5.3 非交互场景下的审批会“闪断”Codex 在交互式终端里弹审批是正常的但如果你把它接入 CI 流水线或自动化脚本非交互模式下审批策略的行为会不一样。很多人在自动化场景里沿用“需确认”模式结果发现任务被挂起、超时最后整个工作流直接判失败。要跑自动化任务审批模式必须通过策略参数强制设定为“自动接受特定安全类别”的白名单模式或者直接使用完全自动模式。我的建议是自动化任务沙箱从严只读或受限写审批从宽白名单自动放行用沙箱代替审批来兜底。5.4 “严格只读”对构建类任务的真实影响严格只读沙箱下npm install这类需要写node_modules的命令会直接失败。不是报权限错误就是报磁盘写入失败。很多人第一次遇到这问题就懵了以为是命令本身有问题。实际上你只要在“临时目录可写”这类例外里加上构建缓存目录问题立刻消失。具体配置上我把allowed_write_paths设为项目目录加一个专门的临时构建目录沙箱攻击面没有变大但构建类任务能正常跑。这个细节我称之为“带锁的抽屉里开个小保险箱”既兼顾了安全也不耽误日常构建。6. 我实际用的选择决策流五步走不再纠结最后分享一套我每次接新项目都会走一遍的快速决策流帮你把“12 种组合怎么选”彻底变成流程题。先回答一个问题项目黄了代价多大如果是学习项目直接走 C2如果是商业项目至少 C10 起步。这一步就淘汰掉一半组合。再回答AI 会被要求做什么类型的工作纯读为主选只读沙箱要改代码选受限写要跑构建、装依赖就要留临时写权限。这一步基本把沙箱档位定死。然后回答你在场吗全程人工盯就上混合审批把安全操作列白名单跑批处理直接自动模式加沙箱兜底需要审计记录的所有写操作强制确认。接着花 15 分钟写 AGENTS.md。不要多写就写四件事项目简介、常用命令、三条硬性约束、一条工作流约定。这是全流程里性价比最高的一步。最后做一次“干跑测试”。给 AI 出一个最简单的任务观察审批弹窗频率和沙箱拦截次数。如果每一步都弹说明审批太紧如果弹都弹不出来说明太松。调整到“关键决策才打断你”的状态就是最佳档位。这套流程跑下来大概 20 分钟就能确定组合比对着表格一个个看快得多关键是它能保证你的每个档位都有明确的“为什么”。我的亲身体会是组合本身没有标准答案真正重要的是你清楚每个档位在保护什么、在牺牲什么。审批牺牲的是你的注意力沙箱牺牲的是 AI 的操作半径AGENTS.md 牺牲的是你写文档的时间。把这三个代价放在项目风险前面一对照答案自己就浮出来了。