English
主导航

推荐
API 仪表板

规则

控制 Codex 可以在沙箱外运行哪些命令

使用规则来控制 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 管理员也可以通过

强制实施限制性的 prefix_rule 条目。 requirements.toml.

了解规则字段

prefix_rule() 支持以下字段：

  • pattern （必填）：一个定义了要匹配的命令前缀的非空列表。每个元素可以是：
    • 字面量字符串（例如， "pr").
    • 字面量联合类型（例如， ["view", "list"]），用于匹配该参数位置的备选项。
  • decision (默认为 "allow")：当规则匹配时要执行的操作。当有多条规则匹配时，Codex 会应用最严格的决策 (forbidden > prompt > allow).
    • allow: 在沙箱外运行命令，无需提示。
    • prompt: 在每次匹配的调用前进行提示。
    • forbidden: 阻止请求且不提示。
  • justification （可选）: 规则的一条非空、人类可读的原因。Codex 可能会将其显示在批准提示或拒绝消息中。当你使用 forbidden,在适当时于理由中包含推荐的替代方案(例如, "Use \rg` 而不是 `grep`。”`).
  • match and 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, *等)
  • ），并由安全的操作符（&&, ||, ;, or |)

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

上面的脚本会被视为两个独立的命令：

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

随后，Codex 会根据你的规则对每条命令进行评估，并采用最严格的结果。

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

这可以防止危险命令与安全命令混在一起执行。

当 Codex 不拆分脚本时

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

  • 重定向（>, >>, <)
  • 替换（$(...), ...)
  • 环境变量（FOO=bar)
  • 通配符模式（*, ?)
  • 控制流（if, for, && with assignments, etc.)

那么 Codex 不会尝试对其进行解释或拆分。

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

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

并且你的规则将应用于这一 单一 invocation.

通过这种处理方式，你可以在安全的情况下获得逐命令评估的安全性，并在不安全的情况下采取保守策略。

测试规则文件

使用 codex execpolicy check 要测试你的规则如何应用于某一命令：

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

该命令会输出 JSON，显示最严格的决定以及任何匹配的规则，包括匹配规则中的任何 justification 值。请使用多个 --rules 标志以组合文件，并添加 --pretty to format the output.

理解规则语言

The .rules 文件格式使用 Starlark （参见 语言规范). 其语法类似于 Python，但被设计为可安全运行：规则引擎能够无副作用地运行它（例如，触碰文件系统）。