夜雨聆风你以为 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 | ||
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 保证"确实是这么做的"。
九、一些注意事项
⚠️ 当前仍是实验性功能，需手动在 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 做什么？欢迎留言分享你的创意！
