规则

使用规则来控制 Codex 在沙盒之外可以运行哪些命令。

创建规则文件

1. 在活动配置层旁边的 rules/ 文件夹中创建一个 .rules 文件（例如 ~/.codex/rules/default.rules）。

2. 添加规则。以下示例在允许 gh pr view 在沙盒外运行前进行提示。

   # Prompt before running commands with the prefix `gh pr view` outside the sandbox.
   prefix_rule(
       # The prefix to match.
       pattern = ["gh", "pr", "view"],
   
       # The action to take when Codex requests to run a matching command.
       decision = "prompt",
   
       # Optional rationale for why this rule exists.
       justification = "Viewing PRs is allowed with approval",
   
       # `match` and `not_match` are optional "inline unit tests" where you can
       # provide examples of commands that should (or should not) match this rule.
       match = [
           "gh pr view 7888",
           "gh pr view --repo openai/codex",
           "gh pr view 7888 --json title,body,comments",
       ],
       not_match = [
           # Does not match because the `pattern` must be an exact prefix.
           "gh pr --repo openai/codex view 7888",
       ],
   )

3. 重启 Codex。

Codex 会在启动时扫描每个活动配置层下的 rules/，包括团队配置位置和位于 ~/.codex/rules/ 的用户层。位于 <repo>/.codex/rules/ 的项目本地规则仅在项目 .codex/ 层被信任时才会加载。

当您在 TUI 中将命令添加到允许列表时，Codex 会写入用户层的 ~/.codex/rules/default.rules，以便将来运行该命令时可以跳过提示。

启用“智能批准”（默认开启）时，Codex 可能会在提升请求期间为您建议 prefix_rule。在接受建议之前，请仔细查看该前缀。

管理员也可以通过 requirements.toml 强制执行限制性的 prefix_rule 条目。

了解规则字段

prefix_rule() 支持以下字段：

• pattern （必填）：一个非空列表，用于定义要匹配的命令前缀。每个元素可以是：
  • 一个字面量字符串（例如 "pr"）。
  • 一个字面量联合（例如 ["view", "list"]），用于在对应参数位置匹配多种可能。
• decision （默认为 "allow"）：规则匹配时采取的行动。当多个规则匹配时，Codex 会应用最严格的决定（forbidden > prompt > allow）。
  • allow：在沙盒外运行命令而不进行提示。
  • prompt：在每次执行匹配命令前进行提示。
  • forbidden：拦截请求而不进行提示。
• justification （可选）：规则的非空、人类可读的理由。Codex 可能会在批准提示或拒绝消息中显示它。使用 forbidden 时，建议在理由中包含推荐的替代方案（例如 "Use `rg` instead of `grep`."）。
• match 和 not_match （默认为 []）：Codex 在加载规则时会验证的示例。使用这些示例可以在规则生效前发现错误。

当 Codex 考虑运行命令时，它会将命令的参数列表与 pattern 进行比较。在内部，Codex 将命令视为参数列表（类似于 execvp(3) 接收到的内容）。

Shell 包装器和复合命令

某些工具将多个 shell 命令包装在一次调用中，例如：

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

由于这种命令可以将多个操作隐藏在一个字符串中，Codex 会对 bash -lc、bash -c 及其 zsh / sh 等价形式进行特殊处理。

当 Codex 可以安全地拆分脚本时

如果 shell 脚本是由以下内容组成的线性命令链：

• 普通词（无变量展开，无 VAR=...，无 $FOO，无 * 等）
• 由安全运算符连接（&&、||、; 或 |）

那么 Codex 会对其进行解析（使用 tree-sitter）并在应用您的规则之前将其拆分为单独的命令。

上述脚本将被视为两个独立的命令：

• ["git", "add", "."]
• ["rm", "-rf", "/"]

随后，Codex 会根据您的规则评估每个命令，结果以最严格的为准。

即使您允许了 pattern=["git", "add"]，Codex 也不会自动允许 git add . && rm -rf /，因为 rm -rf / 部分会被单独评估，从而阻止整个调用被自动允许。

这可以防止危险命令与安全命令一起被“夹带”执行。

当 Codex 不拆分脚本时

如果脚本使用了更高级的 shell 特性，例如：

• 重定向（>, >>, <）
• 替换（$(...), `...`）
• 环境变量（FOO=bar）
• 通配符模式（*, ?）
• 控制流（if, for, 带赋值的 && 等）

那么 Codex 不会尝试解析或拆分它。

在这种情况下，整个调用将被视为：

["bash", "-lc", "<full script>"]

并且您的规则将应用于该单个调用。

通过这种处理方式，您既能在安全的情况下获得按命令评估的安全性，又能在无法拆分的情况下保持保守的行为。

测试规则文件

使用 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，但被设计为安全运行：规则引擎可以在没有副作用的情况下运行它（例如，不会触碰文件系统）。