2026 Codex Rules 配置教程：prefix_rule、命令权限与 execpolicy

先看结论：Rules 只处理 Sandbox 外命令，不是万能权限配置

先让常用工作尽可能留在 Sandbox 内；只有确实需要越过边界的稳定命令，才使用精确的 prefix_rule。不要用一条宽泛 allow 代替权限设计。

Rules 不会扩大文件系统可写范围，不会自动打开网络，也不会修复 OS 权限、只读挂载或套餐用量。出现 permission denied 时，应先进入Sandbox 与权限分流。

AGENTS.md、Sandbox、approval_policy、Rules 和 Hooks 分别管什么

如果目标是“所有任务都先跑相关测试”，写入 AGENTS.md；如果目标是“在工具调用前后运行确定性脚本”，进入 Codex Hooks 配置教程；如果目标是“gh pr view 越界时每次询问”，使用 Rules；如果目标是“阻止工作区之外写入”，应配置 Sandbox 和 workspace roots。

.rules 文件放在哪里：只在活动配置层旁边加载

用户层最常见的位置是：

~/.codex/rules/default.rules

Codex 启动时扫描每个活动配置层旁边的 rules/ 目录，包括用户层、Team Config 和受信任的项目层。项目内可使用：

my-project/
└── .codex/
    └── rules/
        └── project.rules

项目被标记为 untrusted 时，项目级 .codex/ 配置、Hooks 和 Rules 都会被跳过。用户和系统层仍是独立的。修改 Rules 后应重启 Codex，因为规则在启动时加载。

在 TUI 中把命令加入允许列表时，Codex 会把对应用户规则写入 ~/.codex/rules/default.rules，让后续运行减少重复询问。自动生成的前缀也必须人工检查，不能看到“允许”按钮就直接接受。

从一条最小 prefix_rule 开始

下面规则只匹配以 gh pr view 开头的参数列表，并要求每次审批：

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "查看 Pull Request 前需要确认",
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
    ],
    not_match = [
        "gh pr --repo openai/codex view 7888",
    ],
)

pattern 匹配的是命令的参数数组，不是整行字符串包含关系。上例不会匹配参数顺序不同的 gh pr --repo ... view，所以必须用 match 和 not_match 把真实调用方式写成内联测试。

prefix_rule 字段与 allow、prompt、forbidden 决策

多条规则同时匹配时采用最严格结果：forbidden > prompt > allow。因此不能依赖一条宽泛 allow 覆盖更具体的禁止规则。

pattern 是参数前缀：尾随参数仍然会被匹配

pattern = ["gh", "pr", "view"] 会匹配 gh pr view 及其后继续追加的参数，但不会匹配 gh pr --repo owner/repo view。命令前插入包装器、环境变量或调整参数顺序，都可能改变实际参数数组。

同一位置需要多个候选时可使用集合：

prefix_rule(
    pattern = ["gh", "pr", ["view", "list"]],
    decision = "allow",
    justification = "只允许读取 Pull Request",
    match = ["gh pr view 123", "gh pr list --state open"],
    not_match = ["gh pr create", "gh pr merge 123"],
)

不要把 ["git"]、["python"]、["curl"] 或 ["bash", "-lc"] 整类设为 allow。它们可以承载写入、网络、凭证或任意脚本，过宽前缀会抹掉本来需要保留的边界。

Shell wrapper 与复合命令如何评估

命令可能以 bash -lc、bash -c、zsh 或 sh 包装多个动作。Codex 对可安全解析的线性脚本做特殊处理：

• 只有普通字词，没有变量展开、通配符或赋值；
• 只用 &&、||、; 或 | 连接；
• 使用 tree-sitter 拆成单条命令后分别匹配；
• 任何一条命中更严格决策，整个调用按更严格结果处理。

因此允许 git add 不会自动放行后面拼接的另一条高风险命令。若脚本包含重定向、命令替换、环境变量、通配符、赋值或控制流，Codex 不尝试深入解释，而把它保守地视为整个 Shell wrapper 调用。不要为了解决一次匹配失败就允许全部 bash -lc。

三类安全示例：只读允许、发布询问、危险操作禁止

允许稳定的远程只读检查

prefix_rule(
    pattern = ["gh", "pr", ["view", "list"]],
    decision = "allow",
    justification = "允许读取 Pull Request，不覆盖创建或合并",
    match = ["gh pr view 123", "gh pr list --state open"],
    not_match = ["gh pr create", "gh pr merge 123"],
)

部署命令保持询问

prefix_rule(
    pattern = ["npx", "wrangler", "deploy"],
    decision = "prompt",
    justification = "部署会改变线上状态，必须确认目标环境",
    match = ["npx wrangler deploy --env staging"],
    not_match = ["npx wrangler dev"],
)

禁止破坏性 Git 动作并提供替代方案

prefix_rule(
    pattern = ["git", "push", "--force"],
    decision = "forbidden",
    justification = "禁止该参数顺序的强制推送；请使用普通 push 和分支保护流程",
    match = ["git push --force origin main"],
    not_match = ["git push origin main"],
)

最后一条只覆盖展示的参数顺序，不能当作“阻止所有强制推送”的完整策略；参数可以换位置，也存在语义相近选项。示例应根据真实仓库、CI、分支保护与恢复策略修改，不要复制一份“万能 Rules”后在所有项目直接启用。

用 codex execpolicy check 验证，而不是靠真实副作用试错

官方当前提供实验性的 execpolicy 检查命令。测试一条规则：

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

输出 JSON 会给出最严格决策、命中的规则和 justification。多个文件可重复添加 --rules。建议至少测试以下矩阵：

match 和 not_match 是规则加载时的验证样例，不会执行命令。它们用于提前发现规则表达式与预期不一致。

Codex Rules 不生效的排查顺序

1. 确认正在解决 Sandbox 外审批

   命令若在 Sandbox 内完成，不需要 Rules；OS permission denied 也不是 Rules 能修复。

2. 确认 host、CODEX_HOME 和文件位置

   本机、WSL、SSH、容器可能读取不同的 ~/.codex/rules/。

3. 重启 Codex

   规则在启动时扫描，编辑后旧运行可能仍使用原链。

4. 检查项目是否 trusted

   untrusted 项目会跳过项目级 .codex/rules/。

5. 查看真实参数数组

   包装器、-C、参数顺序和尾随参数会改变匹配。

6. 检查更严格的匹配规则

   forbidden 或 prompt 会压过 allow，管理员 requirements 也可能限制用户规则。

7. 运行 execpolicy check

   同时传入实际加载的多个规则文件，查看命中来源。

Smart approvals、团队 Rules 与管理员要求

Smart approvals 启用时，Codex 可能在升级请求中建议 prefix_rule。建议只是候选，不是安全证明；接受前应检查前缀是否包含写入、网络、发布、删除、付款或凭证访问。

团队可通过 Team Config 分发配置层，管理员还可在 requirements.toml 强制更严格的 prefix rules。用户规则不能用来绕过管理员限制。企业仓库应对以下变更单独评审：

• 把 decision 从 prompt 改为 allow；
• 缩短 pattern，导致匹配范围扩大；
• 删除 not_match 或危险样例；
• 允许 Shell、脚本解释器、通用网络客户端或发布工具；
• 新增项目级 Rules 但没有说明 trust、负责人和回滚方式。

审批策略也可以配置 granular 分类或 auto-review，但自动审批不是确定性的安全保证。减少审批噪音的优先路线仍是：把安全工作留在 Sandbox、精确 writable roots、精确命令前缀，而不是训练审查器长期放过宽泛请求。

Codex Rules、prefix_rule 与 execpolicy 常见问题

Codex Rules 是什么？

它是实验性的命令执行策略，用来决定匹配的命令请求在 Sandbox 外运行时应 allow、prompt 还是 forbidden。

Codex Rules 文件放在哪里？

用户层通常是 ~/.codex/rules/default.rules；活动 Team Config 和受信任项目的 .codex/rules/ 也会在启动时扫描。

prefix_rule 的 pattern 是正则表达式吗？

不是。它是命令参数数组的精确前缀，每个位置可以是一个字面字符串或若干候选字面值。

allow、prompt 和 forbidden 哪个优先？

多条规则同时匹配时取最严格决策：forbidden 高于 prompt，prompt 高于 allow。

match 和 not_match 会执行命令吗？

不会。它们是加载规则时验证匹配预期的内联测试样例。

为什么修改 default.rules 后没有生效？

先重启 Codex，再检查实际 CODEX_HOME、活动配置层、项目 trust、命令参数顺序和是否存在更严格规则。

项目里的 .codex/rules 为什么不加载？

项目级 Rules 只在项目配置层受信任时加载；untrusted 项目会跳过该层的 config、Hooks 与 Rules。

Rules 可以允许联网或写任意目录吗？

Rules 只分类 Sandbox 外命令请求，不能替代网络、filesystem、workspace roots 和 OS 权限配置。

AGENTS.md 和 Rules 有什么区别？

AGENTS.md 提供项目工作说明；Rules 是可执行的命令前缀策略。前者告诉 Codex应该怎样工作，后者控制特定越界命令如何处理。

如何测试 Codex Rules？

使用 codex execpolicy check --rules ... -- command 查看 JSON 决策与命中规则，不要通过真实部署或删除动作试错。

可以把 python、curl 或 bash 整类 allow 吗？

不建议。它们能承载非常广泛的写入、网络和脚本行为，应匹配更具体的子命令或保留 prompt。

升级 Plus 或 Pro 能减少 Rules 提示吗？

不能直接改变命令安全策略。套餐影响功能与用量，不会自动扩大 Sandbox 或把 prompt 改成 allow。