Hooks 事件驱动

总在事后才发现问题

那些"记得做"的事情，总被忘记

开始之前

Hooks 是什么

在 Codex 生命周期关键节点注入自定义逻辑

Hooks 让你可以在 Codex 执行过程中的特定事件触发时，运行自己的脚本或 AI 代理。它就像是一个事件监听器系统——你告诉 Codex："当 X 发生时，先执行 Y，再决定是否继续。"

10 种生命周期事件

从会话开始到结束，全覆盖

Codex 定义了 10 种生命周期事件，覆盖了一个完整会话的所有关键时刻。每个事件对应 config.toml 中 [hooks] 下的一个字段。

事件的三种角色

不是所有事件都一样——理解它们的差异

10 种事件虽然触发时机不同，但从"能做什么"的角度可以分为三大类：

command 处理器

Codex Hooks 唯一的处理器类型——运行可执行脚本

TOML 配置基础

在 config.toml 中声明你的 hook 规则

Hook 配置可放在 ~/.codex/config.toml、~/.codex/hooks.json，或项目级 .codex/config.toml、.codex/hooks.json。多个来源的匹配 hook 会全部加载（叠加，非覆盖）。每个事件字段是一个数组，数组元素称为 MatcherGroup。

# 一个完整的 MatcherGroup 结构
[[hooks.PreToolUse]]
matcher = "^(Write|Edit)$"          # 可选：正则匹配工具名

[[hooks.PreToolUse.hooks]]
type = "command"                     # 处理器类型
command = "python .codex/hooks/write_check.py"  # 执行的命令
timeout = 10                        # 超时秒数
statusMessage = "检查写入..."        # 状态栏显示文本

配置示例：多规则组合

同一个事件，多个规则叠加

下面是一个完整的 Hooks 配置示例，展示两个 PreToolUse 规则叠加使用：

# 规则 1：写入/编辑前安全检查
[[hooks.PreToolUse]]
matcher = "^(Write|Edit)$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python .codex/hooks/write_check.py"
timeout = 10
statusMessage = "检查写入操作..."

# 规则 2：所有工具调用都记录审计日志
[[hooks.PreToolUse]]
matcher = "*"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "echo $(date) >> .codex/audit.log"
timeout = 5
statusMessage = "记录审计日志..."

实战 1：PreToolUse 拦截危险命令

不让 rm -rf 或危险 git push 偷偷溜过去

最常见的用途——在工具执行前检查命令是否安全。下面是一个拦截器的实现：

#!/usr/bin/env python3
"""PreToolUse hook：检查 Bash 命令是否安全"""
import json
import sys
import re

# 从 stdin 读取事件上下文（JSON 格式）
context = json.loads(sys.stdin.read())
# 命令嵌套在 tool_input.command 中（Bash / apply_patch 工具）
command = context.get("tool_input", {}).get("command", "")

# 定义危险模式
DANGEROUS_PATTERNS = [
    r"rm\s+-rf\s+/",
    r"git\s+push\s+--force",
    r"DROP\s+TABLE",
    r"DELETE\s+FROM\s+\w+\s*$",
]

for pattern in DANGEROUS_PATTERNS:
    if re.search(pattern, command):
        # 输出拒绝原因到 stderr
        print(f"🚫 危险操作已拦截：{pattern}", file=sys.stderr)
        sys.exit(2)  # 退出码 2 = 拦截操作

sys.exit(0)  # 零 = 放行

# config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python .codex/hooks/safety_check.py"
timeout = 5
statusMessage = "安全检查中..."

实战 2：PostToolUse 自动格式化

每次写完代码自动跑 prettier / eslint

Codex 写完文件后，自动触发格式化工具——你再也不需要手动 cleanup。

# config.toml：写入后自动格式化
[[hooks.PostToolUse]]
matcher = "apply_patch|Edit|Write"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 .codex/hooks/auto_format.py"
timeout = 15
statusMessage = "自动格式化中..."

#!/usr/bin/env python3
"""auto_format.py：PostToolUse 写入后自动格式化"""
import json, sys, re, subprocess

ctx = json.loads(sys.stdin.read())
# apply_patch 的 tool_input.command 包含 patch 内容
patch = ctx.get("tool_input", {}).get("command", "")
# 从 patch 头部提取被修改的文件路径（+++ b/路径）
files = re.findall(r"^\+\+\+ b/(.+)$", patch, re.MULTILINE)

for f in files:
    subprocess.run(["npx", "prettier", "--write", f], timeout=10)

实战 3：SessionStart 注入 git 上下文

每次会话自动告诉 Codex 当前分支和状态

SessionStart hook 的标准输出会作为额外上下文注入到模型对话中。这是"自动给 Codex 提供环境信息"的最佳方式。

#!/usr/bin/env python3
"""SessionStart hook：收集 git 上下文"""
import subprocess

branch = subprocess.getoutput("git branch --show-current")
status = subprocess.getoutput("git status --short")
diff_stat = subprocess.getoutput("git diff --stat HEAD")

print(f"## 当前 Git 状态\n")
print(f"- 分支: {branch}")
print(f"- 变更文件:\n{status}")
print(f"- diff 统计:\n{diff_stat}")

# config.toml
[[hooks.SessionStart]]

[[hooks.SessionStart.hooks]]
type = "command"
command = "python .codex/hooks/git_context.py"
timeout = 10
statusMessage = "收集 Git 上下文..."

实战 4：SubagentStop 审计日志

记录每个子代理做了什么

当子代理完成任务返回时，SubagentStop 事件触发。你可以在这里记录子代理的执行结果，构建完整的审计追踪。

// hook 脚本从 stdin 收到的 JSON（通用字段）：
{
  "hook_event_name": "SubagentStop",
  "session_id": "sess-abc123",
  "turn_id": "turn-xyz",
  "cwd": "/path/to/repo",
  "model": "gpt-5-codex"
}

# config.toml：审计所有子代理结束事件
[[hooks.SubagentStop]]
matcher = "*"

[[hooks.SubagentStop.hooks]]
type = "command"
command = "python .codex/hooks/audit_subagent.py"
timeout = 5
statusMessage = "审计日志记录..."

实战 5：UserPromptSubmit 拦截敏感信息

防止把密码、密钥发给 AI

用户可能在 prompt 里粘贴包含密钥的内容。UserPromptSubmit hook 可以在 prompt 到达模型之前检测并拦截。

#!/usr/bin/env python3
"""UserPromptSubmit hook：检测敏感信息"""
import json
import re
import sys

context = json.loads(sys.stdin.read())
prompt = context.get("prompt", "")

SENSITIVE_PATTERNS = {
    "AWS Key": r"AKIA[0-9A-Z]{16}",
    "OpenAI Key": r"sk-[a-zA-Z0-9]{48}",
    "Private Key": r"-----BEGIN.*PRIVATE KEY-----",
    "Password in URL": r"://[^:]+:[^@]+@",
}

for name, pattern in SENSITIVE_PATTERNS.items():
    if re.search(pattern, prompt):
        print(f"🚫 检测到敏感信息：{name}", file=sys.stderr)
        print("请移除后重新提交。", file=sys.stderr)
        sys.exit(1)

sys.exit(0)

Trust 模型

第一次运行要让 Codex 信任你的 hook

Codex 不会无条件执行项目中的 hook 脚本——它需要你先信任这个项目。这是为了防止恶意仓库通过 hook 执行危险代码。

安全注意事项

Hook 脚本本身也是攻击面

Hooks 给了你巨大的权力，但也引入了新的风险。以下是必须注意的安全事项：

调试技巧

让 Hook 不再"黑盒"

Hook 脚本不像普通命令那样有直接的终端输出。以下是几个实用的调试方法：

with open(".codex/hook_debug.log", "a") as f:
    f.write(f"stdin: {sys.stdin.read()}\n")

小结

你已经掌握了 Codex Hooks 的核心