Hooks

Hooks 是 Codex 的扩展框架，让你在智能体循环期间运行脚本或 MCP 工具，实现诸如：把对话发送到自定义的日志或分析引擎、扫描团队的提示词以阻止不小心粘贴 API Key、总结对话以自动创建持久记忆、在对话回合停止时运行自定义验证检查强制标准、在特定目录里自定义提示。

hooks 如何运行：来自多个文件的匹配 hooks 都会运行；同一事件的多个匹配 command hook 并发启动，一个 hook 无法阻止另一个匹配的 hook 启动；非托管的 hooks 必须经过审查和信任才会运行。

事件

Codex 在哪里找 hooks

Codex 在活动配置层旁边以这两种形式之一发现 hooks：hooks.json，或 config.toml 里内联的 [hooks] 表。已安装的插件也可以通过插件清单或默认的 hooks/hooks.json 文件捆绑生命周期配置。实践中最常用的四个位置：~/.codex/hooks.json、~/.codex/config.toml、<repo>/.codex/hooks.json、<repo>/.codex/config.toml。存在多个 hook 来源时，Codex 加载所有匹配的 hooks，优先级更高的配置层不会替换较低层的 hooks；同一层里同时有 hooks.json 和内联 [hooks] 时，Codex 合并它们并在启动时警告，建议每层只用一种表示。项目本地 hooks 只在项目 .codex/ 层受信时加载；在不受信任的项目里，Codex 仍从各自的活动配置层加载用户和系统 hooks。

审查和信任 hooks

Codex 在决定哪些 hooks 可以运行之前先列出已配置的 hooks。非托管的 hook 运行前，Codex 要求你审查并信任其精确的定义，Codex 对照 hook 当前的哈希记录信任，所以新增或改动的 hooks 会被标记为待审查并被跳过，直到被信任。在 CLI 里用 /hooks 检查 hook 来源、审查新增或改动的 hooks、信任 hooks，或禁用单个非托管 hook；启动时有 hooks 需要审查，Codex 会打印警告让你打开 /hooks。来自系统、MDM、云端或 requirements.toml 来源的托管 hooks 被标记为托管、由策略信任，无法从用户 hook 浏览器里禁用。对已在 Codex 之外审核过 hook 来源的一次性自动化，传 --dangerously-bypass-hook-trust 可在该次调用里运行已启用的 hooks 而不要求持久的 hook 信任。

配置结构

hooks 分三层：hook 事件（如 PreToolUse、PostToolUse、PreCompact、SubagentStart、Stop）、决定何时匹配的 matcher 组、以及 matcher 组匹配时运行的一个或多个 hook 处理器。示例：

{
  "description": "Optional lifecycle hooks for this workspace.",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes",
            "additionalContextLimit": 5000
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

每个事件的输入输出载荷、返回值语义（如何阻止工具调用、注入上下文）和 timeout 等字段，以官方 Hooks 页为准。hooks 由 [features] 里的 hooks 标志控制（默认开启），见「配置基础」。