AI_Coding: Hooks-开发者社区

1. 一句话理解 Hooks

Codex 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.toml`	Hooks 与其他 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 发给模型之前	敏感信息检测、补充上下文
`PreToolUse`	Bash、`apply_patch`或 MCP 工具执行前	拦截危险命令、改写参数
`PermissionRequest`	Codex 准备请求用户授权时	按企业或仓库策略允许/拒绝
`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、compact；
PreCompact、PostCompact：匹配manual或auto；
SubagentStart、SubagentStop：匹配子智能体类型；
UserPromptSubmit、Stop：当前不使用 matcher，配置了也会被忽略。

6. Hook 脚本的输入与输出

6.1 输入

Codex 会通过标准输入stdin向脚本传入一个 JSON 对象。常用公共字段包括：

字段	含义
`session_id`	当前会话 ID
`turn_id`	当前任务回合 ID，主要出现在回合级事件中
`cwd`	当前工作目录
`hook_event_name`	当前 Hook 事件名
`model`	当前模型标识
`permission_mode`	当前权限模式
`transcript_path`	会话记录路径；格式并非稳定接口，不建议强依赖

工具事件还会提供tool_name、tool_input、tool_response等字段。

Python 脚本读取方式：

importjsonimportsys payload=json.load(sys.stdin)event=payload["hook_event_name"]cwd=payload["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.py：

importjsonimportsys payload=json.load(sys.stdin)# 防止 Stop Hook 已经要求继续后再次形成循环。ifpayload.get("stop_hook_active"):print(json.dumps({"continue":True}))raiseSystemExit(0)answer=payload.get("last_assistant_message")or""required_markers=("修改目的","实现逻辑","验证")ifnotall(markerinanswerformarkerinrequired_markers):print(json.dumps({"decision":"block","reason":("如果本轮修改了代码，请补充交付说明：修改目的、核心实现逻辑、""关键文件或函数、验证方式与结果、风险或限制；如果没有修改代码，""请直接说明本轮未修改代码。")},ensure_ascii=False))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`	对当前工作区执行代码审查