Codex钩子让代理框架真正成形

截至Codex 0.150.1（2026年8月27日），Codex钩子已注册十二个生命周期事件，任何非受管钩子在您审查并信任其确切定义之前都会被拒绝运行，并且钩子默认启用。这项功能于5月14日随发布包与ChatGPT移动应用一同达到正式可用，如今已成熟为一个治理表面：PreToolUse可以在工具调用运行之前阻断或改写它，PermissionRequest可以直接决定一次审批，PostToolUse可以替换模型看到的结果，Stop可以拒绝让一个轮次结束。²³

Codex不再像一个守在单个终端里的编程助手。它更像一个操作层，能够跟随工作穿过机器、审批、项目、会话、差异、测试、截图、插件、凭据和本地工具。⁴

Codex钩子让代理框架真正成形。 当代理可以从手机上工作、触达远程开发环境，并运行生命周期钩子时，团队就需要围绕模型建立一套控制系统：证据、审批、Git管护、来源纪律和品味。

TL;DR

Codex已经支持代理团队长期在内部搭建的工作流形态：长时间运行的工作、远程执行、移动端调度、审批、钩子、作用域受限的凭据，以及审计信号。²⁴⁵ 0.150.0的钩子引擎注册了十二个事件，每个非受管钩子在您信任其当前哈希之前都保持跳过状态，钩子从hooks.json文件或config.toml中的内联[hooks]表加载。³⁷ 真正实用的问题不是“如何给Codex写提示词？”而是“Codex必须证明什么，我们才信任结果？”团队应使用钩子和配置来编码审查关口、安全边界、公开写作标准和发布纪律。私有机制应保持私有，公开的只应是模式、验收标准和经过验证的结果。

关键要点

对于工程团队： - 将Codex钩子视为流程基础设施，而不是装饰。信任审查流程是这套基础设施的一部分，而不是需要绕过的阻力。 - 先建立证据、审批、Git管护和发布检查，再添加更聪明的自动化。

对于代理工具构建者： - 围绕Codex的真实表面构建：移动端控制、Remote SSH主机、沙箱模式、审批策略、项目指令、钩子、遥测和版本控制。 - 迁移待完成的工作，而不是照搬旧的斜杠命令形态。

对于公开写作者： - 使用learn.chatgpt.com上的官方文档确认Codex的当前行为；当文档落后于某个版本时，请查证引擎源码。 - 将私有实践标注为作者分析，不要把私有提示词、钩子实现、文件路径、来源列表、凭据和评分内部逻辑写入公开文本。

Codex钩子从何而来？

OpenAI于2026年5月14日发表了“Work with Codex from anywhere”（在任何地方使用Codex）。¹ 文档更新日志中当天的条目记录了这次发布包的内容：通过连接一台运行Codex应用的Mac，Codex可以在ChatGPT移动应用中使用；钩子达到正式可用；面向受信任自动化的Codex访问令牌也随之推出。² Codex从所连接的主机上运行，因此同样的项目、文件、凭据、插件、技能和配置在手机上同样可用。²

远程连接把工作范围延伸到了一张办公桌之外。公告中的Remote SSH能力在文档中落地为SSH主机：ChatGPT桌面应用可以从SSH主机添加远程项目，并针对远程文件系统和shell运行会话。文档的表述很具体：“Remote access uses the connected host’s projects, chats, files, credentials, permissions, plugins, Computer Use, browser setup, and local tools.”（远程访问使用所连接主机的项目、会话、文件、凭据、权限、插件、Computer Use、浏览器设置和本地工具。）⁴

钩子本身在这次发布之前就以实验形式存在，之后又超出了实验的范畴。文档将其定义为一个可扩展性框架，在代理循环期间运行脚本或MCP工具，并直白地列出了用途：把会话发送到日志引擎、拦截不小心粘贴的API密钥、把会话总结为持久记忆、在轮次停止时运行验证检查，以及按目录定制提示。³ 钩子现在默认启用；config.toml中的features.hooks充当总开关，features.codex_hooks只作为已弃用的别名存续。³⁶

这些细节之所以重要，是因为它们把代理工作从一场聊天交流变成了受治理的运营。

Codex钩子在配置中长什么样？

一篇讲钩子的文章应该展示一个钩子。Codex在活动配置层旁边发现钩子，最常用的位置是~/.codex/hooks.json、<repo>/.codex/hooks.json，或任一层config.toml中的内联表；当存在多个来源时，所有匹配的钩子都会加载并运行。³ 一个带有工具关口和完成关口的最小hooks.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/pre_tool_use_policy.py",
            "timeout": 30,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/evidence_gate.py"
          }
        ]
      }
    ]
  }
}

同样的结构以内联形式写在config.toml中：

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

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/pre_tool_use_policy.py"
timeout = 30
statusMessage = "Checking Bash command"

每个钩子由三层组织：一个事件、一个决定事件何时适用的匹配器组，以及一个或多个处理器（command或mcp_tool）。³ 当前的事件如下，以引擎中的十二项列表为权威依据：³⁷

在线的钩子文档目前仍只记录了其中十一个事件，尚没有Interrupt小节。第十二个事件由0.150.0更新日志条目（#40511）以及rust-v0.150.0引擎源码中的HOOK_EVENT_NAMES: [&str; 12]承载。²⁷ 当页面与引擎不一致时，请以引擎为准。

钩子究竟能看到哪些工具调用？

早期版本的文档曾警告，PreToolUse覆盖的范围基本不超出shell和MCP调用。当前文档扩大了这一表面：“PreToolUse and PostToolUse can observe more than shell and MCP calls. Most local function tools use the same hook path,”（PreToolUse和PostToolUse能观察到的不止shell和MCP调用，大多数本地函数工具走同一条钩子路径。）因此匹配器可以直接点名update_plan这样的工具，spawn_agent也会以Agent的名义匹配。³ shell命令以Bash匹配，apply_patch文件编辑以apply_patch、Edit或Write匹配，MCP工具则匹配mcp__filesystem__read_file这样的名称。³

托管工具仍在其外：WebSearch及其同类永远不会经过本地函数工具的钩子路径。³ 文档保留了一条措辞已放缓、值得完整引用的提醒：“Some specialized tool paths can opt out of the default hook path. Treat tool hooks as a useful guardrail, not a complete enforcement boundary.”（某些专门的工具路径可以选择退出默认钩子路径。请把工具钩子当作有用的护栏，而不是完整的强制边界。）³ 硬边界仍归沙箱所有；钩子负责的是边界之内的审查与引导。

Codex如何决定哪些钩子可以运行？

钩子是引导代理的代码，因此Codex对钩子本身进行治理。围绕模型的控制系统正是从这里开始。

任何非受管钩子在运行之前，Codex都要求您审查并信任其确切定义。信任以钩子的当前哈希为记录依据，因此新增或被编辑过的钩子会被标记为待审查，并保持跳过状态，直到再次获得信任。³ CLI中的/hooks命令打开审查界面：检查钩子来源、审查新增或变更的钩子、信任它们，或单独禁用某一个。当启动时有钩子需要审查，Codex会打印一条指向/hooks的警告。³

来自系统、MDM、云端或requirements.toml来源的受管钩子位于这套流程之上：它们按策略受信任，无法从用户钩子浏览器中禁用。³ 插件则位于这套流程之内：安装或启用插件并不会信任其捆绑的钩子，这些钩子与其他钩子一样保持跳过状态，直到通过审查。³ 项目本地钩子仅在项目的.codex/层受信任时才会加载；不受信任的项目仍会加载您的用户钩子和系统钩子。³

自动化同样受这条规则约束。codex exec运行没有审查UI，因此不受信任的钩子会被静默跳过，除非您先在交互式会话中信任它；文档尚未这样说明，但引擎的启动审查界面只存在于交互式TUI中。⁷ 对于在别处审核钩子来源的流水线，--dangerously-bypass-hook-trust可以在单次调用中运行已启用的钩子而不持久化信任。³ 要么审慎地建立信任，要么眼看着您的关口不触发：在任何代码运行之前，代理框架先决定哪些代码可以引导代理。

钩子阻断时会发生什么？什么时候为时已晚？

时机决定钩子还能改变什么。大多数钩子同步运行，默认超时600秒；SessionEnd和Interrupt默认1秒，上限3秒：SessionEnd在会话拆除过程中触发，Interrupt在用户等待时触发。³⁷

PreToolUse在一切发生之前行动，因此手里握着最强的牌：拒绝该调用，或者通过返回带updatedInput的permissionDecision: "allow"来改写它。拒绝的结构如下：

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

退出码2加上写到stderr的理由同样可以阻断。³

PostToolUse在工具运行之后行动，因此无法撤销副作用。decision: "block"会用您的反馈替换工具结果，并让模型从该消息继续，这样既能纠正航向，又不必假装命令从未发生。³ Stop把一次拒绝变成一次继续：阻断完成后Codex会继续工作，您给出的理由会成为新的提示词。³

对于永远不应占据关键路径的检查，可在命令处理器上设置async = true。后台钩子在Codex继续工作的同时运行，在下一个安全点交付输出，并且明确无法阻断、审批或改写任何东西；工具策略、权限决定、提示拒绝和轮次继续请保持同步执行。³

0.149和0.150升级了什么？

8月下旬的两个稳定版本收紧了治理故事。

Codex CLI 0.149.0（2026年8月20日）退役了untrusted审批策略（#39630）；仍写有该值的配置现在会以一条可操作的错误失败，提示您移除该设置。²⁷ Codex CLI 0.150.0（2026年8月26日）新增了Interrupt钩子事件（#40511）：“New Interrupt hooks can run commands or MCP handlers when an active top-level turn is interrupted.”（新的Interrupt钩子可以在活动的顶层轮次被中断时运行命令或MCP处理器。）Interrupt钩子从不为子代理运行。²⁷ 同一版本还阻止了不受信任的项目提供项目级AGENTS.md指令（#39837），这与项目本地钩子只从受信任的.codex/层加载的既有规则相互呼应。²³

方向是一致的：不受信任的目录对走进它的代理拥有的权力越来越小。指令、钩子和审批捷径如今都要经过显式的信任决定。

为什么钩子比移动端更重要？

移动端访问改变的是人可以在哪里介入。钩子改变的是系统可以强制执行什么。

手机让操作者可以在离开办公桌时回答一个问题。钩子则可以在风险动作之前、文件编辑之后、完成之前或发布检查期间拦住代理。手机解决的是延迟。钩子解决的是标准。

Codex在沙箱和审批方面已经有第一方控制表面。安全文档把两层配对：沙箱模式定义代理在技术上能做什么，审批策略定义Codex何时必须停下来先询问再行动。⁵ 代理默认在网络访问关闭的状态下运行，默认的本地workspace-write模式也保持网络访问关闭，除非用户主动启用。⁵ 钩子作为审查与引导层与这些控制并列，而不是沙箱的替代品。

钩子可以让本地标准变得可执行：

模型可能忘记一条规则。钩子可以在规则最要紧的那一刻重新运行这条规则。

哪些东西归代理框架所有，而不归提供商？

代理框架（agent harness）是围绕模型的操作层：权限、记忆、工具、钩子、来源检查、发布关口、审查包和回滚纪律。这个词听起来可能私密或花哨，但它的职责很朴素。这一层把意图变成可问责的工作。

Codex现在暴露的官方表面已经足以让这一层变得显式。远程连接承载主机环境。沙箱模式和审批策略定义动作边界。配置文件定义模型、项目、权限、MCP服务器、技能、钩子、遥测和功能。⁶ OpenTelemetry导出保持可选且默认关闭；启用后，Codex会发出结构化事件，覆盖会话、API请求、流活动、用户提示（默认脱敏）、工具审批决定和工具结果。⁵⁸

这组表面形成了一个有用的分界：

提供商应当持续改进运行时。判断力仍归团队所有。

团队应该先编码什么？

从四个关口开始。它们立刻就能证明自己的价值。

证据关口

Codex最初的发布文章强调了可验证的证据：终端日志、测试输出，以及任务完成过程中可追溯的步骤。⁹ 请把这一期待变成不可协商的要求。一次有意义的完成应当点名变更的文件、运行的命令、观察到的行为、失败的检查和遗留的缺口。

对于公开工作，证据包括来源链接以及论断与来源的对齐。对于网页发布，证据包括渲染后的路由、元数据、schema、发现文件、部署状态、缓存新鲜度和线上变更标记。对于翻译，证据包括语言区域覆盖、质量关口、存储行或缓存文件，以及必要时的母语审校状态。

审批关口

不要对每种动作使用同一种审批姿态。审批文档当前的组合表从Auto预设（workspace-write沙箱配on-request审批）一路排到安全只读浏览、只读非交互式CI、自动审阅模式和危险的完整访问。⁵ 其中一行落后于现实：untrusted策略仍出现在页面上，但0.149.0已将其退役，显式配置现在会报错。²⁵ 若今天想要始终询问的姿态，请把read-only沙箱与on-request审批组合使用。一套强健的本地策略保持同样的形态：低风险读取安静通过，有副作用的工作接受审查，破坏性或对外可见的工作则需要显式证据。

Git管护关口

代理工作需要回滚抓手。Codex自己的安全文档说，Codex与版本控制配合使用效果最佳：委派之前保持状态干净、频繁提交、运行针对性验证、审查差异，并在提交信息中记录决定。⁵

这条建议应当变成流程。在连贯且经过验证的保存点之后提交。按精确路径暂存。按可独立回滚的关注点拆分提交。除非发布流程已经授予发布权限，否则推送之前先询问。不要因为代理恰好看到了无关的脏文件，就把它们扫进一次提交。

品味关口

AI编码让实现变得更便宜。更便宜的实现抬高了品味的价值。

品味不是指装饰性的偏好。它意味着工作改善的是整个产品。意味着代理可以拒绝一条技术上可行却会削弱结果的路径。意味着公开写作避开私有机制、缺乏依据的论断和填充内容。意味着即使本地补丁正确，只要用户可见的路径仍然坏着，工作仍然算失败。

品味关口应当问：

Mozilla的Firefox工作证明了什么？

Mozilla在5月7日发表的关于用Claude Mythos Preview加固Firefox的文章，从另一个技术栈得出了同样的结论。团队表示，早期的LLM代码审计尝试展现了潜力，但误报太多，无法规模化。代理框架改变了经济账，因为它们能够创建并运行可复现的测试用例，动态检验bug假设。¹⁰

Mozilla最重要的那句话并不只关乎模型本身。团队说，发现是必要的，但并不充分。真正有用的系统必须与完整的安全bug生命周期集成：目标、去重、bug跟踪、分诊、修复和发布。¹⁰ 作者们还表示，这条流水线反映了Firefox代码库的语义、工具链和流程。¹⁰

这正是对Codex的启示。更好的模型固然重要。但模型周围的运营系统决定了工作能否成为受信任的产出。

哪些内容不应出现在公开文本中？

一篇公开的Codex文章不应倾倒私有的工作系统。

以下内容请留在公开文本之外：

• 私有提示词和钩子实现；
• 敏感的本地路径；
• 精确的来源映射和评分内部逻辑；
• 账户标识符和凭据处理方式；
• 私有工作流捷径；
• 未发布的插件行为；
• 任何能帮助陌生人重建内部运营的信息。

应该公开的是模式：关口保护什么、要求什么证据、能捕捉什么失败，以及团队如何用官方Codex表面实现这一想法。

这条界线保护的是信任。它同时也让文章更好。私有机制读起来通常像民间传说。公开的验收标准则能帮助其他团队推演自己的系统。

最小的Codex代理框架地图长什么样？

构建能够证明有用工作的最小控制地图。

从显式开始。跑一个真实任务。记录关口在哪里帮了忙、在哪里碍了事。只推广那些改善用户可见结果的部分。

快速总结

Codex钩子、Remote SSH、移动端控制、沙箱、审批、配置、遥测和版本控制都指向同一个方向：编码代理需要围绕它们的操作系统。²⁴⁵⁶ 代理可以写代码。代理框架决定什么才算得上工作。

最好的团队不会靠产出最多的代理成果获胜。他们会靠让代理工作可检查、可回滚、有来源、有品味且值得发布来获胜。

常见问题

什么是Codex钩子？

Codex钩子在代理循环期间运行脚本或MCP工具，从hooks.json文件或config.toml中的内联[hooks]表加载。文档直白地列出了用途：把会话发送到日志引擎、拦截不小心粘贴的API密钥、把会话总结为持久记忆、在轮次停止时运行验证，以及按目录定制提示。³ 0.150.0的引擎注册了十二个事件，从PreToolUse、PermissionRequest和PostToolUse一直到Stop和新增的Interrupt；文档页面尚在跟进，目前仍只列出十一个。³⁷

Codex钩子为什么重要？

钩子让团队把标准放到决策点上，而不是只依赖提示词。当代理行动或尝试结束时，钩子可以检查证据、来源质量、git状态或发布就绪度。

我的钩子为什么没有运行？

通常的答案是信任。Codex会跳过任何您尚未审查其当前哈希的非受管钩子，在交互式会话中打印启动警告，而在codex exec自动化中则静默跳过。⁷ 请打开/hooks审查并信任它，或者仅在于别处审核钩子来源的流水线中传入--dangerously-bypass-hook-trust。³

Codex移动端会取代本地代理工作流吗？

不会。移动端控制让用户可以在离开办公桌时调度工作，但项目、会话、文件、凭据、权限、插件和本地工具仍由所连接的主机提供。⁴ 团队仍然需要本地策略、安全的凭据、版本控制和验证。

Codex代理框架应该先包含什么？

从项目指令、沙箱与审批姿态、机密边界、证据停止关口、精确路径的Git管护、面向公开论断的来源验证，以及面向用户可见工作的发布关口开始。

团队应该公开自己的Codex钩子吗？

应该公开模式和验收标准，而不是私有钩子实现或敏感的工作流细节。一篇有用的公开文章可以解释钩子的职责，而无需暴露私有路径、来源映射、提示词、凭据或评分规则。

参考资料