AI Agent / 系统课时

使用 Hooks 执行规则

使用 Hooks 执行规则

本课用一个可运行的 PreToolUse Hook 把危险 shell 命令挡在执行前,并说明格式化、检查和通知应该挂在哪些事件上。完成后,你会拥有一条可验证、可审查、不会把事后检查误当成事前阻断的规则链。

学习目标

  • 理解 Codex Hooks 的事件点、匹配器与处理器三层结构
  • 能编写并验证一个在工具执行前阻断危险命令的 Hook
  • 能区分事前阻断、事后检查、审批决策与异步通知的适用位置

Hook 插在代理循环的哪里

Codex 可以从用户级或项目级 hooks.json、config.toml 读取 Hooks。一次 Hook 定义由“事件 → matcher → handler”组成;项目本地 Hook 只有在项目配置层受信任时才会运行,而且非托管 Hook 需要在 Codex 中审查并信任其当前定义。:contentReference[oaicite:6]{index=6}

Codex Hooks 在一次工具调用前后的执行位置

PreToolUse 能拦截 Bash、apply_patch、MCP 工具和其他本地函数工具,并在工具真正执行前拒绝或改写输入;PostToolUse 发生在工具已经产生结果之后,即使返回 block,也不能撤销刚才发生的文件修改或外部副作用。:contentReference[oaicite:7]{index=7}

编写危险命令阻断规则

下面示例面向 macOS、Linux 或 WSL。把 Hook 放到项目的 .codex/ 目录,规则只匹配 Bash 工具,再由 Python 脚本检查即将执行的命令。

.codex/hooks.json:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "timeout": 10,
            "statusMessage": "Checking shell policy"
          }
        ]
      }
    ]
  }
}

.codex/hooks/pre_tool_use_policy.py:

python
import json
import sys

payload = json.load(sys.stdin)
command = payload.get("tool_input", {}).get("command", "")

# 只拦截明确的高风险模式;正常命令保持静默并放行。
blocked_patterns = ("rm -rf /", "rm -rf ~", "git reset --hard")

if any(pattern in command for pattern in blocked_patterns):
    result = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Blocked by repository shell policy."
        }
    }
    print(json.dumps(result))

Codex 会把当前 Hook 事件的 JSON 对象写到处理器标准输入。对于 PreToolUse,返回 permissionDecision: "deny" 可以在工具运行前拒绝调用;也可以用退出码 2 并把阻断原因写到标准错误。:contentReference[oaicite:8]{index=8}

先在终端验证脚本

不要直接依赖代理行为来猜规则是否正确。先把一份最小事件输入送给脚本,确认 JSON 输出符合协议。

bash
printf '%s\n' '{"hook_event_name":"PreToolUse","tool_input":{"command":"git reset --hard"}}' \
  | python3 .codex/hooks/pre_tool_use_policy.py

预期输出

json
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Blocked by repository shell policy."}}

然后启动 Codex,在 CLI 中输入 /hooks 检查 Hook 来源、审查新定义并将其标记为可信。Hook 内容发生变化后,Codex 会按新的定义哈希重新要求审查,避免项目悄悄替换已信任脚本。:contentReference[oaicite:9]{index=9}

为不同规则选择正确事件

需求 推荐事件 关键边界
阻止危险命令或改写参数 PreToolUse 工具执行前生效,可 deny 或 rewrite
自动决定一次权限请求 PermissionRequest 只在 Codex 准备请求审批时触发,可 allow 或 deny
格式化、检查工具结果 PostToolUse 工具已执行,不能撤销副作用
发送通知或记录日志 PostToolUse / SessionEnd 不需要阻断时优先异步或短处理
在模型准备结束时追加一轮检查 Stop block 的含义是让 Codex 继续,而不是回滚上一轮

多个匹配到的命令 Hook 可能并发启动,所以不要设计“Hook A 先阻断,Hook B 就一定不会启动”的依赖关系。真正的安全规则应让每个处理器独立判断,并把高风险阻断放在副作用发生前。:contentReference[oaicite:10]{index=10}

Hooks 最适合承载确定性的工程规则:能用脚本明确判断的格式、检查、权限与通知逻辑交给 Hook;需要语义理解和权衡的任务仍交给 Codex 本身,这样规则链既可审计,也不会把代理循环变成难以预测的脚本集合。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Hooks 执行规则

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通