Hook 在各工具中的定义
Codex 的文档将 hooks 描述为“Codex 的可扩展性框架。它们允许您在智能体循环期间运行脚本或 MCP 工具”。其示例列表包括“自动总结聊天以创建持久记忆”和“在聊天轮次停止时运行自定义验证检查,强制执行标准”。
Claude Code 的文档称 hooks “定义在 JSON 设置文件中”,并按事件、匹配器组和处理器进行组织。处理器可以是 shell 命令、HTTP 端点、MCP 工具、提示词或智能体。
Codex 支持的处理器类型较少。其文档称:“支持 command 和 mcp_tool 处理器。prompt 和 agent 处理器会被解析但跳过。”由于 Claude Code 支持这两者,因此在 Codex 中实际运行的每个处理器在 Claude Code 中都有匹配的类型。
Hooks 的存放位置
在 Codex 中, hooks 存放在 hooks.json 文件中或内联在 config.toml 中。文档列出了 hooks.json 的位置:
- 系统级:macOS 和 Linux 上的
/etc/codex/hooks.json。 - 用户级:
$CODEX_HOME/hooks.json,当未设置CODEX_HOME时为~/.codex/hooks.json。 - 受信任项目:
.codex/hooks.json。
Codex 还会加载与已启用插件捆绑的 hooks。当某一层级同时使用这两个文件时,文档称“Codex 会同时加载两者并在启动时发出警告。建议每层仅使用一种格式”。
在 Claude Code 中, hooks 存放在设置文件中。文档的表格列出了主要位置:
~/.claude/settings.json适用于您的所有项目。.claude/settings.json适用于单个项目,且“可以提交到代码库”。.claude/settings.local.json适用于单个项目,保持本地化。- 托管策略设置、插件以及技能或子智能体的前置元数据 (frontmatter)。
因此,Codex 用户级的 hooks.json 最接近地映射到 ~/.claude/settings.json,而项目的 .codex/hooks.json 则映射到 .claude/settings.json 中的顶级 hooks 键下。
保持不变的内容
有几个部分无需转换。
结构。 事件名称、匹配器组以及每个组的处理器列表。
共享的事件名称。 SessionStart、SessionEnd、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SubagentStart、SubagentStop 和 Stop 均出现在两个工具的参考文档中。
SessionStart 来源。 Codex 列出了 startup、resume、clear、compact 和 fork。Claude Code 的 SessionStart 匹配器表列出了相同的五个值。
通用输入字段。 两者都通过标准输入 (stdin) 发送 JSON,包含 session_id、transcript_path、cwd、hook_event_name 和 permission_mode。
退出代码 2。 在 Codex 中,多个事件允许您“使用退出代码 2 并将阻塞原因写入 stderr”。Claude Code 同样在支持的事件上将退出代码 2 视为阻塞信号,并记录了其在每个事件中的行为。
默认超时。 Codex 对大多数 hooks 使用 600 秒。Claude Code 将 600 列为命令 hooks 的默认值。
需要转换的内容
匹配器 (Matchers)。 两者都使用匹配器按工具名称或启动来源进行过滤,但评估方式不同。Codex 称其匹配器“是一个正则表达式字符串”。Claude Code 将仅由字母、数字和少数分隔符组成的匹配器视为精确名称,而将其他任何内容视为未锚定的 JavaScript 正则表达式。像 ^apply_patch$ 这样的 Codex 匹配器在 Claude Code 中仍保持为正则表达式,但其中的工具名称需要更改。
工具名称。 Codex 的 shell 工具匹配为 Bash,这也是 Claude Code 的名称。文件编辑则有所不同。在 Codex 中,apply_patch 可以匹配为 apply_patch、Edit 或 Write。在 Claude Code 中,编辑工具通过 Edit 和 Write 等名称进行匹配。如果您的 Codex hooks 已经使用 Edit|Write,该匹配器可以沿用。如果使用的是 apply_patch,请更改它。
MCP 工具名称。 两者在示例中都使用 mcp__server__tool 模式,因此 MCP 匹配器可以沿用。请检查服务器在两个工具中是否具有相同的名称。
脚本路径。 Codex 的示例通过 Git 引用项目脚本,路径位于 .codex/hooks/ 下。Claude Code 为此提供了一个占位符:${CLAUDE_PROJECT_DIR},“会话启动的项目根目录”。如果您将脚本移动到 .claude/hooks/,请同时更新路径。
模型字段。 Codex 将 model 列为一个通用的输入字段,这是一个“Codex 特有的扩展”。Claude Code 称:“只有 SessionStart hooks 可以接收 model 字段,且 Claude Code 并不总是包含它。”在每个事件上读取模型的 Codex 脚本需要一个回退方案。
轮次 ID (Turn IDs)。 Codex 为轮次作用域的 hooks 添加了 turn_id。Claude Code 的通用字段包括 prompt_id,用于标识正在处理的用户提示词。以轮次 ID 为键的日志脚本需要调整。
上下文限制。 Codex 的 additionalContextLimit 字段控制在 Codex 将全文保存到磁盘之前,hook 可以发送多少上下文。Claude Code 的处理器字段表没有列出该字段,因此在复制处理器时请将其删除。
仅存在于一侧的事件
Codex 列出了三个 Claude Code 的 hook 参考中未以相同名称包含的事件:PreModelRequest、PostModelRequest 和 Interrupt。Codex 为“每次模型请求尝试”运行前两个事件,并在您中断活动轮次时运行 Interrupt。
如果您依赖这些事件,请寻找最接近的 Claude Code 事件,或接受该行为无法迁移的事实。相应地,Claude Code 拥有许多 Codex 没有的事件,例如 PostToolUseFailure、Notification、FileChanged 和 PreModelSwitch。迁移是检查其中之一是否能更好地完成工作的良机。
各侧信任机制的工作原理
Codex 对 hooks 进行单独信任。其文档称:“在非托管 hook 运行之前,Codex 要求您审查并信任确切的 hook 定义。Codex 根据 hook 的当前哈希记录信任,因此新的或更改的 hooks 会被标记为待审查并跳过,直到被信任。”
Claude Code 则检查工作区信任。在交互式会话中,它会“扣留来自每个设置文件(包括您自己的 ~/.claude/settings.json)的 hooks,直到您接受该文件夹的工作区信任对话框”。在 -p 或 SDK 会话中,它“将文件夹视为受信任”。
Claude Code 的 /hooks 菜单是一个只读浏览器,显示每个 hook 及其来源。迁移后使用它来确认每个 hook 是否都出现在预期位置。
插件、托管和禁用的 Hooks
并非每个 hook 都由您负责移动。
插件 hooks 随其插件一起移动。Codex 称启用的插件可以“通过其清单或默认情况下插件根目录中的 hooks/hooks.json”提供 hooks。Claude Code 在插件内部使用相同的文件名,其文档称“当插件启用时,其 hooks 会与您的用户和项目 hooks 合并”。如果 hook 来自插件,请安装该插件的 Claude Code 版本,而不是复制 hook。
托管 hooks 属于您的管理员。Codex 将来自系统、MDM、云端或 requirements.toml 来源的 hooks 标记为受策略托管和信任。Claude Code 拥有托管策略设置,以及一个 allowManagedHooksOnly 设置,用于阻止用户、项目、本地和插件 hooks。在自行重新创建托管 hook 之前,请咨询您的管理员。
关闭 hooks 的方式不同。在 Codex 中,hooks 默认启用,并通过 config.toml 中的功能标志关闭。在 Claude Code 中,文档记录的开关是设置文件中的 disableAllHooks,且它无法禁用来自托管设置之外的托管 hooks。
移动加载上下文的 Hooks
加载上下文的 SessionStart hooks 是最值得正确处理的,因为它们决定了智能体从第一轮开始所了解的信息。
在 Codex 中,“标准输出 (stdout) 上的纯文本被添加为额外的开发者上下文”,JSON 格式的 additionalContext 字段也以同样的方式工作。Codex 还在压缩会话后运行匹配 compact 的 SessionStart hooks,以便在摘要后恢复上下文。
Claude Code 的工作方式类似。其文档称,对于 SessionStart,“Claude Code 将纯文本标准输出添加为 Claude 可以看到并采取行动的上下文”。其 compact 来源在“自动或手动压缩”后触发。
Claude Code 针对哪些内容适合放在 hook 中提供了建议。其 SessionStart 部分称该事件“对于加载开发上下文(如现有问题或代码库的近期更改)非常有用”,然后提到:“对于不需要脚本的静态上下文,请使用 CLAUDE.md”。
因此,如果一个 Codex hook 只是每次打印相同的约定,那么迁移就是一个将该文本移动到 CLAUDE.md 并保留 hook 用于处理动态上下文的机会。我们在 Claude Code hooks 指南中介绍了哪些 Claude Code hooks 可以添加上下文,以及何时 CLAUDE.md 是更好的选择。
人们首先尝试的操作
期望 /import codex 带来 hooks。 其文档列表涵盖了指令文件、MCP 服务器、命令、子智能体和技能。
将 hooks.json 复制到 .claude/ 中。 Claude Code 文档记录的位置是设置文件、插件以及技能或子智能体的前置元数据。
在匹配器中保留 apply_patch。 Claude Code 的编辑工具使用不同的名称。
在每个事件上读取 model。 在 Claude Code 中,只有 SessionStart 可以接收它。
在 hook 中保留静态约定。 Claude Code 建议将静态上下文放在 CLAUDE.md 中。
手动迁移步骤
第 1 步:列出您的 Codex hooks
在 Codex CLI 中打开 /hooks,记录每个 hook 的来源、事件、匹配器和命令。
第 2 步:选择 Claude Code 设置文件
个人 hooks 使用 ~/.claude/settings.json,共享项目 hooks 使用 .claude/settings.json。
第 3 步:复制结构
在 hooks 键下重新创建每个事件和匹配器组,将任何 TOML 格式的 hooks 转换为 JSON。
第 4 步:转换匹配器和路径
替换 apply_patch,检查正则表达式匹配器,并将脚本路径指向 ${CLAUDE_PROJECT_DIR}。
第 5 步:调整读取 Codex 专用字段的脚本
为 model 和 turn_id 添加回退方案,并移除 additionalContextLimit。
第 6 步:将静态上下文移动到 CLAUDE.md
保留 hooks 用于处理变化的上下文。将固定的约定放入 CLAUDE.md。
第 7 步:信任文件夹并验证
接受工作区信任对话框,然后检查 /hooks 并触发每个事件一次。
更好的方法:将 hooks 执行的内容集中管理
Hooks 强制执行规则并加载上下文。它们背后的原因(例如为什么要阻止某个命令、某项检查执行的是哪项策略,或者会话笔记应该包含什么)都是项目上下文。当 hooks 在工具之间移动时,脚本随之迁移,但背后的推理可能只存在于某人的记忆中。
MemoryLake 是此类项目上下文(如策略、约定和检查背后的原因)的记忆层,集中存储在您维护的一个地方,并可供您连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。
您可以用自己的语言亲自编写条目。不会从您的 hooks.json 文件、设置文件、hook 脚本、Codex 或 Claude Code 会话或任何供应商的存储中读取、写入或删除任何内容。Hooks 按照 OpenAI 和 Anthropic 描述的方式工作。
第 1 步:创建 API 密钥
登录并从控制面板生成密钥。像对待其他凭据一样,将其存储在代码库之外。

第 2 步:上传您的第一批记忆
从您在手动迁移第 1 步中列出的 hooks 开始。对于每一个 hook,写下它强制执行的内容以及原因。每个条目对应一个 hook。

第 3 步:连接您的 AI 和智能体
连接 Claude Code、Codex 以及您使用的其他助手。无论哪个工具运行 hook,每个助手都可以借鉴相同的原因。

这在实践中改变了什么
第一个区别是转换更简单。当 hook 的目的被记录下来时,即使名称不同,您也可以选择正确的 Claude Code 事件。
第二个区别是减少了重复。不改变的上下文只需放入 CLAUDE.md 一次,而不是放入一个在每个会话中打印它的脚本中。
第三个区别是跨工具的一致性。相同的策略和原因在 Claude Code 和 Codex 中均可使用。
将 Codex Hooks 迁移到 Claude Code 的最佳实践
先盘点。 在 Codex 中使用 /hooks 查看每个来源。
有意识地映射文件。 用户 hooks 映射到 ~/.claude/settings.json,项目 hooks 映射到 .claude/settings.json。
转换工具名称。 apply_patch 变为 Edit 或 Write。
脚本使用 ${CLAUDE_PROJECT_DIR}。 它指向会话启动的项目根目录。
检查 Codex 专用事件。 PreModelRequest、PostModelRequest 和 Interrupt 需要应对方案。
将静态文本移动到 CLAUDE.md。 保留 hooks 用于处理变化的上下文。
在脚本运行前检查 .claude/。 -p 会话将文件夹视为受信任。
结论
Claude Code 的 /import codex 导入指令文件、MCP 服务器、命令、子智能体和技能,而 hooks 并不在该文档记录的列表中。手动移动它们主要是转换工作,因为这两个工具都使用相同的三个层级:事件、匹配器组和处理器。大多数事件名称、SessionStart 来源、通用输入字段、退出代码 2 和默认超时都可以沿用。
变化在于细节:匹配器的评估方式不同,apply_patch 需要 Claude Code 工具名称,脚本路径应使用 ${CLAUDE_PROJECT_DIR},且读取 model、turn_id 或 additionalContextLimit 的脚本需要调整。Codex 通过哈希信任每个 hook,而 Claude Code 检查工作区信任。利用这次迁移将静态上下文放入 CLAUDE.md,并保留 hooks 处理变化的内容。