Codex Rules 让你用 prefix_rule() 声明哪些命令可以自动运行、哪些需要审批、哪些直接禁止。规则文件存放在 .codex/rules/ 目录下，使用 Starlark 语法。本文说明如何创建规则文件、理解规则字段、处理 Shell 复合命令，以及用命令行工具测试规则是否按预期工作。

Codex Rules

Rules 目前是实验性功能，接口可能变动。

创建规则文件

1. 在 ~/.codex/rules/ 下创建 .rules 文件，例如 ~/.codex/rules/default.rules
2. 写入规则：

# 在沙箱外运行 `gh pr view` 命令前提示审批
prefix_rule(
    # 要匹配的命令前缀
    pattern = ["gh", "pr", "view"],

    # 匹配时的处理动作
    decision = "prompt",

    # 可选：规则存在的原因（会显示在审批提示或拒绝消息里）
    justification = "查看 PR 需要人工确认",

    # 可选：内联单元测试，验证匹配预期
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
        "gh pr view 7888 --json title,body,comments",
    ],
    not_match = [
        # 不匹配：pattern 必须是精确前缀
        "gh pr --repo openai/codex view 7888",
    ],
)

3. 重启 Codex，规则生效

Codex 启动时会扫描所有 Team Config 路径下的 rules/ 目录。在 TUI 里将命令加入允许列表时，Codex 会把规则写入用户层的 ~/.codex/rules/default.rules，下次运行时不再提示。

启用 Smart Approvals 时，Codex 可能在审批请求里自动提议一个 prefix_rule。接受前请仔细检查建议的前缀是否符合预期。

管理员也可以在 requirements.toml 里强制执行 prefix_rule 限制规则。

---

规则字段说明

prefix_rule() 支持以下字段：

pattern（必填）

定义命令前缀的非空列表。每个元素是：

• 字面量字符串："pr"
• 字面量联合（该位置接受多个值之一）：["view", "list"]

decision（默认 "allow"）

匹配时的处理动作：

值	说明
allow	在沙箱外自动运行，不提示
prompt	每次匹配都弹出审批提示
forbidden	直接拒绝，不提示

多条规则同时匹配时，Codex 应用最严格的决策：forbidden > prompt > allow。

justification（可选）

规则存在的原因说明，Codex 可能在审批提示或拒绝消息里展示。使用 forbidden 时，建议在 justification 里写明推荐的替代命令（例如："请使用 rg 代替 grep"）。

match / not_match（默认 []）

Codex 加载规则时验证的示例，用于及早发现规则写错。

---

Shell 复合命令处理

有些工具把多个 shell 命令合并成一次调用，例如：

["bash", "-lc", "git add . && rm -rf /"]

这类命令可能把危险操作隐藏在安全命令旁边，Codex 对 bash -lc、bash -c、zsh -c、sh -c 等有特殊处理。

可以安全拆分的情况

如果 shell 脚本是简单的线性命令链，只含：

• 纯字面量（无变量展开、无 $FOO、无通配符）
• 用 &&、||、;、| 连接

Codex 用 tree-sitter 解析并拆分成独立命令，对每条命令分别应用规则，取最严格结果。

上面的例子拆分后：

• ["git", "add", "."] — 单独评估
• ["rm", "-rf", "/"] — 单独评估

即使 git add 被 allow，因为 rm -rf / 单独评估结果是 prompt 或 forbidden，整个调用也不会自动通过。

不拆分的情况

如果脚本包含以下特性，Codex 不尝试解析：

• 重定向（>、>>、<）
• 变量替换（$(...) 、反引号）
• 环境变量赋值（FOO=bar）
• 通配符（*、?）
• 控制流（if、for 等）

此时整个调用作为单个 ["bash", "-lc", "<完整脚本>"] 参数来匹配规则。

---

测试规则

用 codex execpolicy check 验证规则是否按预期工作：

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

输出 JSON 包含最严格的决策和所有匹配到的规则（包含 justification）。用多个 --rules 合并多个文件，--pretty 格式化输出。

---

规则语言

.rules 文件使用 Starlark 语法——类 Python，但设计上不能产生副作用（不能操作文件系统），规则引擎可以安全执行。

---

常见问题

Q: 我想禁止某个危险命令但允许类似命令，怎么写规则？

A: 用两条规则，决策优先级 forbidden > allow：

# 禁止强制推送到 main
prefix_rule(
    pattern = ["git", "push", "--force"],
    decision = "forbidden",
    justification = "不允许强制推送，请使用 --force-with-lease",
)

# 允许普通 git push
prefix_rule(
    pattern = ["git", "push"],
    decision = "allow",
)

Q: 规则文件修改后需要做什么才能生效？

A: 重启 Codex 即可。规则文件在启动时扫描加载，运行中的 session 不会动态更新。

Q: 团队里所有人都用同一套规则，怎么统一配置？

A: 把 .rules 文件放在仓库的 .codex/rules/ 目录下提交到 Git，Codex 启动时会自动读取项目级规则。团队成员 clone 仓库后无需额外配置，规则自动生效（前提是项目被标记为受信任）。