什么是 Codex 中的 hooks
OpenAI 的文档将 hooks 描述为“Codex 的可扩展性框架”。它们允许你在对话的特定时间点运行脚本或 MCP 工具。
文档列举了一些示例，包括扫描 prompt 以拦截误贴的 API 密钥、在回合停止时运行验证检查，以及一个直接与 memory 相关的示例：“自动总结聊天以创建持久化的 memories”。
Hooks 绑定到事件上。以下是一些主要的事件：
- SessionStart：在 session 启动时运行，包括 compaction 之后。
- PreToolUse 和 PostToolUse：在工具调用前后运行。
- PreCompact 和 PostCompact：在 compaction 前后运行。
- UserPromptSubmit：当你发送 prompt 时运行。
- Stop：当一个回合停止时运行。
Codex 在 hooks.json 文件或 config.toml 中的内联 [hooks] 表中查找 hooks。文档列出了四个最有用的位置：~/.codex/hooks.json、~/.codex/config.toml，以及 <repo>/.codex/ 下的同名文件。启用的插件也可以捆绑 hooks。
如果多个来源都有 hooks，Codex 会加载所有匹配的项。OpenAI 表示，高优先级层“不会替换低优先级的 hooks”。
为什么 hook 会被标记为待审核
OpenAI 文档的审核部分用两句话解释了这一机制：“在非托管 hook 运行之前，Codex 要求你审核并信任确切的 hook 定义。Codex 根据 hook 当前的哈希值记录信任，因此新增或更改的 hooks 会被标记为待审核并跳过，直到获得信任。”
关键词是“确切”和“哈希”。Codex 并不是在询问你是否信任某个文件路径或脚本名称，而是在询问你是否信任这个确切的定义。因此，以下任何操作都会使 hook 重新进入审核状态：
- 你添加了一个新 hook：它从未被信任过。
- 你编辑了一个 hook：更改后的定义具有不同的哈希值。
- 队友更改了项目 hook：如果仓库的
.codex/hooks.json在 pull 过程中发生了变化，新版本需要你的审核。
当启动时 hooks 需要审核，文档称 Codex 会“打印一条警告，告诉你打开 /hooks”。在你操作之前，这些 hooks 会被跳过。
这是最容易被忽视的部分。被跳过的 hook 不会停止 session。如果该 hook 负责加载 context，session 只会在没有它的情况下启动。
如何审核并信任 hooks
在 CLI 中，/hooks 是管理它们的地方。OpenAI 的文档指出，你可以使用它“检查 hook 来源、审核新增或更改的 hooks、信任 hooks 或禁用单个非托管 hooks”。
在桌面应用中，可以通过在 composer 中选择“Review hooks”或打开“Settings > Hooks”来审核插件 hooks。
审核时，请查看 hook 运行的内容及其输入来源。信任是允许脚本在你的 sessions 中运行的决定，因此在批准之前阅读命令是值得的，特别是对于那些不是你编写的项目 hooks。
有两种 hooks 不需要经过此审核：
- 托管 hooks：来自系统、MDM、云端或
requirements.toml来源的 hooks “被标记为已托管，受策略信任，且无法从用户 hook 浏览器中禁用”。 - 一次性绕过：对于已经在其他地方审查过 hook 来源的自动化操作，Codex 提供了一个
--dangerously-bypass-hook-trust标志，可以在不持久化信任的情况下运行已启用的 hooks。顾名思义，这仅适用于极少数情况。
Hooks 默认开启。你可以通过在 config.toml 的 [features] 下设置 hooks = false 来完全关闭它们。
为什么项目 hooks 可能根本无法加载
有时项目 hook 不会出现在审核列表中，因为 Codex 根本没有加载它。这关乎项目信任，而非 hook 信任。
OpenAI 的 hooks 文档指出：“仅当项目 .codex/ 层受信任时，项目本地 hooks 才会加载。”其配置基础页面补充道，如果你将项目标记为不受信任，Codex 会“跳过项目范围的 .codex/ 层，包括项目本地配置、hooks 和 rules”。用户和系统 hooks 仍会加载。
因此，仓库中的 hook 有两道门槛：
- 项目必须受信任，以便 Codex 读取
<repo>/.codex/。 - Hook 本身必须在其当前哈希值下受信任。
如果你克隆了一个带有 hooks 的仓库但没有任何反应，请在检查第二道门槛之前先检查第一道。
插件 hooks 与更新
插件可以自带 hooks。默认情况下，Codex 会在插件内部查找 hooks/hooks.json，插件 manifest 也可以指向其他位置。OpenAI 表示，插件 hooks “使用与其他非托管 hooks 相同的信任审核流程”。
插件有一个特有的细节。文档指出：“如果插件更新更改了捆绑的脚本，即使 hook 定义保持不变，Codex 也需要重新审核。”
因此，即使你自己的配置没有发生任何变化，插件更新也可能使其 hooks 重新进入审核状态。如果插件 hook 在更新后停止运行，/hooks 是首先要查看的地方。
SessionStart hook 如何为 session 提供项目 context
对于 context，SessionStart 是首先要关注的事件。它在 session 开始时运行，其返回的内容会被添加供模型查看。
OpenAI 的文档指出，对于 SessionStart，“stdout 上的纯文本将作为额外的开发者 context 添加。”hook 还可以返回带有 additionalContext 字段的 JSON，并且“该 additionalContext 文本将作为额外的开发者 context 添加”。
该事件会告诉你的 hook session 是如何启动的。source 字段可以是 startup、resume、clear、compact 或 fork。你可以根据这些来源在不同情况下加载不同的 context。
对于长任务，需要了解 compact 情况。文档指出，在 Codex 对根 session 进行 compaction 后，匹配 compact 的 SessionStart hooks 会“在下一次模型请求之前运行”。这包括回合中间的自动 compaction。因此，在摘要替换之前的对话后，hook 可以立即重申长任务中不能丢失的少数事实。我们的 GPT-6.1 Sol 在 Codex 中的 500k context 指南更详细地介绍了 compaction。
一个时间细节：OpenAI 指出 SessionStart hooks 可能会在 MCP 服务器就绪之前运行。如果发生这种情况，它们不会阻塞 session。
保持 context 简短
SessionStart hook 可以为每个 session 提供 context，这让人很想塞入大量内容。文档设定了限制并解释了原因。
默认情况下，Codex 将模型看到的每个 hook 输出消息限制在约 2,500 个 tokens。如果 hook 返回更多内容，Codex 会将全文保存到文件中，并为模型提供一个带有文件路径的简短预览。OpenAI 称之为“溢出 (spilling)”。
你可以通过处理程序上的 additionalContextLimit 来提高阈值，但文档警告不要依赖它：“来自多个 hooks 和插件的 context 会累加，并可能降低模型性能。提高 additionalContextLimit 会增加这种风险。”
它还提到了隐私点。由于超大输出可能会被写入磁盘，因此建议避免在 hook 输出中返回密钥或其他敏感数据。
因此，一个好的 SessionStart hook 应该加载重要内容的简短、即时摘要，而不是整个文档。对于不经常变动的规范，AGENTS.md 是标准位置。我们的防止 Codex 跳过你的 AGENTS.md 规则指南涵盖了这些文件的加载方式。
人们首先会尝试的操作
假设 hook 坏了：它可能只是在更改后等待审核。
不阅读就重新信任：审核的存在是因为 hooks 会在你的 sessions 中运行脚本。
在调试时编辑 hook 却忘记重新信任：每次编辑都会改变哈希值。
在不受信任的项目中寻找项目 hooks：Codex 会跳过该项目的 .codex/ 层。
通过 SessionStart 提供整个文档：大型输出会溢出到磁盘，模型只能看到预览。
解决方法：让你的 context hook 重新运行
第 1 步：打开 /hooks 并审核待处理项
启动 Codex 并打开 /hooks。查找标记为待审核的 hooks，阅读每个 hook 运行的内容，并信任你预期的那些。在桌面应用中，针对插件 hooks 使用“Review hooks”或“Settings > Hooks”。
第 2 步：检查项目门槛
如果仓库 hook 根本没有出现，请确认项目已受信任。Codex 仅为受信任的项目加载 <repo>/.codex/。
第 3 步：使 SessionStart hook 保持简短且稳定
让 hook 通过 additionalContext 返回简短摘要，并同时匹配 compact 和 startup，以便在 compaction 后摘要能够恢复。保持 hook 定义稳定，这样它就不会在你每次微调时都重新进入审核状态。
在 MemoryLake 中设置
SessionStart hook 是一种交付机制。它决定了 context 何时到达 session，而不是 context 是什么或存储在哪里。如果它加载的摘要存在于某个仓库的脚本或某台机器的文件中，那么它的时效性仅取决于最后一次编辑它的人，且仅在运行该 hook 的地方可用。我们的 Codex memories v2 指南涵盖了 Codex 在你机器上保留的本地 memory。
MemoryLake 是一个 memory 层，用于将项目 context 统一保存在你维护的一个地方，供你连接的助手（如 ChatGPT、Claude Code 和 Codex）使用。
你用自己的语言亲自编写条目。你的 hooks、hooks.json 或 config.toml 文件、AGENTS.md 文件、Codex sessions、Codex memories 或任何供应商的存储都不会被读取、写入或删除任何内容。Hook 的审核、信任和 SessionStart 的工作方式与 OpenAI 描述的完全一致。
第 1 步：创建 API 密钥
登录并从控制面板生成密钥。该密钥属于你的 MemoryLake 工作区，与你的 OpenAI 账号是分开的。
第 2 步：上传你的第一批 memories
从你希望 session 开始时的简短摘要开始：项目目标、当前决策和约束。每个条目对应一个决策，这样你就可以在不重写其余部分的情况下更新其中一项。
第 3 步：连接你的 AI 和 agents
连接 Codex 和你使用的任何其他助手。相同的条目可在不同的 sessions 和工具中通用，并且你可以在一个地方统一更新它们。
这在实践中改变了什么
第一个区别是减少了无声的断层。你依赖的 context 不再仅仅存在于一个可能正在等待审核的脚本中。
第二个区别是稳定的 hook。当摘要存储在别处时，hook 定义的更改频率会降低，因此它重新进入审核状态的次数也会减少。
第三个区别是跨工具的一致性。相同的决策在 Codex 和你连接的其他助手中都可用。
Codex hooks 的最佳实践
预期每次更改后都要审核：信任与 hook 当前的哈希值绑定。
信任前先阅读：Hooks 会在你的 sessions 中运行脚本。
先信任项目：仓库 hooks 不会在不受信任的项目中加载。
插件更新后重新检查：更改后的捆绑脚本需要重新审核。
在 SessionStart 中匹配 compact：它能在 compaction 后立即恢复核心要素。
保持 hook 输出简短：大型输出会溢出到磁盘，且 context 会累加。
不要在 hook 输出中包含密钥：超大输出可能会被写入磁盘。
结论
“Hooks need review”意味着 Codex 发现了尚未在其当前版本下获得信任的新增或更改的 hooks。OpenAI 的文档指出，Codex 根据每个 hook 的哈希值记录信任，因此新增或更改的 hooks 会被跳过，直到你在 /hooks 中信任它们。插件 hooks 遵循相同的规则，更改了捆绑脚本的插件更新需要重新审核。项目 hooks 在加载之前也需要项目本身受信任。
最值得优化的 hook 是 SessionStart。它的输出在 session 启动时作为开发者 context 添加，而匹配 compact 的 hook 在 compaction 后会再次运行。保持 context 简短，保持 hook 稳定，并在 session 中缺少预期内容时随时检查 /hooks。