规则

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

创建规则文件

对于 Work Cloud 的本地计算机访问功能，请使用 Agent Security 中的 rules TOML 字段配置受支持的托管命令规则。这些规则适用于本地执行器；Work 云容器使用现有的 Work Cloud 策略。

这些本地 .rules 指令适用于 Codex；不要假定 Work Cloud 的本地计算机访问功能会读取本地规则文件。有关 Work 的托管要求，请参阅托管配置和配置参考。

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/ 目录，包括 Team Config 位置和用户层 ~/.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（默认都是 []）：在加载 rules 时由 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 解析它，并在应用 rules 前把它拆成多条独立命令。

上面的脚本会被视为两条命令：

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

Codex 会分别用你的 rules 评估每条命令，并以最严格的结果为准。

即使你允许 pattern=["git", "add"]，Codex 也不会自动允许 git add . && rm -rf /，因为它会单独评估 rm -rf /。

这可以防止危险命令混在安全命令后面一起“偷渡”执行。

Codex 何时不会拆分脚本

如果脚本使用了更复杂的 shell 特性，例如：

• 重定向，例如 >、>>、<
• 替换表达式，例如 $(...) 或 ...
• 环境变量赋值，例如 FOO=bar
• 通配符模式，例如 *、?
• 控制流，例如 if、for，或带赋值的 &&

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

在这种情况下，整次调用会被当作：

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

并按一次单独调用 整体应用你的 rules。

这种处理方式意味着：在可以安全拆分时，Codex 会按单条命令逐项评估；在不能安全拆分时，则采用更保守的整体判断。

测试规则文件

使用 codex execpolicy check 可以测试 rules 对某条命令会产生什么效果：

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

这个命令会输出 JSON，展示最严格的决策结果以及命中的规则，其中也包括命中规则里的 justification。你可以传多个 --rules 来组合多份规则文件；加上 --pretty 则会得到格式化输出。

理解规则语言

.rules 文件格式使用 Starlark（参阅语言规范）。它的语法类似于 Python，但其设计确保了运行安全：规则引擎可以在不产生副作用（例如访问文件系统）的情况下运行它。