MemoryLake
返回全部文章
Tutorial2026 年 11 月 17 日·10 分钟阅读

Codex 规则控制什么?为什么 .rules 文件不是存放指令的地方、始终允许审批保存在哪里,以及规则重叠时哪项决策胜出 (2026)

你希望 Codex 遵循团队的规范,于是你寻找 Codex 规则文件,创建了一个 rules/ 文件夹,并将你的风格指南写了进去。结果什么也没改变。几周前,你告诉 Codex 始终允许运行 npm test,之后它就再没问过,但你却说不出那个选择保存在了哪里。

这两者都有相同的解释。在 Codex 中,规则(rules)不是指令(instructions)。OpenAI 的文档开篇只有一句话:“使用规则来控制 Codex 可以在沙箱之外运行哪些命令。”当你永久批准一个命令时,该审批就会作为一条规则被保存下来。

本指南涵盖了 Codex 规则是什么、规范应该放在哪里、规则文件存放在何处以及何时加载、始终允许审批保存在哪里、规则如何编写、规则重叠时哪项决策胜出、如何检查 Shell 脚本以及如何测试你的规则。

什么是 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 密钥

登录并在仪表板中生成密钥。像对待任何其他凭据一样,将其存储在仓库之外。

MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供在 Agent 中使用
MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供在 Agent 中使用

第 2 步:上传你的第一批记忆

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

MemoryLake 工作区已上传首批文档,列出了每个文件变为可搜索记忆的过程
MemoryLake 工作区已上传首批文档,列出了每个文件变为可搜索记忆的过程

第 3 步:连接你的 AI 和 Agent

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

MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 Agent 框架
MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 Agent 框架

这在实践中改变了什么

第一个区别是清晰度。规则保持专注于命令,而原因则存在于人们可以阅读的地方。

第二个是跨工具的一致性。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 脚本会被拆分,以便对每个命令进行单独检查。检查你保存的审批,添加理由,并将规则背后的原因保存在你维护的地方。

常见问题

什么是 Codex 规则?

控制 Codex 可以在沙箱外运行哪些命令的策略,编写在 .rules 文件中。

我可以将代码指令放在 Codex 规则文件中吗?

不可以。规则控制命令。OpenAI 表示应将团队指导保留在 AGENTS.md 或签入的文档中。

Codex 将始终允许审批保存在哪里?

保存在用户层的 ~/.codex/rules/default.rules 中。

如果两个规则匹配,哪一个胜出?

最严格的:forbidden(禁止),然后是 prompt(提示),最后是 allow(允许)。

为什么我的项目规则不起作用?

项目规则仅在项目 .codex/ 层被信任时才会加载,且规则是在启动时扫描的。

如何测试 Codex 规则?

使用规则文件和命令运行 codex execpolicy check。它会显示最严格的决策和匹配的规则。

Codex 规则稳定吗?

OpenAI 表示规则处于实验阶段,可能会发生变化。