用 Rules 控制命令边界

Rules 用来控制 Codex 可以在 sandbox 外运行哪些 commands。

Rules 目前是 experimental，未来可能变化。

Create a rules file

在 active config layer 旁边的 rules/ folder 下创建 .rules file。例如：

~/.codex/rules/default.rules

添加 rule。下面示例会在允许 gh pr view 跑出 sandbox 前先 prompt：

# 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",
    ],
)

重启 Codex。

Codex 会在 startup 时扫描每个 active config layer 下的 rules/，包括 Team Config locations，以及 user layer：

~/.codex/rules/

project-local rules 位于：

<repo>/.codex/rules/

只有当 project .codex/ layer 被 trusted 时，project-local rules 才会加载。

你在 TUI 中把 command 加入 allow list 时，Codex 会写入 user layer：

~/.codex/rules/default.rules

这样未来 runs 可以跳过 prompt。

当 Smart approvals 启用时，这是默认行为，Codex 可能在 escalation requests 中为你建议 prefix_rule。接受前要认真 review suggested prefix。

Admins 也可以从 requirements.toml enforce restrictive prefix_rule entries。

Understand rule fields

prefix_rule() 支持这些字段：

字段	说明
`pattern`	required。非空 list，定义要匹配的 command prefix。每个 element 可以是 literal string，例如 `"pr"`，也可以是 literal union，例如 `["view", "list"]`，用于匹配该 argument position 的多个备选。
`decision`	默认 `"allow"`。rule 匹配时采取的 action。多个 rules 同时匹配时，Codex 采用最严格 decision：`forbidden` > `prompt` > `allow`。
`justification`	optional。非空、人类可读的 reason。Codex 可能在 approval prompts 或 rejection messages 中显示它。使用 `forbidden` 时，适合在 justification 中包含推荐替代方式，例如 `"Use \`rg` instead of `grep`."`。
`match` / `not_match`	默认 `[]`。Codex 加载 rules 时会验证这些 examples，用来在 rule 生效前发现错误。

decision 可选值：

decision	行为
`allow`	在 sandbox 外运行 matching command，不 prompt。
`prompt`	每次 matching invocation 前 prompt。
`forbidden`	不 prompt，直接 block request。

Codex 判断 command 能否运行时，会把 command 的 argument list 和 pattern 比较。内部会把 command 当作 arguments list 处理，类似 execvp(3) 接收的形式。

Shell wrappers and compound commands

有些 tools 会把多个 shell commands 包在一次 invocation 中，例如：

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

这种 command 可以把多个 actions 藏在一个 string 里。因此 Codex 会特殊处理 bash -lc、bash -c，以及对应的 zsh / sh equivalents。

When Codex can safely split the script

如果 shell script 是 linear chain，并且只包含：

plain words，也就是没有 variable expansion、没有 VAR=...、$FOO、* 等
通过 safe operators 连接：&&、||、; 或 |

Codex 会用 tree-sitter parse 它，并在应用 rules 前拆成 individual commands。

上面的 script 会被视为两个独立 commands：

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

然后 Codex 会把每个 command 分别和 rules 比较，并采用最严格结果。

即使你 allow pattern=["git", "add"]，Codex 也不会自动 allow git add . && rm -rf /，因为 rm -rf / 部分会被单独评估，并阻止整个 invocation 自动通过。

这能防止 dangerous commands 被夹带在 safe commands 旁边。

When Codex does not split the script

如果 script 使用更高级 shell features，Codex 不会尝试 interpret 或 split。

例子：

redirection：>、>>、<
substitutions：$(...) 或 backticks
environment variables：FOO=bar
wildcard patterns：*、?
control flow：if、for、带 assignments 的 && 等

这种情况下，整个 invocation 会被视为一个 command：

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

rules 也会应用到这个 single invocation 上。

这种处理方式在可以安全拆分时提供 per-command evaluation；不能安全拆分时，保持 conservative behavior。

Test a rule file

用 codex execpolicy check 测试 rules 如何应用到 command：

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

这个命令会输出 JSON，显示 strictest decision，以及匹配到的 rules，包括 matched rules 中的 justification values。

可以用多个 --rules flags 组合多个 files，并加 --pretty 格式化输出。

Understand the rules language

.rules file format 使用 Starlark。语言规范见：

https://github.com/bazelbuild/starlark/blob/master/spec.md

它的语法类似 Python，但设计目标是 safe to run：rules engine 可以无副作用地运行它，例如不会触碰 filesystem。