codex-hooks-doctor

English | 简体中文

找出你的 Codex Hooks 为何没有触发。

codex-hooks-doctor 可以发现你的 Codex Hook 配置、识别常见错误，并让你无需启动 Codex 会话即可测试单个 Hook。

npx codex-hooks-doctor

codex-hooks-doctor 是一个独立的社区项目，并非 OpenAI 官方产品。

功能简介

v0.2 CLI 专注于回答两个问题：

• 发现了哪些用户级和仓库级 Hook，其中有哪些明显问题？
• 在收到具有代表性的类 Codex 载荷时，指定的命令 Hook 是否按预期工作？

它绝不会调用 LLM、通过网络发送 Hook 内容、修改 Codex 配置，也不会声称某个 Hook 是安全的。

快速开始

扫描但不执行 Hook：

npx codex-hooks-doctor

显式测试一个已发现的 Hook：

npx codex-hooks-doctor test --event PreToolUse --hook project:PreToolUse:0:0

两种工作流都支持使用 --json 输出机器可读的结果。

扫描

codex-hooks-doctor 与 codex-hooks-doctor scan 等效。扫描会发现并解析 Hook，但绝不会 执行其中的命令。

codex-hooks-doctor v0.2.0

Scanning:
  user config (/Users/alice)
  /Users/alice/work/demo

Found 2 hook handlers in 1 source

✓ /Users/alice/work/demo/.codex/hooks.json
  PreToolUse         project:PreToolUse:0:0
  Stop               project:Stop:0:0

Findings

CHD007  WARNING
Stop has a matcher, but Codex currently ignores matchers for Stop.

CHD013  INFO
Project hooks require project-layer trust, and every non-managed command hook requires
exact hook-definition review in Codex.
Doctor does not infer persisted hook trust in v0.2.

0 errors, 1 warning, 1 info

Scope: user + project hook sources.
Managed, plugin, profile, and runtime-injected hooks are not modeled in v0.2.

仅有警告不会导致扫描失败。退出码 0 表示命令成功完成且没有错误级别的问题，1 表示用户配置或被测试的 Hook 存在错误级别的失败，2 表示 CLI 用法错误或内部失败。

测试 Hook

测试在设计上会产生副作用。该命令只执行一个明确选定的 Hook，将紧凑 JSON 加换行符 写入 stdin，并捕获 stdout、stderr、退出码、执行时长和超时状态。

npx codex-hooks-doctor test \
  --event PreToolUse \
  --hook project:PreToolUse:0:0

常用选项：

--cwd <path>          session working directory
--payload <file>      custom event payload JSON
--timeout <seconds>   local execution timeout
--ignore-matcher      run despite a non-matching or uncertain matcher result
--json                machine-readable output

如果省略 --hook，只有在该事件恰好存在一个可执行 Hook 时，CLI 才会运行。它绝不会 自动运行多个 Hook。有效的 Hook 决策——包括 PreToolUse deny/block、Stop continuation、PostToolUse feedback 或 PermissionRequest decision——会被报告为协议 结果，而不是进程失败。

三个新事件使用相同的命令形式：

npx codex-hooks-doctor test --event PostToolUse --hook project:PostToolUse:0:0
npx codex-hooks-doctor test --event UserPromptSubmit --hook project:UserPromptSubmit:0:0
npx codex-hooks-doctor test --event PermissionRequest --hook project:PermissionRequest:0:0

PostToolUse feedback 会被明确报告为发生在工具已经执行之后。空的 PermissionRequest 结果表示未作决定，Codex 的正常批准流程会继续；它并不表示 allow。

测试工具保留 shell 命令语义，因为真实的 Hook 命令可能使用 $(git rev-parse ...) 之类的展开。它只近似模拟 Codex 客户端的进程环境；不同客户端和操作系统上的 shell 及环境行为可能有所不同。

v0.2 检查内容

稳定诊断代码 CHD001–CHD013 涵盖：

• 格式错误的 JSON 或 TOML；
• 建模配置层中被禁用的 Hook，以及已弃用的 features.codex_hooks 别名；
• 同一配置层中的 hooks.json 与内联 [hooks] 合并；
• 能够解析但不会执行的 prompt/agent 处理器，以及不会生效的异步 SessionEnd 设置；
• 被忽略的 matcher 和常见的 Rust 正则表达式不兼容结构；
• 空命令、不可靠的相对 .codex/... 路径和无效超时；
• 项目配置层信任和非托管 Hook 精确定义审查要求。

matcher 模拟特意采用保守策略，并非完整的 Rust 正则表达式引擎。它有三种结果：匹配、 不匹配和不确定。不确定的 matcher 不会被当作无效表达式或确定不匹配。doctor 默认不会 执行它；仅在你确实希望绕过 matcher 门控时才传入 --ignore-matcher。

对于工具事件，matcher 模拟包含文档中说明的别名。具体来说，apply_patch 载荷可以匹配 apply_patch、Edit 或 Write。Codex 当前会忽略 UserPromptSubmit 和 Stop 的 matcher，因此这些 matcher 不会阻止测试执行。

支持的事件

v0.2 支持执行测试以下事件：

• SessionStart
• PreToolUse
• Stop
• PostToolUse
• UserPromptSubmit
• PermissionRequest

其他当前事件可以被发现和显示。选择其中任一事件时，工具会给出明确的 v0.2 不支持 结果，而不会运行该 Hook。

每个受支持事件都有固定版本的官方输入/输出 schema 和代表性载荷。你可以通过 --payload 提供自定义载荷；无效载荷会在 matcher 评估或 Hook 执行前被拒绝。

发现范围

扫描器会读取：

• ~/.codex/hooks.json
• ~/.codex/config.toml 中的内联 Hook
• 从仓库根目录到 cwd 各层级的 .codex/hooks.json 和内联 .codex/config.toml

仓库根目录通过 git rev-parse --show-toplevel 解析；如果不可用，则只使用 cwd，并报告 这一限制。v0.2 不建模 managed、plugin、profile、system/MDM/cloud、session 和 runtime-injected Hook。工具不会猜测可信状态；请在 Codex 中使用 /hooks 检查和审查。

安全说明

scan 绝不会执行 Hook。test 会执行一个由用户选择的命令，并可能产生该命令通常会 产生的任何副作用。请先查看打印出的命令。Hook 的 stdout/stderr 会原样显示，其中本身 可能含有敏感数据；doctor 不会打印环境变量，也不会添加遥测。

限制

• 该工具建模用户级和项目级来源，而不是完整的 Codex 配置解析。
• 目前只执行命令处理器；doctor 会报告已解析的 prompt 和 agent 处理器。
• 支持异步命令 Hook，但成功返回的后台控制意图不能阻止、批准、重写、替换或以其他 方式同步控制触发操作。受支持的信息性输出会被保留。异步非零退出仍是 Hook/进程失败， 不会被转换为成功但不生效的控制决策。
• 本地 shell/环境行为可能与特定 Codex 客户端不同。
• 内置 schema 是固定版本快照，不会在运行时获取。
• Rust 正则表达式兼容性检查采取保守策略，并不完整。
• CI 已在 Node.js 20 和 22 上通过 Ubuntu、macOS 和 Windows 测试。

开发

需要 Node.js 20 或更高版本。

npm install
npm test
npm run typecheck
npm run build
npm run schemas:verify

schemas:verify 无需网络即可检查已提交的 schema manifest、内置文件集和来源信息。 维护者可以运行 npm run schemas:check，将内置 schema 与固定的准确上游修订进行语义 比较。若要有意更新快照，请运行 npm run schemas:update -- <40-character-openai/codex-commit-sha>；工具会拒绝 main、 标签、分支和短 SHA 等浮动引用。

上游兼容性

选定的官方生成 schema 固定在 src/schemas/generated 下，其来源信息记录在 src/schemas/UPSTREAM.md 中。当前文档与 schema 的差异记录在 UPSTREAM_NOTES.md。 由于 main 分支的 schema 可能包含尚未进入已发布客户端的行为，因此以官方 Hooks 文档作为发布行为的参考。 正常 CLI 使用、安装和测试不会获取 schema，也不要求访问 GitHub。