1. 一句话理解 HooksCodex Hooks 是插入到 Codex 生命周期中的脚本回调机制当会话开始、用户提交提示词、工具执行前后、申请权限、上下文压缩或任务准备结束时Codex 可以自动执行指定脚本。Hooks 更适合做“必须执行的机械动作”例如执行命令前拦截危险操作提交 Prompt 前检测 API Key、Token 等敏感信息修改代码后执行格式化、测试或静态检查任务结束前检查交付内容是否完整记录工具调用和执行结果在会话开始时注入项目约定。它与AGENTS.md的区别是AGENTS.md告诉模型“应该怎么做”Hooks 会在固定事件上真实运行脚本。稳定的开发规范通常使用AGENTS.md Hooks前者负责解释和指导后者负责检查和兜底。2. 配置位置与作用范围Hooks 可以写成独立的hooks.json也可以内联到同级的config.toml。作用范围推荐位置适用场景当前用户的所有项目~/.codex/hooks.json个人统一习惯、通知、日志当前用户的全局配置~/.codex/config.tomlHooks 与其他 Codex 配置集中管理单个 Git 仓库repo/.codex/hooks.json团队共享的测试、安全和交付规则单个仓库的统一配置repo/.codex/config.toml项目配置与 Hooks 集中管理注意项目级 Hooks 只有在该项目被 Codex 标记为可信时才会加载。多个配置来源命中的 Hooks 会全部执行不是高优先级覆盖低优先级。同一层不要同时写hooks.json和内联[hooks]否则虽然会合并但启动时会警告。非管理员托管的 Hook 首次运行或内容变更后需要通过/hooks重新审核和信任。3. Hook 的结构一个 Hook 分三层事件什么时候触发例如PreToolUse、PostToolUse、Stop匹配器过滤哪些工具或触发来源处理器实际执行的脚本命令。{hooks:{PostToolUse:[{matcher:Bash|apply_patch,hooks:[{type:command,command:/usr/bin/python3 \$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use.py\,timeout:30,statusMessage:Checking code changes}]}]}}当前应以type: command为准。prompt和agent类型虽然能够被解析但尚不会执行async也尚未真正支持。timeout单位为秒省略时默认值为 600 秒。4. 常用生命周期事件事件触发时机典型用途SessionStart新建、恢复、清空或压缩后启动会话加载项目说明、环境检查UserPromptSubmit用户 Prompt 发给模型之前敏感信息检测、补充上下文PreToolUseBash、apply_patch或 MCP 工具执行前拦截危险命令、改写参数PermissionRequestCodex 准备请求用户授权时按企业或仓库策略允许/拒绝PostToolUse支持的工具产生结果之后校验输出、运行后置检查、补充反馈PreCompact上下文压缩前保存状态、决定是否允许压缩PostCompact上下文压缩后恢复必要上下文、记录压缩事件SubagentStart子智能体启动时注入子任务约束SubagentStop子智能体准备结束时检查子任务结果、要求继续完善Stop当前任务回合准备结束时验收测试、交付检查、要求补充说明其中PreToolUse、PostToolUse目前主要覆盖 Bash、apply_patch和 MCP 工具并不能拦截所有执行路径因此它是工作流护栏不应被视为完整的安全边界。5. Matcher 匹配规则matcher是正则表达式。*、空字符串或省略表示全部匹配。常见写法Bash ^apply_patch$ Edit|Write mcp__filesystem__.* startup|resume manual|auto不同事件匹配的字段不同PreToolUse、PostToolUse、PermissionRequest匹配工具名SessionStart匹配startup、resume、clear、compactPreCompact、PostCompact匹配manual或autoSubagentStart、SubagentStop匹配子智能体类型UserPromptSubmit、Stop当前不使用 matcher配置了也会被忽略。6. Hook 脚本的输入与输出6.1 输入Codex 会通过标准输入stdin向脚本传入一个 JSON 对象。常用公共字段包括字段含义session_id当前会话 IDturn_id当前任务回合 ID主要出现在回合级事件中cwd当前工作目录hook_event_name当前 Hook 事件名model当前模型标识permission_mode当前权限模式transcript_path会话记录路径格式并非稳定接口不建议强依赖工具事件还会提供tool_name、tool_input、tool_response等字段。Python 脚本读取方式importjsonimportsys payloadjson.load(sys.stdin)eventpayload[hook_event_name]cwdpayload[cwd]6.2 输出退出码0且无输出检查通过继续执行。某些事件可以在stdout输出 JSON用于放行、拒绝、注入上下文或要求 Codex 继续。在支持的阻断场景中可用退出码2并把原因写入stderr。不同事件支持的输出字段并不相同不要把某个事件的返回结构直接复制给另一个事件。例如在PreToolUse中拒绝危险工具调用{hookSpecificOutput:{hookEventName:PreToolUse,permissionDecision:deny,permissionDecisionReason:Destructive command blocked by hook.}}例子我的需求是开发完成后自动讲解修改逻辑7.1 推荐方案这个需求有两层“说明应该写什么”属于模型行为规范适合写进仓库的AGENTS.md“没有说明就不允许结束”属于机械验收适合用StopHook 兜底。建议先在AGENTS.md中加入## 代码修改后的交付要求 凡是修改代码最终回复必须包含 1. 修改目的 2. 核心实现逻辑 3. 关键文件或函数 4. 验证方式与结果 5. 尚存风险或限制没有则明确写“无”。这样通常已经够用而且比每次结束时强制多跑一轮更节省 Token。7.2 Stop Hook 兜底示例项目目录repo/ ├── AGENTS.md └── .codex/ ├── hooks.json └── hooks/ └── require_change_explanation.py.codex/hooks.json{hooks:{Stop:[{hooks:[{type:command,command:/usr/bin/python3 \$(git rev-parse --show-toplevel)/.codex/hooks/require_change_explanation.py\,timeout:15,statusMessage:Checking delivery explanation}]}]}}.codex/hooks/require_change_explanation.pyimportjsonimportsys payloadjson.load(sys.stdin)# 防止 Stop Hook 已经要求继续后再次形成循环。ifpayload.get(stop_hook_active):print(json.dumps({continue:True}))raiseSystemExit(0)answerpayload.get(last_assistant_message)orrequired_markers(修改目的,实现逻辑,验证)ifnotall(markerinanswerformarkerinrequired_markers):print(json.dumps({decision:block,reason:(如果本轮修改了代码请补充交付说明修改目的、核心实现逻辑、关键文件或函数、验证方式与结果、风险或限制如果没有修改代码请直接说明本轮未修改代码。)},ensure_asciiFalse))else:print(json.dumps({continue:True}))工作原理当 Codex 准备结束回合时脚本检查最后一条回复是否包含必要说明缺失时返回decision: block。在Stop事件中这不是拒绝结果而是让 Codex 根据reason自动继续一轮。脚本必须检查stop_hook_active否则可能反复要求继续。局限该简化示例只能检查最终回复结构不能准确判断“本轮是否真的修改过代码”。如果仓库经常存在用户自己的未提交改动不建议简单使用git diff判断是否由 Codex 修改更严格的方案需要在SessionStart或任务开始时记录基线再在Stop时比较。8. 配置后的启用与验证创建.codex/hooks.json和脚本文件。确认项目已被 Codex 信任。重启 Codex 或新开会话。在 CLI 输入/hooks。检查 Hook 来源、命令和脚本路径并信任新增 Hook。发起一个小型代码修改任务观察状态提示和最终说明。修改 Hook 内容后再次打开/hooks重新审核新的内容哈希。排查命令命令用途/hooks查看、信任或禁用 Hooks/status查看当前模型、权限、上下文和会话配置/debug-config排查配置层级和生效来源/diff查看当前工作区改动/review对当前工作区执行代码审查如需临时关闭全部 Hooks可在config.toml中配置[features] hooks false实践建议从一个窄用途 Hook 开始例如只检查最终交付说明不要一开始就拦截所有事件。Hook 脚本要快、确定、可重复不要在里面执行耗时且不稳定的大模型调用。对Stop和SubagentStop必须处理“已经继续过”的状态防止死循环。不要把 Hook 当作唯一安全边界危险操作仍应结合 Codex 权限、沙箱和人工审批。团队共享的 Hooks 放在仓库.codex/中脚本路径从 Git 根目录解析避免从子目录启动时找不到文件。项目规范优先放在AGENTS.md格式化、测试、扫描、阻断等确定性动作再交给 Hooks。第三方文章和视频可能基于早期版本事件类型、返回结构和支持范围应以当前官方 Hooks 页面为准。资料来源OpenAI 官方Codex HooksOpenAI 官方Codex CLI Slash CommandsGoogle 搜索中的 Codex Hooks 视频入口菜鸟教程Codex 斜杆命令