使用 rules 控制 Codex 可以在 sandbox 外运行哪些 commands。
创建 rules 文件
在 active config layer 旁边的 rules/ 文件夹下创建 .rules 文件（例如 ~/.codex/rules/default.rules）。
添加一条 rule。这个示例会在允许 gh pr view 于 sandbox 外运行前提示确认。
# 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 scans rules/ under every active config layer at startup, including Team Config locations 和 the user layer at ~/.codex/rules/。Project-local rules under <repo>/.codex/rules/ load only 当 the project .codex/ layer is trusted.
当 you 添加 a command 到 the allow 列出 in the TUI, Codex writes 到 the user layer at ~/.codex/rules/默认.rules so future runs can skip prompt.
当 Smart approvals are enabled (the 默认), Codex may propose a prefix_rule for you during escalation requests。检查 the suggested prefix carefully 之前 accepting it.
Admins can also enforce restrictive prefix_rule entries 从 requirements.toml .
理解 rule 字段
prefix_rule() supports these fields:
A literal string (例如, "pr").
A union of literals (例如, ["view", "列出"]) 到 match alternatives at that argument position.
allow：运行 command outside the sandbox 不使用 prompting.
prompt：Prompt 之前 each matching invocation.
forbidden：Block the request 不使用 prompting.
justification (可选)：A non-empty, human-readable reason for the rule。Codex may surface it in approval prompts 或 rejection messages。当 you 使用 forbidden, include a recommended alternative in the justification 当 appropriate (例如, "使用 \rg` 而不是 `grep`.”`).
match 和 not_match (默认s 到 [])：Examples that Codex validates 当 it loads your rules。使用 these 到 catch mistakes 之前 a rule takes effect.
当 Codex considers a command 到 运行, it compares command’s argument 列出 到 pattern。Internally, Codex treats command as a 列出 of arguments (like what execvp(3) receives).
Shell wrappers 和 compound commands
Some tools wrap several shell commands into a single invocation, 例如:
["bash", "-lc", "git add . && rm -rf /"]Because this kind of command can hide multiple actions inside one string, Codex treats bash -lc, bash -c, 和 their zsh / sh equivalents specially.
Codex 什么时候可以安全拆分 script
如果 the shell script is a linear chain of commands made only of:
plain words (no variable expansion, no VAR=..., $FOO, *, etc.)
joined by safe operators (&&, ||, ;, 或 |)
then Codex parses it (using tree-sitter) 和 splits it into individual commands 之前 applying your rules.
The script above is treated as two separate commands:
["git", "添加", "."]
["rm", "-rf", "/"]
Codex then evaluates each command against your rules, 和 the most restrictive result wins.
Even 如果 you allow pattern=["git", "添加"], Codex won’t auto allow git add . && rm -rf /, because the rm -rf / portion is evaluated separately 和 prevents the whole invocation 从 being auto allowed.
This prevents dangerous commands 从 being smuggled in alongside safe ones.
Codex 什么时候不会拆分 script
如果 the script uses more advanced shell features, such as:
redirection (>, >>, <)
substitutions ($(...), ...)
environment variables (FOO=bar)
wildcard patterns (*, ?)
control flow (如果, for, && 使用 assignments, etc.)
then Codex doesn’t try 到 interpret 或 split it.
In those cases, the entire invocation is treated as:
["bash", "-lc", "<full script>"]和 your rules are applied 到 that single invocation.
With this handling, you get the security of per-command evaluation 当 it’s safe 到 do so, 和 conservative behavior 当 it isn’t.
测试 rule file
使用 codex execpolicy check to test how your rules apply to a command:
codex execpolicy check --pretty \
--rules ~/.codex/rules/default.rules \
-- gh pr view 7888 --json title,body,commentsThe command emits JSON showing the strictest decision 和 any matching rules, including any justification values 从 matched rules。使用 多个 --rules flag 到 combine files, 和 添加 --pretty 到 format the output.
理解 rules language
The .rules file format uses Starlark (see the language spec )。Its syntax is like Python, but it’s designed 到 be safe 到 运行：the rules engine can 运行 it 不使用 side effects (例如, touching the filesystem).