结论先说
- 同一配置层里支持两种声明格式(二选一,别混写):独立的
hooks.json文件,或者在config.toml里写内联[hooks]表;如果在同一个目录同时写了这两份,Codex 会把两边都加载并给出告警。 - 安全机制比普通脚本更严:非托管钩子按哈希值做信任锁定。不管是你自己的
~/.codex/hooks.json还是同事提交在仓库.codex/hooks.json里的钩子,首次添加或每次改了配置内容后,都必须进命令行敲/hooks审阅确认信任后才会真正运行。 - 跨层级钩子是「叠加并发执行」而不是覆盖:系统层、用户层和受信任项目层如果同时匹配了同一个事件,对应的多个命令钩子会并发拉起。
- 项目级钩子要求双重前提:不仅钩子哈希要通过审核,当前项目目录的
.codex/层本身也必须处于已受信任(Trusted)状态。

图:本站根据 OpenAI Codex 官方文档 Hooks 整理的示意图
本文根据 OpenAI Codex 官方文档《Hooks》与配置文件参考整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 搜「codex hooks 怎么配」「codex hooks.json 用法」的开发者与团队技术负责人;
- 用习惯了 Claude Code 的钩子机制(见 /guides/claude-code-hooks),切到或双持 Codex 时也想实现「命令执行前拦截」「回合结束前自动跑格式化与测试」的人;
- 照着文档建好了
.codex/hooks.json,但启动会话后发现脚本根本没跑、顶部还弹出一行审核提醒的同学。
如果你只是想在长任务跑完时弹一个系统桌面提醒或响一声,直接用更轻量的 notify 配置就够了(见 /guides/codex-notify-task-completion-alert);需要在智能体循环中间精细介入,才用本文讲的 Hooks。
一、钩子能挂在哪些时间点?官方事件分类表
按官方文档,Codex 将整场会话拆成了五类精确的挂载时机,覆盖从输入提示词到子代理结束的全链路:
- 单轮执行中途:
UserPromptSubmit(提交提示词时,可用于扫描阻断误贴密钥)、PreToolUse(调工具前校验)、PermissionRequest(请求权限时)、PostToolUse(工具返回后)、PreCompact/PostCompact(上下文压缩前后)、SubagentStop与Stop(当前轮准备停下时,最适合挂代码规范与测试检查); - 每次向模型发请求前后:
PreModelRequest、PostModelRequest; - 会话与子代理启停:
SessionStart、SubagentStart、SessionEnd(注:SessionEnd和人工打断时的Interrupt仅对主线程触发,不对子代理触发)。
二、配置文件放在哪,怎么写 hooks.json 与内联 TOML
本地 Codex 按从高到低的系统治理范围依次扫描四处位置:
- 系统托管层:macOS / Linux 为
/etc/codex/hooks.json,Windows 为%ProgramData%\OpenAI\Codex\hooks.json(由企业管理员下发,默认强制受信任且不可被个人关闭); - 个人用户层:
~/.codex/hooks.json(Windows 为%USERPROFILE%\.codex\hooks.json); - 受信任项目层:仓库内的
.codex/hooks.json; - 插件自带层:已启用插件目录下的
hooks/hooks.json。
写法 A:独立 JSON 文件(.codex/hooks.json)
结构分「事件名 → matcher 正则匹配组 → hooks 处理器列表」三层:
json
{
"description": "团队仓库 Bash 命令策略检查与收尾校验",
"hooks": {
"PreToolUse": [
{
"matcher": "^Bash$",
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/check_bash_policy.py",
"timeout": 30,
"statusMessage": "正在检查终端命令合规性"
}
]
}
]
}
}
写法 B:直接写进 config.toml(适合个人轻量配置)
如果你本来就在维护 ~/.codex/config.toml(完整键说明见 /guides/codex-config-toml-complete-guide),不想多建一个文件,可以用等价的 TOML 数组表语法:
toml
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/check_bash_policy.py"
timeout = 30
statusMessage = "Checking Bash command"

图:本站根据 OpenAI Codex 官方文档 Hooks 整理的示意图
三、关键一步:用 /hooks 审核信任让配置真正生效
这是防止克隆恶意开源仓库后一启动就被偷跑木马脚本的核心安全防线(沙箱基础见 /guides/codex-permissions-sandbox):
- 保存好
hooks.json后打开 Codex CLI,顶部会提示有待审核的钩子; - 输入斜杠命令
/hooks打开钩子管理器,查看来源路径与具体要执行的命令行; - 确认安全后标记为受信任(Trust)。注意信任绑定的是当前定义的哈希值——以后只要有人改动了里面的命令参数,旧信任立即失效,必须重新进
/hooks点一次确认。
日常用 Codex 搭自动化研发防护链、对比各档官方订阅所含本地与云端额度时,也可参考 /chongzhi/chatgpt-plus 的整理说明。
常见问题
Q:在 CI 流水线无头脚本里跑一次性任务,没法手敲 /hooks 点信任怎么办?
按官方文档说明,如果外部流水线环境已经自行完成了代码与钩子来源的安全审计,可以在单次命令行调用时显式传入 --dangerously-bypass-hook-trust,仅跳过这一次调用的持久化信任检查;切勿在来路不明的外部 PR 分支上开这个开关。
Q:为什么我的钩子脚本同一轮突然被执行了两遍?
检查是不是在 ~/.codex/ 用户目录和仓库 .codex/ 目录里登记了相同的钩子,或者在同一个目录既放了 hooks.json 又在 config.toml 里写了 [hooks]。删掉重复声明即可恢复单次运行。
相关教程
- /guides/codex-config-toml-complete-guide:Codex
config.toml核心配置项全解 - /guides/codex-notify-task-completion-alert:Codex 任务完成桌面通知与声音提醒配置
- /guides/codex-permissions-sandbox:Codex 权限审批与沙箱机制详解
- /guides/claude-code-hooks:Claude Code Hooks 配置方法横向对比
参考资料
- OpenAI Codex 官方文档:Hooks — https://learn.chatgpt.com/docs/hooks
- OpenAI Codex 开发者中心 — https://developers.openai.com/codex
0 条评论
还没有评论,来抢沙发~