first-review-hooks

第一次学 Hooks，不要先创建。

先学会看。

这篇只做低风险动作：


查看当前有没有 Hooks -> 理解它们来自哪里 -> 判断能不能信任


> 前置教程：什么时候应该用 Hooks，什么时候不要用
> 如果你还不能判断什么时候需要 Hooks，先看前置教程。
完成后你应该能做到：

打开 Hooks 查看界面。
看懂 Hook 来源。
看懂 Hook 事件。
看懂 Hook 触发器（matcher）。
看懂 Hook 命令。
判断是否需要信任或禁用。
不运行看不懂的 Hook。

不要第一次就在陌生项目里信任 Hooks。
建议用：

你自己的练习项目。
已经熟悉的本地项目。
没有敏感数据的项目。

打开项目后，先让 Codex 只读检查：


请只读检查当前项目是否存在 Codex Hooks 配置。
要求：


不要创建、修改、删除任何文件。

2. 检查用户级和项目级可能的 hooks.json 或 config.toml hooks 配置。
3. 不要执行任何 Hook。
4. 如果发现 Hook，只总结来源、事件和命令，不要信任。


预期结果：

Codex 只做检查。
如果没有 Hooks，会直接说明。
如果有 Hooks，会列出来源 and 事件。

第 2 步：在 CLI 里使用 /hooks
Section titled “第 2 步：在 CLI 里使用 /hooks”
在 Codex CLI 中输入：


/hooks


它用于查看 and 管理当前会话加载到的生命周期 Hooks。
你要重点看：

Hook 来源。
触发事件。
matcher。
command（命令）。
是否需要信任。
是否已禁用。

常见来源：
| 来源                       | 风险判断                |
| ------------------------ | ------------------- |
| 用户级 \~/.codex/hooks.json | 你自己配置的，仍要审查         |
| 项目级 .codex/hooks.json    | 只在受信任项目加载，必须看项目是否可信 |
| config.toml 内联 \[hooks\] | 看所在配置层              |
| 插件提供的 Hooks              | 看插件来源是否可信           |
| 管理员托管 Hooks              | 通常由组织策略管理           |

如果来源是陌生项目的 .codex/hooks.json，不要直接信任。


常见事件：
| 事件                | 你要问什么      |
| ----------------- | ---------- |
| PreToolUse        | 工具调用前会做什么  |
| PostToolUse       | 工具调用后会做什么  |
| PermissionRequest | 权限请求时会做什么  |
| PreCompact        | 上下文压缩前会做什么 |
新手重点关注：


这个 Hook 会不会在我没注意的时候运行命令？


这是最重要的。
你要看它会执行什么。
如果看到类似：


python3 .codex/ecosystem/hooks/check_secrets.py


要继续问：

这个脚本在哪里？
脚本内容是什么？
只读还是会修改文件？
会不会联网？
会不会删除文件？
会不会读取密钥？

不要只看文件名觉得安全。
第 6 步：让 Codex 帮你解释 Hook
Section titled “第 6 步：让 Codex 帮你解释 Hook”
复制 Hook 配置后问：


请帮我审查这个 Hook。
Hook 配置：
【粘贴配置】
要求：


不要运行。

2. 解释事件、matcher、command。
3. 如果 command 指向脚本，请只读查看脚本内容。
4. 判断它是否只读。
5. 判断它是否会修改文件、删除文件、访问网络或读取敏感信息。
6. 给出是否建议信任。


预期结果：

Codex 会解释触发时机。
Codex 会解释命令。
Codex 会给出风险判断。

只有同时满足下面条件，才考虑信任：

来源可信。
事件合理。
matcher 范围清楚。
command 你能看懂。
脚本内容可审查。
不会做你不想要的高风险动作。
你知道怎么禁用或删除。

如果不满足，就不要信任。
可以对 Codex 说：


我暂时不信任这个 Hook。
请告诉我如何保持它不运行，以及如果以后要移除应该改哪个文件。
不要执行任何 Hook。


第 8 步：记录到 AGENTS.md 还是不记录
Section titled “第 8 步：记录到 AGENTS.md 还是不记录”

如果项目里确实有团队 Hooks，可以在 AGENTS.md 里写一条说明：


Hooks 使用说明

本项目可能加载 .codex/hooks.json 中的生命周期 Hooks。



新增或修改 Hooks 后，必须先审查事件、matcher、command 和脚本内容。


不要信任来源不明或无法解释的 Hooks。

但不要把 Hook 命令细节全部塞进 AGENTS.md。

详细配置留在 .codex/hooks.json 或 config.toml。

/hooks `里看不到项目级 Hook`


Section titled “/hooks 里看不到项目级 Hook”
可能原因：

项目不受信任。
Hook 文件路径不对。
配置语法错误。
当前启动目录不是你以为的项目目录。

先问：


请只读排查为什么当前会话没有加载项目级 Hooks。
要求：


不要修改文件。

2. 检查项目是否有 .codex/hooks.json。
3. 检查 config.toml 是否有内联 hooks。
4. 检查当前工作目录 and 项目根目录。
5. 不要信任或运行任何 Hook。


这是正常的。
Hook 定义变了，就要重新审查。
不要觉得麻烦就跳过。
不要信任。
先解释，再决定。
完成后你应该有：

/hooks` 页面里看到的来源、事件、matcher 和 command。
一个 Hook 来源判断。
一个 Hook 命令解释。
一个是否信任的理由。
一个“不运行看不懂 Hook”的习惯。

下一步可以继续写第一个低风险 Hook，但只有在你能审查 Hooks 之后才适合做。