第一次查看和审查 Hooks

第一次查看和审查 Hooks

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

先学会看。

这篇只做低风险动作：

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

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

本篇目标

完成后你应该能做到：

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

第 1 步：打开一个安全项目

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

建议用：

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

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

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

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

预期结果：

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

第 2 步：在 CLI 里使用 /hooks

在 Codex CLI 中输入：

/hooks

它用于查看和管理当前会话加载到的生命周期 Hooks。

你要重点看：

• Hook 来源。
• 触发事件。
• matcher。
• command。
• 是否需要信任。
• 是否已禁用。

第 3 步：看 Hook 来源

常见来源：

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

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

第 4 步：看触发事件

常见事件：

事件	你要问什么
PreToolUse	工具调用前会做什么
PostToolUse	工具调用后会做什么
PermissionRequest	权限请求时会做什么
PreCompact	上下文压缩前会做什么

新手重点关注：

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

第 5 步：看 command

这是最重要的。

你要看它会执行什么。

如果看到类似：

python3 .codex/hooks/check_secrets.py

要继续问：

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

不要只看文件名觉得安全。

第 6 步：让 Codex 帮你解释 Hook

复制 Hook 配置后问：

请帮我审查这个 Hook。

Hook 配置：
【粘贴配置】

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

预期结果：

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

第 7 步：决定是否信任

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

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

如果不满足，就不要信任。

可以对 Codex 说：

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

第 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

可能原因：

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

先问：

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

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

Hook 变更后又要求信任

这是正常的。

Hook 定义变了，就要重新审查。

不要觉得麻烦就跳过。

Hook 命令看不懂

不要信任。

先解释，再决定。

这一篇的验收标准

完成后你应该有：

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

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