钩子

Hooks 是 Codex 的一个扩展框架。它们允许你将自定义脚本注入到智能体循环（agentic loop）中，从而实现以下功能：

• 将对话发送到自定义的日志/分析引擎
• 扫描团队的提示词，阻止意外粘贴 API 密钥
• 总结对话以自动创建持久记忆
• 在对话轮次停止时运行自定义验证检查，强制执行标准
• 在特定目录下自定义提示词

Hooks 默认处于启用状态。如果你需要在以下环境中将其关闭 config.toml，请设置：

[features]
hooks = false

使用 hooks 作为规范的功能键。 codex_hooks 仍然可用作已弃用的别名。

管理员可以在以下环境中以相同方式强制禁用 Hooks requirements.toml with [features].hooks = false.

需要注意的运行时行为：

• 来自多个文件的匹配 Hooks 都会运行。
• 同一事件的多个匹配命令 Hooks 会并发启动，因此一个 Hook 无法阻止另一个匹配 Hook 的启动。
• 非托管的命令 Hooks 在运行前必须经过审查并受到信任。
• PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStop，且 Stop 在轮次（turn）范围内运行。 SessionStart and SubagentStart 在线程（thread）或子智能体启动（subagent-start）范围内运行。

Codex 在哪里查找 Hooks

Codex 会从活动配置层（active config layers）中通过以下两种形式发现 Hooks：

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

已安装的插件还可以通过其插件清单或默认配置来捆绑生命周期配置 hooks/hooks.json 文件中。请参阅 构建插件 以了解插件打包规则。

实际上，最常用的四个位置是：

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

如果存在多个钩子来源，Codex 会加载所有匹配的钩子。高优先级的配置层不会替换低优先级的钩子。如果单个层同时包含 hooks.json and inline [hooks]，Codex 会将它们合并并在启动时发出警告。建议每个层只使用一种表示形式。

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

项目本地 Hook 仅在项目 .codex/ 层是受信任的。在不受信任的项目中，Codex 仍会从其各自的活动配置层加载用户和系统钩子。

审查并信任钩子

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

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

来自系统、MDM、云端或 requirements.toml 来源的托管 hook 会被标记为托管状态，默认受策略信任，并且无法在用户 hook 浏览器中禁用。

对于已在 Codex 外部审查过 hook 来源的一次性自动化，请传入 --dangerously-bypass-hook-trust 以运行已启用的 hook，而无需在此次调用中要求持久的 hook 信任。

配置结构

Hook 按三个层级进行组织：

• 一个 hook 事件，例如 PreToolUse, PostToolUse, PreCompact, SubagentStart, or Stop
• 决定该事件何时匹配的匹配器组
• 当匹配器组匹配时运行的一个或多个 hook 处理程序

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes"
          }
        ]
      }
    ],
    "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
          }
        ]
      }
    ]
  }
}

Notes:

• timeout 以秒为单位。
• If timeout 被省略时，Codex 将使用 600 seconds.
• statusMessage 是可选的。
• commandWindows 是一个仅限 Windows 的可选命令覆盖。在 TOML 中，使用 command_windows or commandWindows.
• async 会被解析，但目前尚不支持异步命令 hook。Codex 会跳过具有以下设置的处理程序： async: true.
• 仅限 type: "command" 处理程序在今天运行。 prompt and agent 处理程序已被解析但被跳过。
• 命令运行时使用会话 cwd 作为其工作目录。
• 对于仓库本地钩子，建议从 git 根目录解析，而不是使用相对路径，例如 .codex/hooks/...。Codex 可能从子目录启动，而基于 git 根目录的路径能保持钩子位置的稳定。

等效的内联 TOML 在 config.toml:

[[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"

托管钩子来自 requirements.toml

企业管理需求也可以在内联定义钩子，位于 [hooks]。当管理员希望强制执行钩子配置，同时通过 MDM 或其他设备管理系统交付实际脚本时，这非常有用。若要为在本地禁用钩子的用户强制实施托管钩子，请固定 [features].hooks = true in requirements.toml 以及 [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；您的企业工具必须单独安装和更新它们。
• 托管钩子命令应使用所配置的托管目录下的脚本绝对路径。
• allow_managed_hooks_only = true 将跳过来自用户、项目、会话和插件源的钩子，但依然会从以下位置加载托管钩子 requirements.toml 和其他托管配置层。

插件捆绑的钩子

当插件启用时，Codex 可以从该插件加载生命周期钩子，并与用户、项目和托管钩子同时使用。

默认情况下，Codex 会在 hooks/hooks.json 中查找，路径位于插件根目录内。插件清单可以通过在 hooks 条目来覆盖该默认设置，该条目位于 .codex-plugin/plugin.json。manifest 条目可以是 ./为前缀的路径、以 ./为前缀的路径数组、内联钩子对象或内联钩子对象数组。

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

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

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

• PLUGIN_ROOT 是一个 Codex 特定的扩展，指向已安装的插件根目录。
• PLUGIN_DATA 是一个 Codex 特定的扩展，指向插件的可写入数据目录。
• Codex 还会设置 CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA 以兼容现有的插件钩子。

插件钩子使用与其他钩子相同的事件模式。安装或启用插件并不会自动信任其钩子；Codex 会跳过插件捆绑的钩子，直到你审查并信任当前的钩子定义。

匹配器模式

The matcher 字段是一个正则表达式字符串，用于过滤钩子的触发时机。请使用 "*", ""，或省略 matcher 以匹配受支持事件的每一次出现。

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

*对于 apply_patch, matcher 的值也可以使用 Edit or Write.

Examples:

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

通用输入字段

每个命令钩子会在其标准输入上接收一个 JSON 对象，位于 stdin.

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

回合（Turn）范围的钩子列表 turn_id 作为 Codex 特定的扩展字段，列在它们各自的事件专属表格中。

SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, SubagentStart, SubagentStop，且 Stop 还包括 permission_mode，它会将当前的权限模式描述为 default, acceptEdits, plan, dontAsk, or bypassPermissions.

transcript_path 指向对话记录以方便查阅，但记录格式并不是一个稳定的钩子接口，未来可能会随时间发生变化。

如果您需要完整的传输格式，请参见 模式.

通用输出字段

SessionStart, PreCompact, PostCompact, UserPromptSubmit, SubagentStop，且 Stop 支持这些共享的 JSON 字段。 SubagentStart 在以下情况接受相同的结构 systemMessage and hook-specific context, but continue: false 不会停止子代理：

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

退出 0 且无输出将被视为成功，Codex 将继续执行。

PreToolUse and PermissionRequest 支持 systemMessage，但是 continue, stopReason，且 suppressOutput 目前在那些事件中尚不受支持。如果 PreToolUse 钩子返回了其中一个不受支持的字段，Codex 会将该次钩子运行标记为失败，报告错误，并继续执行工具调用。

PostToolUse 支持 systemMessage, continue: false，且 stopReason. suppressOutput 已被解析，但在该事件中目前尚不受支持。

钩子

SessionStart

matcher 应用于 source for this event.

的字段（除已有字段外） 通用输入字段:

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

上的 JSON stdout 支持 通用输出字段 and this hook-specific shape:

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

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

SubagentStart

matcher 应用于 agent_type for this event.

的字段（除已有字段外） 通用输入字段:

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

上的 JSON stdout 支持 systemMessage and this hook-specific shape:

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

该 additionalContext 文本作为子智能体的额外开发者上下文添加。 continue: false 会出于兼容性进行解析，但不会阻止子智能体启动。

PreToolUse

PreToolUse 可以拦截通过以下方式执行的 Bash 和文件编辑： apply_patch，以及 MCP 工具调用。它仍然是一个防护栏，而不是一个完整的强制执行边界，因为 Codex 通常可以通过另一个受支持的工具路径执行等效的工作。

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

的字段（除已有字段外） 通用输入字段:

上的纯文本 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" with updatedInput:

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

For Bash commands and 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 and Write.

的字段（除已有字段外） 通用输入字段:

上的纯文本 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, or interrupt for PermissionRequest；这些字段为未来的行为保留，目前会导致安全关闭。

PostToolUse

PostToolUse 在支持的工具有输出后运行，包括 Bash、 apply_patch, 和 MCP 工具调用。对于 Bash，它也会在命令以非零状态退出后运行。它无法撤销已经运行的工具所产生的副作用。

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

的字段（除已有字段外） 通用输入字段:

上的纯文本 stdout 被忽略。

上的 JSON stdout 可以使用 systemMessage and this hook-specific shape:

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

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

For this event, decision: "block" 不会撤销已完成的 Bash 命令。相反，Codex 会记录反馈，用该反馈替换工具结果，并从 hook 提供的消息继续运行模型。

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

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

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

PreCompact

PreCompact 在 Codex 压缩对话之前运行。 matcher 应用于 trigger, 其值为 manual and auto.

的字段（除已有字段外） 通用输入字段:

上的纯文本 stdout 被忽略。

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

PostCompact

PostCompact 在 Codex 压缩对话之后运行。 matcher 应用于 trigger, 其值为 manual and auto.

的字段（除已有字段外） 通用输入字段:

上的纯文本 stdout 被忽略。

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

用户提示提交

matcher 当前未用于此事件。

的字段（除已有字段外） 通用输入字段:

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

上的 JSON stdout 支持 通用输出字段 and this hook-specific shape:

{
  "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 for this event.

的字段（除已有字段外） 通用输入字段:

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

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

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

你也可以使用退出代码 2 并将继续的原因写入 stderr.

如果任何匹配的 SubagentStop 钩子返回 continue: false，它将优先于其他匹配项产生的继续决策 SubagentStop hooks.

停止

matcher 当前未用于此事件。

的字段（除已有字段外） 通用输入字段:

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

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

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

你也可以使用退出代码 2 并将继续的原因写入 stderr.

For this event, decision: "block" 不会拒绝该轮次。相反，它会告诉 Codex 继续运行，并自动创建一个新的继续提示，该提示将作为新的用户提示，使用您的 reason 作为该提示文本。

如果任何匹配的 Stop 钩子返回 continue: false，它将优先于其他匹配项产生的继续决策 Stop hooks.

模式

如果您需要确切的当前传输格式，请参阅 Codex GitHub 存储库.