钩子

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

Hooks 是一个用于 Codex的扩展框架。它们允许你将自己的脚本注入到智能体循环中，从而启用如下功能：

将聊天发送到自定义 logging/analytics 引擎
扫描团队的提示词，以阻止意外粘贴 API 密钥
汇总聊天以自动创建持久记忆
在聊天轮次停止时运行自定义验证检查，以执行标准
在特定目录中自定义提示

需要注意的运行时行为：

来自多个文件的匹配 hooks 都会运行。
同一事件的多个匹配命令 hooks 会并发启动，因此一个 hook 无法阻止另一个匹配 hook 启动。
非托管命令 hooks 必须经过审核并受信任后才能运行。

钩子会在对话中的不同时间点运行：

何时	Hooks
在一个轮次期间	`PreToolUse`， `PermissionRequest`， `PostToolUse`， `PreCompact`， `PostCompact`， `UserPromptSubmit`， `SubagentStop`， `Stop`
当会话或子智能体启动时	`SessionStart`， `SubagentStart`
当主线程结束时	`SessionEnd` （不对子智能体运行）

Codex 查找钩子的位置

Codex 会在以下任一形式的活动配置层旁查找钩子：

hooks.json
内联 [hooks] 表位于 config.toml

已安装的插件也可以通过其插件清单或默认 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 会合并它们并在启动时发出警告。每个层最好只使用一种表示方式。

Codex 还可以发现与已启用插件捆绑的 hooks。插件捆绑的 hooks 会与其他 hook 来源一起加载，并使用与其他非托管 hooks 相同的信任审核流程。

仅当项目 .codex/ 层受信任时，项目本地 hooks 才会加载。在不受信任的项目中， Codex 仍会从各自的活动配置层加载用户和系统 hooks。

审查并信任钩子

Codex 会先列出已配置的 hooks，然后再决定哪些可以运行。在非托管命令 hook 运行之前， Codex 要求你审核并信任该确切 hook 定义。 Codex 会根据 hook 当前的哈希记录信任状态，因此新的或已更改的 hooks 会被标记为待审核，并在受信任之前跳过。

使用 /hooks 在 CLI 中检查 hook 来源、审核新的或已更改的 hooks、信任 hooks，或禁用单个非托管 hooks。如果 hooks 在启动时需要审核， Codex 会打印一条警告，提示你打开 /hooks。

来自系统、 MDM、cloud 或 requirements.toml 来源的托管 hooks 会被标记为托管，按策略受信任，并且无法从用户 hook 浏览器中禁用。

对于已经在 Codex之外验证 hook 来源的一次性自动化，传入 --dangerously-bypass-hook-trust 即可运行已启用的 hooks，而不要求该次调用具有持久化的 hook 信任。

配置结构

钩子分为三个层级：

一个 hook 事件，例如 PreToolUse、 PostToolUse、 PreCompact、 SubagentStart，或 Stop
一个用于决定该事件何时匹配的匹配器组
一个或多个在匹配器组匹配时运行的 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
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_end.py",
            "timeout": 3
          }
        ]
      }
    ],
    "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"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/permission_request.py\"",
            "statusMessage": "Checking approval request"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py\"",
            "statusMessage": "Reviewing Bash output"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/user_prompt_submit_data_flywheel.py\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_continue.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

注意：

description 是 hooks.json 文件的可选顶层元数据。它不会改变哪些 hooks 会运行。
timeout 以秒为单位。
如果 timeout 被省略， Codex 对大多数 hooks 使用 600 秒。
- SessionEnd 默认使用 1 秒，并最高支持 3 秒。
statusMessage 是可选的。
additionalContextLimit 设置命令 hook 可向模型 additionalContext 发送多少内容，然后 Codex 会将完整文本保存到磁盘，并改为发送较短的预览。请参阅大型 hook 输出。
commandWindows 是一个仅限 Windows 的可选命令覆盖。在 TOML中，使用 command_windows 或 commandWindows。
会解析 async 选项，但尚不支持异步命令 hooks 。
目前只有 type: "command" 处理程序会运行。 prompt 和 agent 处理程序会被解析但跳过。
命令会以会话 cwd 作为其工作目录运行。
对于仓库本地 hooks，建议从 git root instead of using a relative path such 解析为 .codex/hooks/...。 Codex 可能从子目录启动，而基于 git 根目录的路径可让 hook 位置保持稳定。

等效的内联 TOML 位于 config.toml：

[[hooks.SessionStart]]
matcher = "^compact$"

[[hooks.SessionStart.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/session_start.py"'
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'
timeout = 30
statusMessage = "Reviewing Bash output"

关闭钩子

钩子默认处于启用状态。要在 config.toml 中关闭钩子，请设置：

[features]
hooks = false

使用 hooks 作为规范功能键。 codex_hooks 仍可作为已弃用的别名使用。管理员也可以在 requirements.toml 中使用 [features].hooks = false以同样方式强制关闭 hooks。

来自 `requirements.toml` 的托管钩子

企业托管要求也可以在 [hooks]下内联定义 hooks。当管理员希望强制执行 hook 配置，同时通过 MDM 或其他设备管理系统交付实际脚本时，这很有用。若要即使用户在本地禁用了 hooks 也强制执行托管 hooks，请在 [features].hooks = true 中将 requirements.toml 与 [hooks]一起固定。若要忽略用户、项目、会话和插件 hooks，同时仍允许管理员托管 hooks，请设置 allow_managed_hooks_only = true。

allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
timeout = 30
statusMessage = "Checking managed Bash command"

托管钩子的注意事项：

managed_dir 用于 macOS 和 Linux。
windows_managed_dir 用于 Windows。
Codex 不会分发 managed_dir中的脚本；你的企业工具必须单独安装和更新它们。
托管 hook 命令应使用配置的托管目录下的绝对脚本路径。
allow_managed_hooks_only = true 会跳过来自用户、项目、会话和插件来源的 hooks，但仍会从 requirements.toml 和其他托管配置层加载托管 hooks。

插件捆绑的钩子

启用插件后， Codex 可以从该插件加载生命周期 hooks，并与用户、项目和托管 hooks 一起使用。

默认情况下， Codex 会查找 hooks/hooks.json 在插件根目录内。插件清单可以通过 hooks 中的条目 .codex-plugin/plugin.json覆盖该默认设置。清单条目可以是一个 ./-prefixed 路径，一个由 ./-prefixed 路径组成的数组，一个内联 hooks 对象，或一个内联 hooks 对象数组。

{
  "name": "repo-policy",
  "hooks": "./hooks/hooks.json"
}

清单 hook 路径会相对于插件根目录解析，并且必须保持在该根目录内。如果清单定义了 hooks， Codex 会使用这些清单条目，而不是默认的 hooks/hooks.json。

插件钩子命令会接收以下环境变量：

PLUGIN_ROOT 是一个 Codex-specific 扩展，指向已安装的插件根目录。
PLUGIN_DATA 是一个 Codex-specific 扩展，指向插件的可写数据目录。
Codex 还会设置 CLAUDE_PLUGIN_ROOT 和 CLAUDE_PLUGIN_DATA 以便兼容现有插件 hooks。

插件 hooks 使用与其他 hooks 相同的事件架构。安装或启用插件不会自动信任其 hooks； Codex 会跳过插件捆绑的 hooks 直到你审核并信任当前 hook 定义。

匹配器模式

该 matcher 字段是一个正则表达式字符串，用于筛选 hooks 何时触发。使用 "*"， ""，或完全省略 matcher 以匹配受支持事件的每一次发生。

目前只有部分 Codex 事件支持 matcher：

事件	什么 `matcher` 过滤器	备注
`PermissionRequest`	工具名称	支持包括 `Bash`、 `apply_patch`*和 MCP 工具名称
`PostToolUse`	工具名称	请参阅工具覆盖范围
`PostCompact`	压缩触发器	值为 `manual` 或 `auto`
`PreCompact`	压缩触发器	值为 `manual` 或 `auto`
`PreToolUse`	工具名称	请参阅工具覆盖范围
`SessionEnd`	结束原因	目前仅 `other`
`SessionStart`	启动来源	值为 `startup`、 `resume`、 `clear`和 `compact`
`SubagentStart`	子智能体类型	值取决于启动的子智能体
`SubagentStop`	子智能体类型	值取决于停止的子智能体
`UserPromptSubmit`	不支持	任何已配置的 `matcher` 都会对此事件忽略
`Stop`	不支持	任何已配置的 `matcher` 都会对此事件忽略

*对于 apply_patch， matcher 值也可以使用 Edit 或 Write。

示例：

Bash
^apply_patch$
Edit|Write
mcp__filesystem__read_file
mcp__filesystem__.*
startup|resume|clear|compact
manual|auto

工具覆盖范围

PreToolUse 和 PostToolUse 可以观察的不只是 shell 和 MCP 调用。大多数本地函数工具使用相同的 hook 路径，因此你可以匹配其工具名称、检查其 JSON 参数，并且对于 PreToolUse，阻止或重写调用。

工具路径	`PreToolUse`	`PostToolUse`	备注
Shell 命令	是	是	匹配为 `Bash`。
统一 exec（`exec_command`）	是	是	匹配为 `Bash`。后续的 `write_stdin` 轮询可在原始命令完成时传递其 `PostToolUse` 。
`apply_patch`	是	是	匹配为 `apply_patch`、 `Edit`，或 `Write`。
MCP 工具	是	是	匹配 MCP 工具名称，例如 `mcp__filesystem__read_file`。
其他本地函数工具	是	是	匹配函数工具名称，例如 `update_plan`。 `spawn_agent` 也会匹配 `Agent`。
托管工具，例如 `WebSearch`	否	否	这些不使用本地函数工具 hook 路径。

write_stdin 是现有统一 exec 会话的传输通道。它在发送输入或轮询已通过 PreToolUse 的命令时，不会再次运行 PreToolUse。

某些专用工具路径可以选择退出默认 hook 路径。请将工具 hooks 视为有用的防护措施，而不是完整的强制执行边界。

通用输入字段

每个命令 hook 都会在 JSON 上收到一个 stdin对象。

以下是你通常会使用的共享字段：

字段	类型	含义
`session_id`	`string`	当前 Codex 会话 ID。子智能体 hooks 使用父会话 ID。
`transcript_path`	`string \| null`	会话转录文件的路径（如果有）
`cwd`	`string`	会话的工作目录
`hook_event_name`	`string`	当前 hook 事件名称
`model`	`string`	Codex-specific 扩展。活动模型 slug

轮次范围的 hooks 会在其 turn_id 事件专用表中将 Codex-specific 列为扩展。

SessionStart、 PreToolUse、 PermissionRequest、 PostToolUse、 UserPromptSubmit、 SubagentStart、 SubagentStop和 Stop 也包含 permission_mode，它将当前权限模式描述为 default、 acceptEdits、 plan、 dontAsk，或 bypassPermissions。

transcript_path 为方便起见指向聊天转录，但转录格式并不是 hooks 的稳定接口，可能会随时间变化。

如果需要完整的传输格式，请参阅架构。

通用输出字段

SessionStart、 PreCompact、 PostCompact、 UserPromptSubmit、 SubagentStop和 Stop 支持这些共享 JSON 字段。 SubagentStart 接受相同的 systemMessage 和 hook 专用上下文形状，但 continue: false 不会停止子智能体：

{
  "continue": true,
  "stopReason": "optional",
  "systemMessage": "optional",
  "suppressOutput": false
}

字段	效果
`continue`	如果 `false`，则将该 hook 运行标记为已停止
`stopReason`	记录为停止原因
`systemMessage`	在 UI 或事件流中显示为警告
`suppressOutput`	目前会解析，但尚未实现

退出码为 0 且没有输出会被视为成功，Codex 会继续运行。

PreToolUse 和 PermissionRequest 支持 systemMessage，但 continue， stopReason，以及 suppressOutput 目前不支持这些事件。如果 PreToolUse 钩子返回其中某个不受支持的字段， Codex 会将该钩子运行标记为失败，报告错误，并继续工具调用。

PostToolUse 支持 systemMessage， continue: false，以及 stopReason。 suppressOutput 会被解析，但目前不支持该事件。

较大的钩子输出

默认情况下， Codex 会将每条模型可见的钩子输出消息限制在大约 2,500 个 token。如果钩子返回更多内容， Codex 会将完整文本保存到 <temp_dir>/hook_outputs/<session_id>/<uuid>.txt 并向模型提供包含保存文件路径的头尾预览。此行为称为溢出： Codex 将过大的输出存储到磁盘，并替换为更短的、模型可见的预览。如果无法写入文件，模型仍会收到截断后的预览。

保持钩子和插件上下文简洁。来自多个钩子和插件的上下文会累加，并可能降低模型性能。提高 additionalContextLimit 会增加这种风险。避免将限制设置为 0 ，除非钩子强制执行严格的输出上限；否则，单个钩子可能消耗整个上下文窗口。

对于任何返回 additionalContext的命令钩子，请在处理程序上设置 additionalContextLimit 来自定义近似 token 阈值：

{
  "type": "command",
  "command": "python3 ~/.codex/hooks/session_start.py",
  "additionalContextLimit": 5000
}

省略 additionalContextLimit 以使用默认 2500-token 阈值。使用正整数来选择不同的阈值，或使用 0 将处理程序的完整附加上下文直接传递给模型。 Codex 会独立评估每个匹配的处理程序。对于无法生成附加上下文的事件， Codex 会忽略 additionalContextLimit 并报告配置警告。

该设置仅适用于 additionalContext。工具反馈和继续提示会保留默认限制。

由于过大的输出可能会被写入磁盘，请避免在钩子输出中返回密钥或其他敏感数据。

钩子

SessionStart

对于此事件，matcher 会应用于 source。

除通用输入字段之外的字段：

字段	类型	含义
`source`	`string`	会话的启动方式： `startup`， `resume`， `clear`，或 `compact`

stdout 中的纯文本会作为额外的开发者上下文添加。

JSON 在 stdout 上支持通用输出字段以及这个钩子专用形状：

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Load the workspace conventions before editing."
  }
}

该 additionalContext 文本会作为额外的开发者上下文添加。

在 Codex 压缩根会话后， SessionStart 匹配 source: "compact" 的钩子会在下一次模型请求之前运行。这也适用于在一个回合中间发生自动压缩时： Codex 会将钩子的附加上下文传递给立即继续的请求，而不是等待之后的用户回合。如果钩子返回 continue: false， Codex 会结束该回合而不再发送另一次模型请求。

SessionEnd

SessionEnd 允许你在会话结束时运行命令，例如保存最终备注或清理文件。当你归档或删除仍打开的对话时、当 Codex 正常关闭时，或在对话已空闲且未在任何已连接客户端中打开 30 分钟后，它会为主线程运行。它不会为子代理运行。

切换离开某个对话或调用 thread/unsubscribe 不会立即结束会话，因此不会立即运行 SessionEnd。你的钩子在运行时仍可读取会话转录记录。

matcher 会筛选 reason 此事件。目前， reason 始终为 other。你可以省略 matcher 或使用 other 以在每个 SessionEnd 事件上运行。

除通用输入字段之外的字段：

字段	类型	含义
`reason`	`string`	会话结束的原因： `other`

例如，SessionEnd 命令会接收：

{
  "session_id": "thr_123",
  "transcript_path": "/workspace/.codex/rollout.jsonl",
  "cwd": "/workspace",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

SessionEnd 钩子是建议性的。它们的输出不会引导 Codex 或保持线程打开。如果命令超时或以错误退出， Codex 会将其报告为钩子失败。

SubagentStart

对于此事件，matcher 会应用于 agent_type。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。活动 Codex 回合 ID
`agent_id`	`string`	子代理的标识符
`agent_type`	`string`	子代理类型或配置文件
`permission_mode`	`string`	当前权限模式

stdout 中的纯文本会作为子智能体的额外开发者上下文添加。

JSON 在 stdout 上支持 systemMessage 以及这个钩子专用形状：

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Review the repository test conventions first."
  }
}

该 additionalContext 文本会作为额外的开发者上下文添加到子代理。 continue: false 会为兼容性而解析，但它不会阻止子代理启动。

PreToolUse

PreToolUse 可以拦截 Bash、通过 apply_patch执行的文件编辑、 MCP 工具调用，以及其他本地函数工具。请参阅工具覆盖范围了解支持的路径和例外情况。

matcher 会应用于 tool_name 和匹配器别名。对于通过 apply_patch执行的文件编辑， matcher 值可以使用 apply_patch， Edit，或 Write；钩子输入仍会报告 tool_name: "apply_patch"。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。活动 Codex 回合 ID
`tool_name`	`string`	规范钩子工具名称，例如 `Bash`， `apply_patch`，或类似 MCP 的名称 `mcp__fs__read`
`tool_use_id`	`string`	此调用的工具调用 ID
`tool_input`	`JSON value`	工具专用输入。 `Bash` 和 `apply_patch` 使用 `tool_input.command`。 MCP 和其他本地函数工具会发送它们的参数。

stdout 上的纯文本会被忽略。

JSON 在 stdout 上可以使用 systemMessage。要拒绝受支持的工具调用，请返回这个钩子专用形状：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

Codex 也接受以下较旧的块格式：

{
  "decision": "block",
  "reason": "Destructive command blocked by hook."
}

也可以使用退出代码 2，并将阻止原因写入 stderr。

要添加模型可见上下文而不阻塞，请返回 hookSpecificOutput.additionalContext：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "The pending command touches generated files."
  }
}

要重写受支持的工具调用而不阻塞，请返回 permissionDecision: "allow" 并带上 updatedInput：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "command": "echo rewritten"
    }
  }
}

对于 Bash 命令和 apply_patch， updatedInput 必须包含字符串 command 字段。对于 MCP 和其他本地函数工具， updatedInput 是替换参数对象。仅在 updatedInput 时返回 permissionDecision: "allow"；其他 updatedInput 形状会被报告为错误。

permissionDecision: "ask"、旧版 decision: "approve"、 continue: false、 stopReason，以及 suppressOutput 会被解析，但尚不支持。 Codex 会将该钩子运行标记为失败，报告错误，并继续工具调用。

PermissionRequest

PermissionRequest 会在 Codex 即将请求批准时运行，例如 shell 提权或托管网络批准。它可以允许请求、拒绝请求，或拒绝决定并让正常的批准提示继续。它不会为不需要批准的命令运行。

matcher 会应用于 tool_name 和匹配器别名。当前规范值包括 Bash， apply_patch，以及 MCP 工具名称，例如 mcp__server__tool； apply_patch 也会匹配 Edit 和 Write。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。活动 Codex 回合 ID
`tool_name`	`string`	规范钩子工具名称，例如 `Bash`， `apply_patch`，或类似 MCP 的名称 `mcp__fs__read`
`tool_input`	`JSON value`	工具专用输入。 `Bash` 和 `apply_patch` 使用 `tool_input.command` ，而 MCP 工具会发送所有参数。
`tool_input.description`	`string \| null`	人类可读的批准原因，当 Codex 有该原因时

stdout 上的纯文本会被忽略。

某些工具输入可能包含人类可读的描述，但不要依赖每个工具都有 tool_input.description 字段。

要批准请求，请返回：

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow"
    }
  }
}

要拒绝请求，请返回：

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Blocked by repository policy."
    }
  }
}

如果多个匹配钩子返回决定，任何 deny 都会优先。否则， allow 会让请求继续，而不显示批准提示。如果没有匹配的钩子作出决定， Codex 会使用正常的批准流程。

不要为 updatedInput、 updatedPermissions，或 interrupt 返回 PermissionRequest；这些字段预留给未来行为，目前会失败并关闭。。

PostToolUse

PostToolUse 会在受支持的工具产生输出后运行，包括 Bash、 apply_patch、 MCP 工具调用，以及其他本地函数工具。对于 Bash，它也会在命令以非零状态退出后运行。它无法撤销已经运行的工具所产生的副作用。请参阅工具覆盖范围了解支持的路径和例外情况。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。活动 Codex 回合 ID
`tool_name`	`string`	规范钩子工具名称，例如 `Bash`， `apply_patch`，或类似 MCP 的名称 `mcp__fs__read`
`tool_use_id`	`string`	此调用的工具调用 ID
`tool_input`	`JSON value`	工具专用输入。 `Bash` 和 `apply_patch` 使用 `tool_input.command`。 MCP 和其他本地函数工具会发送它们的参数。
`tool_response`	`JSON value`	工具专用输出。 MCP 工具会发送 MCP 调用结果。其他本地函数工具通常会发送面向模型的输出。

stdout 上的纯文本会被忽略。

JSON 在 stdout 上可以使用 systemMessage 以及这个钩子专用形状：

{
  "decision": "block",
  "reason": "The Bash output needs review before continuing.",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "The command updated generated files."
  }
}

该 additionalContext 文本会作为额外的开发者上下文添加。

对于此事件， decision: "block" 不会撤销已完成的 Bash 命令。相反， Codex 会记录反馈，用该反馈替换工具结果，并从钩子提供的消息继续模型。

也可以使用退出代码 2，并将反馈原因写入 stderr。

要在命令已经运行后停止原始工具结果的正常处理，请返回 continue: false。 Codex 会将工具结果替换为你的反馈或停止文本，并从那里继续。

updatedMCPToolOutput 和 suppressOutput 会被解析，但尚不支持。 Codex 会将钩子运行标记为失败，报告错误，并继续正常处理工具结果。

来自代码模式的工具调用

当模型使用代码模式调用来自 JavaScript的工具时，钩子决定会应用于该嵌套调用。 PreToolUse 可以在工具运行前停止它，或重写其输入。阻塞型 PostToolUse 无法撤销工具的副作用，但它可以阻止原始结果到达正在运行的脚本。

钩子结果	代码模式看到的内容
`PreToolUse` 阻塞	工具 Promise 会在工具运行前拒绝。
`PreToolUse` 返回 `updatedInput`	工具会使用重写后的输入运行，并且 Promise 会以该结果完成。
`PostToolUse` 返回 `decision: "block"` 或以代码 `2`	退出，工具会先运行，然后 Promise 会以钩子原因为由拒绝。
`PostToolUse` 返回 `continue: false`	Codex 会将钩子反馈用于模型可见结果，但不会拒绝嵌套工具 Promise。

PreCompact

PreCompact 会在 Codex 压缩聊天之前运行。 matcher 会应用到 trigger，其值为 manual 和 auto。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。活动 Codex 回合 ID
`trigger`	`string`	触发压缩的原因： `manual` 或 `auto`

stdout 上的纯文本会被忽略。

JSON 在 stdout 上支持通用输出字段。如果匹配的 PreCompact 钩子返回 continue: false， Codex 会在压缩前停止。

PostCompact

PostCompact 会在 Codex 压缩聊天后运行。 matcher 会应用到 trigger，其值为 manual 和 auto。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。活动 Codex 回合 ID
`trigger`	`string`	触发压缩的原因： `manual` 或 `auto`

stdout 上的纯文本会被忽略。

JSON 在 stdout 支持通用输出字段。如果某个匹配的 PostCompact 钩子返回 continue: false， Codex 会在压缩后停止。

UserPromptSubmit

matcher 当前不会用于此事件。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。当前 Codex 轮次 ID
`prompt`	`string`	即将发送的用户提示

stdout 中的纯文本会作为额外的开发者上下文添加。

JSON 在 stdout 支持通用输出字段和此钩子特有的形状：

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Ask for a clearer reproduction before editing files."
  }
}

该 additionalContext 文本会作为额外的开发者上下文添加。

要阻止提示，请返回：

{
  "decision": "block",
  "reason": "Ask for confirmation before doing that."
}

也可以使用退出代码 2，并将阻止原因写入 stderr。

SubagentStop

对于此事件，matcher 会应用于 agent_type。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。当前 Codex 轮次 ID
`agent_id`	`string`	子代理的标识符
`agent_type`	`string`	子代理类型或配置文件
`agent_transcript_path`	`string \| null`	子代理转录文件的路径（如果有）
`stop_hook_active`	`boolean`	此子代理是否已经继续
`last_assistant_message`	`string \| null`	最新的子代理助手消息（如果可用）

SubagentStop 期望 JSON 在 stdout 退出时 0。纯文本输出对此事件无效。

JSON 在 stdout 支持通用输出字段。若要请求 Codex 继续子代理流程，请返回：

{
  "decision": "block",
  "reason": "Run one more focused pass inside the subagent."
}

也可以使用退出代码 2，并将继续原因写入 stderr。

如果任何匹配的 SubagentStop 钩子返回 continue: false，则它优先于其他匹配 SubagentStop 钩子的继续决策。

Stop

matcher 当前不会用于此事件。

除通用输入字段之外的字段：

字段	类型	含义
`turn_id`	`string`	Codex-specific 扩展。当前 Codex 轮次 ID
`stop_hook_active`	`boolean`	此轮次是否已由 `Stop`
`last_assistant_message`	`string \| null`	最新的助手消息文本（如果可用）

Stop 期望 JSON 在 stdout 退出时 0。纯文本输出无效对此事件。

JSON 在 stdout 支持通用输出字段。若要让 Codex 继续运行，请返回：

{
  "decision": "block",
  "reason": "Run one more pass over the failing tests."
}

也可以使用退出代码 2，并将继续原因写入 stderr。

对于此事件， decision: "block" 不会拒绝该轮次。相反，它会告诉 Codex 继续，并自动创建一个新的继续提示，该提示会作为新的用户提示，使用你的 reason 作为该提示文本。

如果任何匹配的 Stop 钩子返回 continue: false，则它优先于其他匹配 Stop 钩子的继续决策。

Schemas

链接的 main 分支架构可能包含当前版本中没有的钩子字段。请将本页作为发布行为参考。

如果你需要确切的当前传输格式，请参阅 Codex GitHub 仓库中的生成架构。

纯文本别名

字符串 | null

钩子

Codex 查找钩子的位置

审查并信任钩子

配置结构

关闭钩子

来自 requirements.toml 的托管钩子

插件捆绑的钩子

匹配器模式

工具覆盖范围

通用输入字段

通用输出字段

较大的钩子输出

钩子

SessionStart

SessionEnd

SubagentStart

PreToolUse

PermissionRequest

PostToolUse

来自代码模式的工具调用

PreCompact

PostCompact

UserPromptSubmit

SubagentStop

Stop

Schemas

纯文本别名

来自 `requirements.toml` 的托管钩子