第四章：项目指令、配置、权限与沙盒
App 用户先写 AGENTS.md
AGENTS.md 是项目级指令文件。App 打开项目后，会把它作为重要上下文。
▫️
•
项目是什么。
•
技术栈是什么。
•
常用命令是什么。
•
代码风格是什么。
•
修改后如何验证。
•
哪些文件或动作禁止。
代码块
JavaScript
# Project Instructions## Overview
这是一个 Next.js 应用，主代码在 `src/`，测试在 `tests/`。
## Commands- 安装依赖：`npm install`- 开发服务：`npm run dev`- 类型检查：`npm run typecheck`- 单元测试：`npm test`- 格式检查：`npm run lint`## Code Style- 使用 TypeScript strict mode。
- 不新增 `any`。
- 复用现有组件和工具函数。
## Testing- 修改业务逻辑时补充或更新测试。
- 提交前至少运行相关测试。
## Safety- 不读取或修改 `.env*`。
- 不提交真实密钥。
- 不直接改数据库迁移，除非任务明确要求。
多层 AGENTS.md
Monorepo 可以在根目录和子目录放不同的 AGENTS.md：
代码块
Plain Text
repo/
AGENTS.md
apps/web/AGENTS.md
packages/api/AGENTS.md
apps/web/AGENTS.md
packages/api/AGENTS.md
理解方式：
•
根目录写全局规则。
•
子目录写局部规则。
•
越靠近当前文件的指令越能补充具体上下文。
•
不要依赖“同名标题自动覆盖”这种想象，写规则时要尽量避免冲突。
App 中的权限入口
App 用户优先通过这几处理解权限：
•
App Settings。
•
当前线程的审批提示。
•
当前 App 的 / 命令列表中显示的权限入口。
•
Review 面板中的 diff。
常见策略：
#moAbRILcPyaZ text { white-space: pre; }#moAbRILcPyaZ .fb0 { stroke: var(--N900-FG, 0.15); }#moAbRILcPyaZ .fb0 {stroke: rgba(31,35,41, 0.15)}#moAbRILcPyaZ .fx0 { stroke-miterlimit: 10; }#moAbRILcPyaZ .fx0 {stroke-miterlimit: 10}#moAbRILcPyaZ .fa1 { fill: rgb(187, 191, 196); }#moAbRILcPyaZ .fa1 {fill: rgb(187, 191, 196)}#moAbRILcPyaZ .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#moAbRILcPyaZ .fx1 {font-style: normal}#moAbRILcPyaZ .fx2 { text-anchor: middle; }#moAbRILcPyaZ .fx2 {text-anchor: middle}#moAbRILcPyaZ .fx3 { dominant-baseline: central; }#moAbRILcPyaZ .fx3 {dominant-baseline: central}#moAbRILcPyaZ .fx4 { stroke: none; }#moAbRILcPyaZ .fx4 {stroke: none}#moAbRILcPyaZ .fc0 { fill: var(--text-caption); }#moAbRILcPyaZ .fc0 {fill: #646a73}#moAbRILcPyaZ .fa2 { fill: var(--text-link-disabled); }#moAbRILcPyaZ .fa2 {fill: rgb(187, 191, 196)}#moAbRILcPyaZ .fa3 { fill: rgb(222, 224, 227); }#moAbRILcPyaZ .fa3 {fill: rgb(222, 224, 227)}#moAbRILcPyaZ .fx5 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#moAbRILcPyaZ .fx5 {font-style: normal}#moAbRILcPyaZ .fx6 { text-anchor: start; }#moAbRILcPyaZ .fx6 {text-anchor: start}#moAbRILcPyaZ .fx7 { dominant-baseline: alphabetic; }#moAbRILcPyaZ .fx7 {dominant-baseline: alphabetic}#moAbRILcPyaZ .fc1 { fill: rgb(0, 0, 0); }#moAbRILcPyaZ .fc1 {fill: rgb(0, 0, 0)}#moAbRILcPyaZ .fb1 { fill: var(--N900-FG, 0.15); }#moAbRILcPyaZ .fb1 {fill: rgba(31,35,41, 0.15)}#moAbRILcPyaZ .fb2 { fill: rgb(209, 217, 224); }#moAbRILcPyaZ .fb2 {fill: rgb(209, 217, 224)}#moAbRILcPyaZ .fa4 { fill: var(--bg-body); }#moAbRILcPyaZ .fa4 {fill: #fff}AB123456场景陌生项目日常小改大规模重构CI / 自动化涉及密钥 / 生产数据建议保守审批，先只读允许常见读写和安全命令使用 worktree，严格 review外部沙箱 + 最小权限默认拒绝，人工确认
沙盒模式怎么理解
Codex 的沙盒是为了限制命令和文件访问范围。CLI 中常见模式包括：
#VbLUstaevQbz text { white-space: pre; }#VbLUstaevQbz .fb0 { stroke: var(--N900-FG, 0.15); }#VbLUstaevQbz .fb0 {stroke: rgba(31,35,41, 0.15)}#VbLUstaevQbz .fx0 { stroke-miterlimit: 10; }#VbLUstaevQbz .fx0 {stroke-miterlimit: 10}#VbLUstaevQbz .fa1 { fill: rgb(187, 191, 196); }#VbLUstaevQbz .fa1 {fill: rgb(187, 191, 196)}#VbLUstaevQbz .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#VbLUstaevQbz .fx1 {font-style: normal}#VbLUstaevQbz .fx2 { text-anchor: middle; }#VbLUstaevQbz .fx2 {text-anchor: middle}#VbLUstaevQbz .fx3 { dominant-baseline: central; }#VbLUstaevQbz .fx3 {dominant-baseline: central}#VbLUstaevQbz .fx4 { stroke: none; }#VbLUstaevQbz .fx4 {stroke: none}#VbLUstaevQbz .fc0 { fill: var(--text-caption); }#VbLUstaevQbz .fc0 {fill: #646a73}#VbLUstaevQbz .fa2 { fill: var(--text-link-disabled); }#VbLUstaevQbz .fa2 {fill: rgb(187, 191, 196)}#VbLUstaevQbz .fa3 { fill: rgb(222, 224, 227); }#VbLUstaevQbz .fa3 {fill: rgb(222, 224, 227)}#VbLUstaevQbz .fx5 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#VbLUstaevQbz .fx5 {font-style: normal}#VbLUstaevQbz .fx6 { text-anchor: start; }#VbLUstaevQbz .fx6 {text-anchor: start}#VbLUstaevQbz .fx7 { dominant-baseline: alphabetic; }#VbLUstaevQbz .fx7 {dominant-baseline: alphabetic}#VbLUstaevQbz .fc1 { fill: rgb(0, 0, 0); }#VbLUstaevQbz .fc1 {fill: rgb(0, 0, 0)}#VbLUstaevQbz .fx8 { font: 400 13px LarkHackSafariFont, LarkEmojiFont, ui-monospace, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, "Noto Sans", Tahoma, "Nimbus Sans L", Arial, "Liberation Sans", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", "Microsoft YaHei", "Wenquanyi Micro Hei", "WenQuanYi Zen Hei", STHeiti, SimHei, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", system-ui; }#VbLUstaevQbz .fx8 {font-style: normal}#VbLUstaevQbz .fb1 { fill: var(--N900-FG, 0.15); }#VbLUstaevQbz .fb1 {fill: rgba(31,35,41, 0.15)}#VbLUstaevQbz .fb2 { fill: rgb(209, 217, 224); }#VbLUstaevQbz .fb2 {fill: rgb(209, 217, 224)}#VbLUstaevQbz .fa4 { fill: var(--bg-body); }#VbLUstaevQbz .fa4 {fill: #fff}AB1234模式含义只读，适合审计和探索可写工作区，适合日常开发无沙盒限制，只能在外部可信沙箱中使用read-onlyworkspace-writedanger-full-access
App 用户不需要一开始背 CLI 参数，但要理解：权限越大，越需要 Review、Git 和备份。
6. config.toml 是什么
config.toml 是 Codex 的配置文件。它适合团队或高级用户管理：
•
默认 profile。
•
审批和沙盒默认值。
•
MCP server。
•
feature flags。
•
终端和环境策略。
App 主线中，普通读者不需要先手写它。推荐顺序：
先在 App Settings 里完成模型、权限、终端、插件和 MCP 的基础设置。
团队需要统一策略时，再查官方 Config Reference。
只复制官方当前支持的字段。
改完后重启或刷新 App，再用 /status、Settings、MCP 列表等入口验收。
如果教程需要展示配置，优先展示“要查官方 schema”而不是写死字段：
只作为结构提示，实际字段以官方 Config Reference 和当前 App 为准。# 不要把模型名、实验开关或公司密钥硬写进教程示例。
注意：字段会随版本变化，写教程时应链接官方 Config Reference，不要复制过时字段，也不要发明 features.goals 这类未核实字段。
Rules：比 prompt 更硬的命令边界
Rules 用来限制或允许命令执行。适合团队把危险命令拦住：
[[rules]]
match = "rm -rf *"action = "deny"message = "禁止危险递归删除；需要清理时先列出目标路径并人工确认。"
Rules 适合：
•
禁止危险命令。
•
要求高风险命令人工审批。
•
给团队设置统一安全边界。
Rules 不适合：
•
写代码风格。
•
写长工作流。
•
替代测试。
Hooks：事件脚本
Hooks 是事件触发脚本，适合做：
•
命令执行前检查。
•
工具执行后记录日志。
•
自动格式化。
•
外部审计。
App 用户应先理解它的风险：
•
Hook 会运行真实脚本。
•
Hook 可能读取敏感上下文。
•
Hook 写错会阻塞工作流。
学习阶段不要急着写 Hook。先用 AGENTS.md、Settings、Rules。
改完配置后怎么验收
每次改 AGENTS.md、Settings、Rules、Hooks 或 config.toml 后，都按这张表验收：
配置没验收就等于没配置。
App 项目基线
个人项目的最小基线：
代码块
Plain Text
AGENTS.md
写清项目命令、测试、禁止事项
App Settings
使用默认或保守审批
Review
每次改动都看 diff
Git
小步提交，不混 unrelated changes
团队项目再增加：
代码块
Plain Text
常见问题
Q1：可以在 AGENTS.md 里指定模型吗？
不建议。模型选择属于运行配置，不是项目事实。
Q2：Rules 和 Hooks 有什么区别？
Rules 更像命令策略；Hooks 是事件脚本。能用 Rules 解决的，不要先写 Hook。
Q3：App 用户必须学 config.toml 吗？
不必须。单人使用先掌握 App Settings 和 AGENTS.md。