什么是 Codex 规则
Codex 在沙箱中运行命令。规则决定了当命令需要在沙箱外运行时会发生什么:运行它、先询问你,或者拒绝。
OpenAI 的文档在顶部增加了一个警告:“规则处于实验阶段,可能会发生变化。”
规则编写在 .rules 文件中。文档指出该格式使用 Starlark,其语法类似于 Python,但“旨在安全运行:规则引擎可以在没有副作用(例如触碰文件系统)的情况下运行它”。
因此,规则文件是一个关于命令策略的小程序。写在里面的散文不是规则,它不会改变 Codex 编写代码的方式。
你的规范应该放在哪里
代码规范、项目结构和团队指导应放在 AGENTS.md 中。OpenAI 关于记忆(memories)的文档对此非常直接:“将所需的团队指导保留在 AGENTS.md 或签入的文档中。”
同一页面还警告不要依赖记忆来处理必须始终应用的规则:“将记忆视为一个有用的召回层,而不是必须始终应用的规则的唯一来源。”
这为你提供了三个具有不同职责的不同位置:
AGENTS.md:Codex 在你的项目中应该了解什么以及应该如何工作。- 记忆 (Memories):Codex 从之前的对话中继承的有用的上下文。
- 规则 (Rules):哪些命令可以在沙箱外运行,以及如何运行。
如果 Codex 没有遵循你在 AGENTS.md 中编写的指令,规则文件并不是该检查的地方。请检查加载了哪些指令文件。我们在停止 Codex 跳过 AGENTS.md 规则的指南中介绍了如何检查这一点。
规则文件存放在哪里以及何时加载
你在活动配置层旁边的 rules/ 文件夹下创建一个 .rules 文件。文档中的示例是 ~/.codex/rules/default.rules。
然后:“Codex 在启动时会扫描每个活动配置层下的 rules/”。这包括团队配置(Team Config)位置和位于 ~/.codex/rules/ 的用户层。
两个细节决定了规则是否生效:
- 编辑后重启。 文档的步骤以重启 Codex 结束,因为规则是在启动时扫描的。
- 项目规则需要信任。 “只有当项目
.codex/层被信任时,<repo>/.codex/rules/下的项目本地规则才会加载。”
因此,提交到仓库的规则在队友信任该项目之前,不会在他们的机器上生效。
始终允许审批保存在哪里
这部分很容易被忽略,它也是一种记忆。
文档指出:“当你在 TUI 中将命令添加到允许列表时,Codex 会写入用户层的 ~/.codex/rules/default.rules,以便将来的运行可以跳过提示。”
从这句话可以得出三个结论:
- 你的审批是被记录下来的。 它们是文件中的规则,而不是隐藏在会话中的设置。
- 它们位于用户层。 它们保存在你的主目录中,而不是你批准时正在处理的项目中。
- 你可以读取并编辑它们。 打开
~/.codex/rules/default.rules即可查看你以此方式允许的每个命令。
规则还有第二种添加方式。“当启用智能审批(默认开启)时,Codex 可能会在提权请求期间为你建议一个 prefix_rule。”文档增加了一个提醒:“在接受建议的前缀之前,请仔细检查它。”
原因在于前缀。建议的规则会匹配所有以该前缀开头的命令,因此一个简短的前缀可能会允许比你原本打算批准的那个命令多得多的操作。
规则是如何编写的
每条规则都是一个带有几个字段的 prefix_rule()。文档对它们进行了描述:
pattern是必填项。它是一个列表,定义了要匹配的命令前缀,例如gh、pr和view这三个单词。每个元素可以是一个字面量,或者是该位置的一组备选项。decision默认为 allow(允许)。选项包括 allow、prompt(提示)和 forbidden(禁止)。justification是可选的:“规则的一个非空的、人类可读的原因。”文档称 Codex 可能会在审批提示或拒绝消息中显示它。match和not_match是可选的示例,“Codex 在加载规则时会验证这些示例”。文档称它们为内联单元测试。
文档关于 forbidden 规则的指导值得遵循:“当你使用 forbidden 时,请在理由中酌情包含推荐的替代方案”。这样,当 Codex 触发该规则时,它就会知道该改做什么。
理由(justification)字段也是规则最接近“原因”的东西。一年后,正是它告诉你为什么某个命令被阻止了。
文档中的示例规则起什么作用
OpenAI 的示例是一个非常有用的模板。它是使用 GitHub CLI 查看拉取请求(pull request)的单条规则。
- 模式 (pattern) 是由
gh、pr和view组成的前缀。 - 决策 (decision) 是 prompt,因此 Codex 在每个匹配的命令在沙箱外运行之前都会询问。
- 理由 (justification) 写着 “Viewing PRs is allowed with approval”(查看 PR 需经批准后允许),这就是你在提示中会看到的内容。
- 匹配示例 (match examples) 包括通过编号和带有额外标志查看 PR,因此 Codex 会检查规则是否覆盖了这些情况。
- 不匹配示例 (not_match example) 将仓库标志放在单词 view 之前,注释解释了为什么它不应该匹配:“不匹配是因为
pattern必须是精确的前缀。”
最后一个例子展示了字面匹配是多么严格。顺序不同的相同单词组成的命令是不同的前缀,因此它需要自己的规则。
规则重叠时哪项决策胜出
来自多个层的规则可能会匹配同一个命令。文档对结果有明确说明:“当有多个规则匹配时,Codex 应用最严格的决策(forbidden > prompt > allow)。”
因此,你用户层中的 allow 无法放宽来自另一层的 forbidden 规则。应用最严格的匹配决策。
管理员可以刻意利用这一点。文档提到管理员“也可以从托管的 requirements.toml 文件中强制执行限制性的 prefix_rule 条目”。
如何检查 Shell 脚本
某些工具会将多个命令包装在一次调用中,例如运行短脚本的 bash -lc 调用。文档解释了为什么这很重要:此类命令“可以在一个字符串中隐藏多个操作”。
Codex 以两种方式处理此问题。
当它可以安全地拆分脚本时。 如果脚本是由 &&、||、; 或 | 等运算符连接的简单普通命令链,Codex 会对其进行解析并拆分为独立的命令。“然后 Codex 会根据你的规则评估每个命令,并以最严格的结果为准。”文档中的示例:允许 git add 并不代表允许隐藏在后面的链式 rm -rf,因为那部分会被单独评估。
当它不能拆分时。 如果脚本使用了重定向、替换、环境变量、通配符或控制流,Codex 不会尝试解释它。整个调用被视为单个命令,你的规则将应用于该命令。
文档总结了这一设计:“在安全的情况下,你可以获得按命令评估的安全性;在不安全的情况下,则采取保守行为。”
如何测试规则
在依赖某条规则之前,请先检查它。文档建议使用 codex execpolicy check,将其指向规则文件并提供一个命令。“该命令会输出 JSON,显示最严格的决策和任何匹配的规则,包括来自匹配规则的任何 justification 值。”你可以传递多个规则文件来查看它们如何组合。
规则内部的 match 和 not_match 示例会自动执行类似的工作,因为 Codex 在加载规则时会验证它们。
规则与已退役的 untrusted 策略
如果你曾使用过旧的 untrusted 审批策略,那么现在规则变得更加重要。OpenAI 的审批文档指出 Codex 不再支持该设置,并解释了如何保持严格的项目。你在用户级配置中添加一个信任级别为 untrusted 的项目条目,然后:“除非执行策略规则允许,否则命令需要审批。”
在这种设置下,你的 allow 规则是命令在不询问的情况下运行的唯一途径。这是保持 default.rules 整洁的另一个原因。
Codex 对钩子(hooks)也有类似的信任步骤,钩子在运行前需要审核。我们在为什么 Codex 钩子需要审核的指南中介绍了这一点。
人们首先会尝试的操作
将规范写入规则文件。 规则控制命令。规范应放在 AGENTS.md 中。
编辑规则并期望它立即生效。 规则是在启动时扫描的。
提交项目规则并期望它们随处生效。 项目规则仅在项目层被信任时才会加载。
不经阅读就接受建议的前缀。 简短的前缀可能会允许超出你预期的操作。
允许一个命令来覆盖阻止。 最严格的决策胜出。
解决方法:将每种指令放在其所属的位置
第 1 步:将规范移至 AGENTS.md
将任何描述如何编写代码的内容从规则文件中移出,放入 AGENTS.md。
第 2 步:检查你保存的审批
打开 ~/.codex/rules/default.rules 并删除你不再需要的 allow 规则。
第 3 步:添加理由和示例
为每条规则提供一个理由,并添加 match 和 not_match 示例,以便在 Codex 加载规则时发现错误。
第 4 步:记录每项命令策略存在的原因
写下规则背后的决策,例如为什么要阻止某个命令,或者应该使用哪个替代方案。
在 MemoryLake 中设置
规则文件记录了 Codex 可以运行什么。其背后的决策(例如为什么在本地阻止部署命令,或者哪个测试命令取代了旧命令)是项目知识,项目上的每个助手都应该掌握。
MemoryLake 是此类项目上下文的记忆层,例如决策、规范以及防护措施背后的原因,这些内容保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。
你用自己的语言亲自编写条目。不会从你的 .rules 文件、AGENTS.md 文件、Codex 配置或记忆、会话或任何供应商的存储中读取、写入或删除任何内容。Codex 规则和审批按照 OpenAI 描述的方式工作。
第 1 步:创建 API 密钥
登录并在仪表板中生成密钥。像对待任何其他凭据一样,将其存储在仓库之外。

第 2 步:上传你的第一批记忆
从你在解决方法的第 4 步中编写的内容开始:命令策略背后的原因以及被阻止命令的替代方案。每个条目一个决策。

第 3 步:连接你的 AI 和 Agent
连接 Codex、Claude Code 以及你使用的其他助手。无论其自身的权限系统如何,每个助手都可以利用相同的决策。

这在实践中改变了什么
第一个区别是清晰度。规则保持专注于命令,而原因则存在于人们可以阅读的地方。
第二个是跨工具的一致性。Claude Code 有其自身的权限规则,而两者背后的决策可以共存在一个地方。
第三个是更容易审核。队友在更改规则之前可以看到该规则存在的原因。
Codex 规则的最佳实践
规则仅用于命令。 规范属于 AGENTS.md。
检查你的用户层。 始终允许审批保存在 ~/.codex/rules/default.rules 中。
阅读建议的前缀。 它们可能匹配多个命令。
编写理由。 为 forbidden 规则包含一个替代方案。
添加匹配示例。 Codex 在加载规则时会验证它们。
使用 codex execpolicy check 进行测试。 在依赖它之前查看最严格的决策。
编辑后重启。 规则是在启动时扫描的。
结论
Codex 规则控制哪些命令可以在沙箱外运行:允许、提示或禁止。它们不是指令,规范属于 AGENTS.md。规则文件位于每个配置层旁边的 rules/ 文件夹中,在启动时加载,且项目规则需要受信任的项目。当你在 TUI 中允许一个命令时,Codex 会将其保存到用户层的 ~/.codex/rules/default.rules 中。
当规则重叠时,最严格的决策胜出,简单的 Shell 脚本会被拆分,以便对每个命令进行单独检查。检查你保存的审批,添加理由,并将规则背后的原因保存在你维护的地方。