企业官网建设流程全解析

围绕 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.md：AI 脑子里预设的“该做什么、别做什么”

AGENTS.md 是给 AI 读的项目说明文件，相当于给新入职的工程师发一份“团队手册”。它解决的不是权限问题，而是“方向问题”。

一个好的 AGENTS.md 至少包含四层信息：

1. 项目身份：这是什么项目、用了什么技术栈、目录结构大概什么样。
2. 常用命令：构建命令、测试命令、Lint 命令、单测跑法，写得越具体，AI 越不会瞎猜。
3. 代码风格与禁区：比如“不可修改公共 API 签名”“新增依赖必须经过确认”“错误处理统一用某个模式”。
4. 工作流约定：比如“改完代码必须跑特定测试”“提交前必须执行 lint”。

AGENTS.md 可以由多层级构成：全局级（放在用户配置目录）、项目级（放在仓库根目录）、目录级（放在某个子模块下）。Codex 读取时遵循就近合并原则，子目录的规则会叠加在项目级之上。

2. 十二种组合全览：先看代价，再谈适配

按审批 2 档（自动 / 需确认）、沙箱 2 档（受限写 / 严格只读）、AGENTS.md 2 档（无手册 / 有完整手册）来算，正好是 8 种基础组合。再加上按类别审批、混合审批这种细分档位，实际会凑出 12 种左右。我按风险从低到高排了一张表，后面逐个说明。

2.1 组合速查表与风险定价

表格只是骨架，关键在下面两点判断逻辑。

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 改成 auto，sandbox profile 改成 open。如果做 C12，就把 category 换 all，profile 改成 read_only，allowed_commands 里只保留 git 相关命令。

4.2 AGENTS.md 推荐结构：别写成论文，写成速查卡

我在多个项目里反复打磨出来的结构，核心原则就一句话：AI 读的时候 10 秒内能找到关键信息。太长的 AGENTS.md 反而会让 AI 抓不住重点。

# 项目：Harness 工作流引擎 ## 项目结构速览 - `src/` 主业务代码，按模块划分 - `tests/` 单测目录，测试文件名与模块一一对应 - `scripts/` 自动化脚本，仅 CI 调用 ## 常用命令 - 构建：`npm run build` - 单测：`npm run test -- --runInBand` - Lint：`npm 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 种组合怎么选”彻底变成流程题。

1. 先回答一个问题：项目黄了代价多大？如果是学习项目，直接走 C2；如果是商业项目，至少 C10 起步。这一步就淘汰掉一半组合。
2. 再回答：AI 会被要求做什么类型的工作？纯读为主选只读沙箱；要改代码选受限写；要跑构建、装依赖，就要留临时写权限。这一步基本把沙箱档位定死。
3. 然后回答：你在场吗？全程人工盯，就上混合审批，把安全操作列白名单；跑批处理，直接自动模式加沙箱兜底；需要审计记录的，所有写操作强制确认。
4. 接着花 15 分钟写 AGENTS.md。不要多写，就写四件事：项目简介、常用命令、三条硬性约束、一条工作流约定。这是全流程里性价比最高的一步。
5. 最后做一次“干跑测试”。给 AI 出一个最简单的任务，观察审批弹窗频率和沙箱拦截次数。如果每一步都弹，说明审批太紧；如果弹都弹不出来，说明太松。调整到“关键决策才打断你”的状态就是最佳档位。

这套流程跑下来，大概 20 分钟就能确定组合，比对着表格一个个看快得多，关键是它能保证你的每个档位都有明确的“为什么”。

我的亲身体会是：组合本身没有标准答案，真正重要的是你清楚每个档位在保护什么、在牺牲什么。审批牺牲的是你的注意力，沙箱牺牲的是 AI 的操作半径，AGENTS.md 牺牲的是你写文档的时间。把这三个代价放在项目风险前面一对照，答案自己就浮出来了。