Claude Code Hooks 推荐：先装这 6 个，配置直接复制（2026）

Claude Code Hooks 推荐先装 6 个：桌面通知、改完自动格式化、保护 .env 这类文件、压缩后补回上下文、记录每条 Bash 命令、结束前检查测试。前 5 个是普通的命令 hook，复制配置就能用；最后一个用的是官方标着实验功能的 agent hook，想试再加。hook 和 Skill 最大的不同是：Skill 是 Claude 读了照着做，可能做也可能忘；hook 在固定时机一定会执行，不靠 Claude 自觉。

下面的配置都来自 Anthropic 的 官方 hooks 指南 和 Hooks 参考文档，2026 年 10 月 27 日核对。还没分清 Hook、Skill、MCP 各管什么的，可以先看 Claude Code Skills 和 MCP 区别。

先装这 6 个 hook

每个 hook 都由三部分组成：事件（什么时候触发）、matcher（只对哪些工具或情况触发）、要执行的命令。写进设置文件的 hooks 字段里，同一个事件下可以挂多个 hook。

1. 桌面通知：Claude 等你时提醒你

Claude 需要你授权或者等你回复时，弹一条系统通知，你就不用一直盯着终端。下面是 macOS 的写法，放进 ~/.claude/settings.json；Linux 把命令换成 notify-send，Windows 用 PowerShell 弹窗，三种写法 官方文档 里都有。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

matcher 留空就是所有通知都弹。只想在要授权时提醒，就写 permission_prompt，它在授权提示等了大约 6 秒后触发；写 idle_prompt 则是 Claude 回答完大约 60 秒你还没打字才触发。Mac 上如果没弹出来，多半是「脚本编辑器」没有通知权限，到系统设置的通知里打开就行。

2. 改完文件自动格式化

每次 Claude 用 Edit 或 Write 改完文件，就对这个文件跑一次 Prettier，格式不用你再管。这个放在项目的 .claude/settings.json 里，团队一起用（官方示例）。需要先装好 jq。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

注意它只管 Edit 和 Write。Claude 用 Bash 命令改的文件不会触发，想覆盖这种情况，官方建议改用 FileChanged 事件。

3. 保护 .env 和锁文件

这是最值得装的一个。PreToolUse 在工具执行之前触发，脚本以退出码 2 结束，这次修改就会被拦下，脚本写到 stderr 的原因会作为反馈交给 Claude，让它换个做法（官方示例）。先把脚本存成 .claude/hooks/protect-files.sh，再 chmod +x 加上执行权限：

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

然后在 .claude/settings.json 里注册：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

要保护哪些文件，改 PROTECTED_PATTERNS 那一行就行。官方文档还提到，hook 返回 deny 在任何权限模式下都有效，包括 bypassPermissions，所以拿它做硬性规矩比写在 CLAUDE.md 里靠谱。

4. 上下文压缩后补回关键信息

对话太长时 Claude Code 会压缩上下文，一些细节可能就丢了。给 SessionStart 加一个 matcher 为 compact 的 hook，每次压缩后把项目规矩重新塞回去（官方示例）。hook 输出到 stdout 的文字会进入 Claude 的上下文。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing.'" }
        ]
      }
    ]
  }
}

echo 后面换成你自己的规矩，也可以换成 git log –oneline -5 这类命令，把最近的提交带进去。如果是每次开会话都要的信息，官方建议直接写进 CLAUDE.md。

5. 记录 Claude 跑过的每条 Bash 命令

事后想查 Claude 到底执行了什么，这个最省事。PostToolUse 在命令执行成功后触发，把命令追加到一个日志文件里：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt" }
        ]
      }
    ]
  }
}

它只记成功执行的命令，失败的要另外挂 PostToolUseFailure。

6. 结束前检查测试有没有过

Stop 事件在 Claude 回答完时触发。用 agent 类型的 hook，会起一个子代理去跑测试，没通过就让 Claude 接着改（官方示例）。agent hook 默认超时 60 秒，这里设成了 120 秒。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

三点要注意。第一，Stop 不支持 matcher，而且 Claude 每回答完一次都会触发，不只是任务做完的时候。第二，agent hook 目前是实验功能，官方说正式流程优先用命令 hook。第三，Stop hook 连续拦 8 次、中间 Claude 没调用任何工具，Claude Code 就不再听它的；自己写命令版 Stop hook 时，要检查输入里的 stop_hook_active 字段，为 true 就直接放行，不然容易一直循环（官方说明）。

常用的 hook 事件

官方文档目前列了 33 个事件，日常用到的就上表这几个。PreToolUse 能在执行前拦下操作；PostToolUse 发生在工具执行之后，已经做完的事撤不回来（官方限制说明）。

同一个事件挂了多个 hook 时，它们会并行执行，全部跑完再合并结果。PreToolUse 的决定取最严格的那个，顺序是 deny、defer、ask、allow（官方说明）。所以一个记日志的 hook 和一个拦截的 hook 可以放在一起，拦截生效的同时日志照样会写。

hook 写在哪个文件

个人习惯（比如桌面通知）放 ~/.claude/settings.json；团队都要遵守的规矩（比如保护文件、自动格式化）放项目里的 .claude/settings.json，提交进仓库。几个设置文件分别在什么路径、谁覆盖谁，可以看 Claude Code settings.json 位置在哪。

写完在 Claude Code 里输入 /hooks，能看到按事件分组的所有 hook，确认你的配置被读到了（官方说明）。想临时全部关掉，在设置里加 “disableAllHooks”: true。

hook 也可以打包进插件，写在插件的 hooks/hooks.json 里，插件启用期间生效。现成的插件可以看 Claude Code Mods 推荐，想自己写一个，看 Claude Code 插件怎么写。

装之前看一眼安全

官方文档写得很直接：命令 hook 用你当前用户的完整权限执行 shell 命令，你账号能读写、删除的文件它都能动（安全说明）。所以从网上抄来的 hook，先看懂每一行再加。插件带的 hook 也一样，启用插件前先看它的 hooks/hooks.json 里写了什么。

另外，命令 hook 默认超时 10 分钟。格式化、lint 这类慢命令一般没问题，但不要在 hook 里跑会卡住等输入的东西。

常见问题

Claude Code Hooks 推荐先装哪一个？

先装保护文件的 PreToolUse hook。它能拦下对 .env、.git/ 这类文件的修改，而且在任何权限模式下都有效。其次是桌面通知，装上马上就能感觉到区别。

hook 没有生效怎么办？

先输入 /hooks 看它在不在对应事件下面。不在的话，检查 JSON 有没有多余的逗号、文件路径对不对。在的话，检查 matcher 是否和工具名完全一致，matcher 区分大小写。脚本类的 hook 还要确认已经 chmod +x。

hook 能直接调用斜杠命令吗？

不能。命令 hook 只能通过 stdout、stderr 和退出码跟 Claude Code 沟通，不能触发 / 开头的命令，也不能直接调用工具（官方限制说明）。需要 Claude 做判断的场景，用 prompt 或 agent 类型的 hook。

这份 Claude Code Hooks 推荐清单只用了官方文档里的示例，6 个都能单独装。建议一次加一个，用 /hooks 确认生效，再加下一个。用到 MCP 的话，hook 的 matcher 也能匹配 MCP 工具，MCP 本身怎么挑可以看 Claude Code MCP 推荐。