�� OpenAI Codex Hooks:让 AI 编程助手变得「可编程」

你以为 Codex 只是帮你写代码？错——它现在可以被你「编程控制」了。

一、AI Agent 时代的新问题

当 AI 编程助手从"补全代码"进化为"自主执行任务"，一个新的问题浮出水面：

我怎么知道它在做什么？我能不能在它做之前拦一下？

你给 Codex 一个任务，它开始自主运行——读文件、改代码、执行命令……整个过程就像一个黑盒。对于个人开发者来说还好，但一旦进入团队、企业环境，这种"失控感"就是隐患。

OpenAI 的答案是：Hooks。

二、什么是 Codex Hooks？

Hooks 是 Codex 的生命周期钩子框架——一套让你在 AI Agent 运行循环（Agentic Loop）的关键节点，注入自己脚本的机制。

理解它的最好方式是类比：

就像 Git 有 pre-commit、post-merge 钩子，
Codex 现在有 PreToolUse、PostToolUse、Stop……
你的脚本，在 AI 行动前后运行。

用一句话总结：
Hooks 把 Codex 从「听话的 AI」变成了「可编程的智能工作流」。

三、Codex 的 Agent Loop 是怎么运转的？

在聊 Hooks 之前，先理解 Codex 的工作机制：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line用户输入    ↓构建 Prompt（指令 + 工具 + 上下文）    ↓模型推理    ↓决策：直接回复 or 调用工具？    ↓ ← 这里就是 Hooks 的插入点执行工具（Bash、文件读写…）    ↓结果反馈给模型    ↓循环，直到任务完成

每完成一次"用户输入 → 最终回复"的完整过程，叫做一轮 Turn。

Hooks 就是在这个循环的各个节点，让你的脚本参与进来——不是建议，是干预。

四、6 大核心事件，覆盖全生命周期


事件	触发时机	能做什么
`SessionStart`	会话启动/恢复/清除时	注入上下文、加载记忆、初始化环境
`PreToolUse`	工具执行前	⚡ 拦截危险命令！审计、扫描、阻止
`PostToolUse`	工具执行后	日志记录、结果校验、触发通知
`UserPromptSubmit`	用户发送提示后	敏感信息过滤、prompt 增强
`Stop`	每轮对话结束时	质量检查、自动继续执行
`PermissionRequest`	需要权限确认时	自定义权限逻辑

🔥 最强能力：PreToolUse 拦截

PreToolUse 是所有 Hooks 中最"强硬"的一个。

当 Codex 准备执行 Bash 命令时，你的脚本先运行。如果返回 "permissionDecision": "deny"，这条命令直接被阻止，Codex 不会执行它。

这意味着你可以：

阻止 rm -rf 等危险命令
拦截访问敏感目录的操作
在执行前做安全扫描

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line{  "hookSpecificOutput": {    "hookEventName": "PreToolUse",    "permissionDecision": "deny",    "permissionDecisionReason": "检测到危险命令，已被安全策略阻止。"  }}

五、5 分钟上手：最简配置

第一步：开启功能旗标

编辑 ~/.codex/config.toml：

ounter(lineounter(line[features]codex_hooks = true

第二步：创建 hooks.json

在 ~/.codex/hooks.json 写下你的第一个 Hook：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line{  "hooks": {    "SessionStart": [      {        "matcher": "startup",        "hooks": [          {            "type": "command",            "command": "echo '🚀 Codex 已启动，当前目录：'$(pwd)",            "statusMessage": "初始化环境..."          }        ]      }    ],    "PreToolUse": [      {        "matcher": "Bash",        "hooks": [          {            "type": "command",            "command": "python3 ~/.codex/scripts/safety_check.py",            "statusMessage": "安全扫描中...",            "timeout": 10          }        ]      }    ]  }}

配置支持三层，会全部合并运行：

ounter(lineounter(lineounter(line~/.codex/hooks.json          ← 全局生效~/.codex/config.toml         ← 内联 TOML 配置  <项目>/.codex/hooks.json     ← 项目级（需项目被信任）

六、4 个「开箱即用」的实战场景

🔐 场景一：防止 API Key 泄露

在 UserPromptSubmit 事件写一个脚本，扫描用户提交的 Prompt，检测是否包含 sk-xxx 格式的 API Key，发现就阻止发送并告警。

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineimport json, sys, redata = json.load(sys.stdin)prompt = data.get("userPrompt", "")if re.search(r'sk-[A-Za-z0-9]{20,}', prompt):    print(json.dumps({        "decision": "block",        "reason": "⚠️ 检测到 API Key，已阻止发送！请勿在对话中粘贴密钥。"    }))else:    print(json.dumps({"decision": "approve"}))

🧠 场景二：自动生成对话记忆

在 Stop 事件调用脚本，读取 transcript_path 中的完整对话记录，自动总结本次工作内容，追加到 ~/.codex/memory.md。

下次启动时通过 SessionStart 把这份记忆注入上下文——Codex 记住了上次你干了什么。

✅ 场景三：强制代码规范

在 Stop 事件运行 eslint 或 black 格式化检查。如果不通过，返回：

ounter(lineounter(lineounter(lineounter(line{  "decision": "block",  "reason": "代码格式检查未通过，请先修复 lint 错误再提交。"}

Codex 会把这条信息当作新的 Prompt 继续处理——自动修 lint，不需要你开口。

📊 场景四：操作审计日志

在 PostToolUse 事件记录每次 Bash 执行的命令、时间、工作目录，写入日志文件。团队场景下，所有 AI 操作都有迹可查。

七、企业级：托管 Hooks

对于需要统一管控的团队，Codex 支持托管 Hooks（Managed Hooks）。

通过 requirements.toml 中的 managed_dir 配置，管理员可以下发强制执行的 Hooks，成员无法绕过。这是企业合规、安全审计的核心基础。

ounter(lineounter(lineounter(line# requirements.toml[managed]managed_dir = "/opt/company/codex-hooks"

八、Hooks vs AGENTS.md：两者如何配合？

很多人用 AGENTS.md 给 Codex 写指令。Hooks 和它的区别是什么？

对比	AGENTS.md	Hooks
性质	静态文本指令	动态可执行脚本
加载时机	会话开始时一次性读入	循环每个节点实时运行
能力边界	"告诉"模型该怎么做	直接干预、拦截、注入
适合场景	行为规范、偏好设置	安全控制、自动化、审计

两者不是竞争关系，而是互补。
AGENTS.md 定义"应该怎么做"，Hooks 保证"确实是这么做的"。

九、一些注意事项

⚠️ 当前仍是实验性功能，需手动在 config.toml 中开启
⚠️ 暂不支持 Windows 系统
⚠️ 同一事件的多个 Hooks 并发执行，注意脚本间的竞争条件
⚠️ 项目级 Hooks 只在项目被信任后才会加载
⚠️ Hook 脚本默认超时 600 秒，可以在配置中自定义

十、结语：AI Agent 的「可编程时代」

Hooks 的出现，标志着 AI 编程助手进入了新阶段：

不只是"更聪明的自动补全"
不只是"可以对话的助手"
而是可以被你编程控制的智能工作流

当你能在 AI 的每个动作前后插入自己的逻辑，AI 就不再是黑盒。

这正是 Codex Hooks 的核心价值：把确定性还给开发者，把灵活性留给 AI。

📎 官方文档：https://developers.openai.com/codex/hooks
📦 开源仓库：https://github.com/openai/codex

💬 你最想用 Hooks 做什么？欢迎留言分享你的创意！