https://codexer.com/tags/%E6%8A%A4%E6%A0%8F/Recent content in 护栏 on CodexerHugozh-cnFri, 16 Oct 2026 07:45:00 +0800https://codexer.com/posts/2026-10-16-codex-hooks-silent-failure/Fri, 16 Oct 2026 07:45:00 +0800https://codexer.com/posts/2026-10-16-codex-hooks-silent-failure/<p>你在 <code>~/.codex/hooks.json</code> 里写了几个钩子：<code>PreToolUse</code> 拦住 <code>rm -rf</code>，拦住读 <code>.env</code>，<code>PostToolUse</code> 跑一遍格式化，<code>Stop</code> 要求测试通过才准收工。头两天日志里能看到钩子输出，你觉得这事就算配好了。</p> <p>三个月后复盘，你回头翻记录，发现那几行输出最后一次出现是一个半月前。</p> <p>hooks 麻烦的地方不在能不能配，而在它坏掉的样子。它坏的时候不会报错：配置在、信任哈希在、别的插件的钩子还在打印日志，所有表面信号都是对的。下面这些是我在 openai/codex 的 issue 里翻到的案例，都能复现，共同点是安静。</p> <h2 id="先记住-hooks-的几个设定">先记住 hooks 的几个设定</h2> <p>官方文档里值得先划出来的几条：</p> <table> <thead> <tr> <th>位置</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>~/.codex/hooks.json</code>、<code>~/.codex/config.toml</code></td> <td>用户级</td> </tr> <tr> <td><code>&lt;repo&gt;/.codex/hooks.json</code>、<code>&lt;repo&gt;/.codex/config.toml</code></td> <td>项目级，只在该项目的 <code>.codex/</code> 层被信任时加载</td> </tr> <tr> <td>插件自带的 <code>hooks/hooks.json</code></td> <td>随插件启用而加载，走同样的信任流程</td> </tr> <tr> <td><code>requirements.toml</code></td> <td>托管钩子，按策略视为已信任，用户没法在钩子浏览器里禁用</td> </tr> </tbody> </table> <p>事件分三组：回合内的有 <code>PreToolUse</code>、<code>PermissionRequest</code>、<code>PostToolUse</code>、<code>PreCompact</code>、<code>PostCompact</code>、<code>UserPromptSubmit</code>、<code>Stop</code>、<code>SubagentStop</code>；会话或子 agent 启动时有 <code>SessionStart</code>、<code>SubagentStart</code>；主线程结束时是 <code>SessionEnd</code>。</p> <p>几条运行时规则：</p> <ul> <li>多个文件里匹配上的钩子都会跑。高优先级的层不替换低优先级的层，只做叠加。同一层里同时写了 <code>hooks.json</code> 和内联 <code>[hooks]</code>，Codex 会合并并在启动时给一条警告，所以一层里挑一种写法。</li> <li>非托管的命令钩子要先审阅并信任才会跑。信任记在钩子定义的哈希上，新增或改动过的钩子会被标成待审阅然后跳过。用 <code>/hooks</code> 看来源、审阅、信任或禁用。</li> <li>同一个事件上多个匹配的命令钩子并发启动，一个钩子拦不住另一个。</li> </ul> <p>还有一条最重要的：钩子崩了、超时了、返回了不合法的 JSON，操作照常进行，钩子只被标成 <code>Failed</code>。这个设计叫 fail-open，好处是钩子不会把 agent 卡死，代价是护栏失灵的时候没有任何东西会喊出来。</p> <p>官方文档自己也是这个调子：工具钩子是有用的护栏，不是完整的执行边界，有些特殊工具路径不走默认的钩子。</p> <h2 id="改完配置没重启这次会话的钩子全灭">改完配置没重启，这次会话的钩子全灭</h2> <p>openai/codex#21160，2026 年 5 月 5 日开的，报的是 <code>codex-cli 0.128.0</code>，Ubuntu 24.04 on WSL2。两个场景：</p> <ul> <li>会话撞到限流停下时，本该跑的那条 stop 钩子不跑。</li> <li>会话还活着的时候改 <code>hooks.json</code>，只要文件本身是合法 JSON（<code>jq</code> 验证通过），这个会话后面所有钩子都不再触发，重启会话才恢复。</li> </ul> <p>报告者的诉求很朴素：要么在限流停下时也跑钩子，要么明说这种情况会跳过；改配置可以继续用旧的那份，也可以热加载，或者至少提示一句需要重启。不能接受的是整个会话静默失去钩子。</p>