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}

PreToolUse 能拦截 Bash、apply_patch、MCP 工具和其他本地函数工具,并在工具真正执行前拒绝或改写输入;PostToolUse 发生在工具已经产生结果之后,即使返回 block,也不能撤销刚才发生的文件修改或外部副作用。:contentReference[oaicite:7]{index=7}
编写危险命令阻断规则
下面示例面向 macOS、Linux 或 WSL。把 Hook 放到项目的 .codex/ 目录,规则只匹配 Bash 工具,再由 Python 脚本检查即将执行的命令。
.codex/hooks.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:
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 输出符合协议。
printf '%s\n' '{"hook_event_name":"PreToolUse","tool_input":{"command":"git reset --hard"}}' \
| python3 .codex/hooks/pre_tool_use_policy.py预期输出
{"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 本身,这样规则链既可审计,也不会把代理循环变成难以预测的脚本集合。