Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

规则（Rules）

用 prefix_rule 控制哪些命令可以在沙箱外运行：创建规则文件、字段、shell 包装与复合命令的处理、用 codex execpolicy 测试（实验性）。

用规则控制 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".
    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，以后的运行就能跳过提示。启用了 Smart approvals（默认）时，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 比较；内部它把命令当作参数列表（类似 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", "/"]），每条分别对规则评估，最严格的结果胜出。所以即使你允许 pattern=["git", "add"]，Codex 也不会自动允许 git add . && rm -rf /，因为它把 rm -rf / 单独评估。

Codex 不拆分脚本时：脚本用了更高级的 shell 特性（重定向 >、>>、<；替换 $(...)；环境变量 FOO=bar；通配符 *、?；控制流 if、for 等）时，Codex 不尝试解释或拆分，整个调用被当作 ["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，但被设计为可以安全运行：规则引擎运行它不会有副作用，如触碰文件系统）。