Codex Hooks(钩子)怎么配:hooks.json 路径、触发事件与 /hooks 信任审核

想让 Codex 在执行工具前自动做策略校验、改完代码停下前自动跑单测,可以配置内置的生命周期钩子(Hooks)。本文根据官方文档讲清 hooks.json 与 config.toml 两种写法、四大加载层级、完整事件表以及必做的 /hooks 哈希信任审核。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Plus 账号

结论先说

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

Codex 四层 Hooks 加载位置与信任

图:本站根据 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 按从高到低的系统治理范围依次扫描四处位置:

  1. 系统托管层:macOS / Linux 为 /etc/codex/hooks.json,Windows 为 %ProgramData%\OpenAI\Codex\hooks.json(由企业管理员下发,默认强制受信任且不可被个人关闭);
  2. 个人用户层:~/.codex/hooks.json(Windows 为 %USERPROFILE%\.codex\hooks.json);
  3. 受信任项目层:仓库内的 .codex/hooks.json;
  4. 插件自带层:已启用插件目录下的 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"

配置并启用 Codex 生命周期钩子四步

图:本站根据 OpenAI Codex 官方文档 Hooks 整理的示意图

三、关键一步:用 /hooks 审核信任让配置真正生效

这是防止克隆恶意开源仓库后一启动就被偷跑木马脚本的核心安全防线(沙箱基础见 /guides/codex-permissions-sandbox):

  1. 保存好 hooks.json 后打开 Codex CLI,顶部会提示有待审核的钩子;
  2. 输入斜杠命令 /hooks 打开钩子管理器,查看来源路径与具体要执行的命令行;
  3. 确认安全后标记为受信任(Trust)。注意信任绑定的是当前定义的哈希值——以后只要有人改动了里面的命令参数,旧信任立即失效,必须重新进 /hooks 点一次确认。

日常用 Codex 搭自动化研发防护链、对比各档官方订阅所含本地与云端额度时,也可参考 /chongzhi/chatgpt-plus 的整理说明。

常见问题

Q:在 CI 流水线无头脚本里跑一次性任务,没法手敲 /hooks 点信任怎么办?

按官方文档说明,如果外部流水线环境已经自行完成了代码与钩子来源的安全审计,可以在单次命令行调用时显式传入 --dangerously-bypass-hook-trust,仅跳过这一次调用的持久化信任检查;切勿在来路不明的外部 PR 分支上开这个开关。

Q:为什么我的钩子脚本同一轮突然被执行了两遍?

检查是不是在 ~/.codex/ 用户目录和仓库 .codex/ 目录里登记了相同的钩子,或者在同一个目录既放了 hooks.json 又在 config.toml 里写了 [hooks]。删掉重复声明即可恢复单次运行。

相关教程

参考资料

  • OpenAI Codex 官方文档:Hooks — https://learn.chatgpt.com/docs/hooks
  • OpenAI Codex 开发者中心 — https://developers.openai.com/codex

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    多 Agent 协同开发怎么落地:「一个写、一个审」双代理工作流搭建指南

    多 Agent 协同开发里投入产出比最高的模式就是「一个写、一个审」。本文依据 Anthropic 与 OpenAI 官方编码最佳实践,讲清为什么同会话自审容易漏问题,以及用只读子代理、跨模型交叉审查(Claude Code + Codex)和自动化闭环落地的具体方法。

    ClaudeCodex0
  2. 02

    codebase-memory 类 MCP 是什么、怎么用:基于语法树图谱的本地代码索引原理与配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一类本地代码图谱 MCP 服务器:用 Tree-sitter 把仓库解析成函数与调用关系的 SQLite 图库,帮编码助手查调用链并省下读整份文件的额度。

    ClaudeCodex0
  3. 03

    Chrome DevTools MCP 怎么用、怎么保留登录态:安装配置、独立目录与远程调试端口连接

    Chrome DevTools MCP 本身免费且无需注册账号,大家搜「登录」通常是为了让 AI 调试需要登录的网页后台。本文按官方仓库文档讲清安装命令,以及用 --userDataDir 持久化独立配置目录、用 --browserUrl 挂载已登录浏览器的两种标准做法。

    ClaudeCodex0
  4. 04

    Codex 接入 Amazon Bedrock 与 Google Cloud Vertex AI 教程:企业云托管配置

    企业合规要求模型流量统一走自家 AWS 或 GCP 云账单时,不需要硬拼第三方代理。本文根据 OpenAI Codex 官方文档,讲清原生接入 Amazon Bedrock(四种 AWS 凭证方式)与 Google Cloud Vertex AI(ADC 认证与区域驻留)的完整步骤。

    Codex0
  5. 05

    Codex 自动审查 GitLab Merge Request 怎么配:公有云与自托管实例接入指南

    代码托管在 GitLab 的团队同样可以用上 OpenAI 官方的云端代码审查。本文根据官方文档讲清 GitLab.com 与企业自托管实例的服务账号配置、Developer 权限、Webhook 开启与 AGENTS.md 规则约束。

    ChatGPTCodex0
  6. 06

    Codex 接入 Linear 怎么用:指派 Issue、评论 @Codex 自动改码与 Triage 分流教程

    用 Linear 管研发任务单的团队,可以直接把 Issue 指派给 Codex 或在评论区 @Codex 自动拉起云端环境改代码。本文按 OpenAI 官方文档讲清云端环境前置准备、连接器安装、多仓库指定技巧以及 Triage 规则自动派单配置。

    ChatGPTCodex0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~