#Codex 规则与钩子

权限设置 解决「范围」与「要不要问」，而本章的两件工具更细：

• 规则（Rules）：对某一条具体命令决定 allow / prompt / forbidden
• 钩子（Hooks）：在 Agent 生命周期的关键时刻插入你的脚本

这两项属于较新的/实验性的能力，配置格式可能随版本调整，请以官方 Rules 与 Hooks 文档为准。

#一、规则（Rules）

#解决什么问题

沙箱与审批是「粗粒度」的。规则让你对沙箱外要执行的命令做精确判定，例如「gh pr view 允许但需确认，gh pr merge 直接禁止」。

#格式：Starlark prefix_rule()

规则写在 rules/ 目录下的 .rules 文件中（如 ~/.codex/rules/default.rules），用 Python 风格的 Starlark：

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "查看 PR 允许，但需要确认",
    match = ["gh pr view 7888"],
    not_match = ["gh pr --repo openai/codex view 7888"],
)

优先级： forbidden > prompt > allow。

#复合命令的处理

Codex 会智能拆分 &&、||、;、| 连接的「纯词」命令并逐段匹配，对每段套用最严格的规则；若命令包含重定向、变量替换、子命令替换等，则作为单一调用整体判定，避免「夹带」危险操作。

#来源与企业强制

• 用户层：当你在审批时选择「总是允许」，Codex 会在 ~/.codex/rules/default.rules 自动生成对应规则
• 团队/企业：管理员可通过 requirements.toml 下发强制规则
• 校验：codex execpolicy check 测试某命令会命中哪条规则

codex execpolicy check -- gh pr view 7888

#二、钩子（Hooks）

#解决什么问题

钩子让你在 Agent 循环的确定性时刻注入脚本——做安全策略、日志审计、上下文注入、提交前校验等，而不依赖模型「自觉」。

#生命周期事件

#配置格式

钩子写在 hooks.json，或 config.toml 的内联 [hooks] 表：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/policy.py",
            "statusMessage": "正在检查命令",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

#脚本的输入与输出

钩子脚本通过 stdin 收到 JSON（含 session_id、cwd、tool_name、tool_input 等），并通过 stdout 输出 JSON 控制是否继续：

{
  "continue": false,
  "stopReason": "Policy violation",
  "systemMessage": "Action blocked"
}

#典型用途

1. 安全策略：PreToolUse 拦截危险命令、检测泄露的密钥
2. 审计/分析：SessionStart / Stop 把会话数据送到外部系统
3. 持久记忆：UserPromptSubmit 自动总结交互
4. 质量校验：PostToolUse 在继续前强制代码规范
5. 上下文注入：SessionStart 加载团队约定为开发者上下文

#信任模型

• 托管钩子（来自 requirements.toml）无需信任审查即生效
• 用户钩子需通过 /hooks 命令显式信任后才会执行

#规则 vs 钩子 vs AGENTS.md

三者叠加：AGENTS.md 让它想做对，Rules/Hooks 让它不能做错。

#下一步

• 权限设置：规则之上的沙箱与审批
• 安全与企业管理：用 requirements.toml 强制下发
• 自动化与 CI/CD：在无人值守场景里用钩子兜底