Claude Code Hooks 怎么用？2026 Claude Code Hooks 配置教程（附 5 个实用示例）

Claude Code Hooks 是在 Claude Code 生命周期的特定时刻自动执行的命令：改完文件自动格式化、动到 .env 立刻拦截、需要你确认时弹出桌面通知。和写在 CLAUDE.md 里的规则不同，Hooks 是确定性的——到了那个时刻一定会执行，不依赖 Claude 是否"记得"。

这篇 Claude Code Hooks 配置教程讲清 Hooks 的事件类型、配置结构、matcher 写法和输入输出规则，最后给出 5 个可以直接复制的示例。还不熟悉 Claude Code 的话，先看《Claude Code 教程：2026 Claude Code 安装与使用指南》。

---

Claude Code Hooks 是什么

官方的定义是：Hooks 是用户自定义的 Shell 命令，Claude Code 在生命周期的特定节点运行它们，让你获得确定性的控制——某些操作一定会发生，而不是依赖大模型自己决定要不要做。

Hooks 和 CLAUDE.md 的区别

对比项	CLAUDE.md	Hooks
本质	给 Claude 读的说明	自动执行的命令
是否一定生效	不一定，Claude 可能忽略	一定，到时机就执行
适合	编码规范、项目约定	格式化、拦截危险操作、通知、日志

经验法则：希望 Claude 遵守的写进 CLAUDE.md，必须执行或必须拦截的用 Hooks。CLAUDE.md 的写法见《CLAUDE.md 怎么写？Claude Code 项目记忆配置指南》。

---

Claude Code Hooks 常用事件

Claude Code 支持几十种事件，最常用的是这些：

事件	触发时机	能否阻止
PreToolUse	工具调用执行之前	能，可以拦截这次调用
PostToolUse	工具调用成功之后	不能撤销，但可以把反馈告诉 Claude
UserPromptSubmit	你提交提示词、Claude 处理之前	能
Notification	Claude Code 发出通知时（如等待你确认）	—
Stop	Claude 完成回复时	能，让 Claude 继续工作
SessionStart	会话开始、恢复或压缩之后	不能，但输出会加入上下文
PreCompact / PostCompact	上下文压缩前后	PreCompact 能阻止压缩
SubagentStart / SubagentStop	子代理启动 / 结束时	SubagentStop 能

---

Claude Code Hooks 配置方法

配置文件放在哪里

位置	生效范围
~/.claude/settings.json	你的所有项目
.claude/settings.json	当前项目，可以提交到 Git 与团队共享
.claude/settings.local.json	当前项目，仅自己使用
组织托管设置	整个组织

此外，插件、Skill 和子代理的配置里也可以定义只在各自范围内生效的 Hooks。

配置结构

结构是"事件 → matcher 分组 → 处理器列表"：

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

处理器的 type 除了最常用的 command（执行 Shell 命令），还有 http（向 URL 发 POST 请求）、mcp_tool（调用 MCP 工具）、prompt（让模型做一次判断）和实验性的 agent。command 类型默认超时 600 秒，可以用 timeout 调整。

用 /hooks 查看已配置的 Hooks

在会话中输入 /hooks，可以浏览所有已配置的 Hooks，并看到每一条来自用户设置、项目设置还是插件。这个界面是只读的，增删 Hooks 需要直接编辑 settings 文件。想临时关闭全部 Hooks，在设置里加 "disableAllHooks": true。

---

matcher 怎么写

写法	含义
"*"、"" 或不写	匹配全部
"Bash"	只匹配 Bash 工具
"Edit|Write" 或 "Edit, Write"	匹配多个工具
"mcp__github__.*"	匹配 github 这个 MCP 服务器的全部工具
"^Notebook"	含特殊字符时按正则表达式匹配

注意 MCP 工具的名称格式是 mcp__<服务器>__<工具>，匹配整个服务器时必须加 .*，只写 mcp__github 匹配不到任何工具。MCP 的配置方法见《Claude Code MCP 怎么配置？2026 Claude Code MCP 配置教程》。

SessionStart 的 matcher 是触发来源：startup、resume、clear、compact；UserPromptSubmit、Stop 等事件不支持 matcher，写了也会被忽略。

---

Hooks 的输入与输出

输入：从 stdin 读取 JSON

Claude Code 会把事件信息以 JSON 形式传给命令的标准输入，常用字段包括 session_id、cwd、hook_event_name，工具类事件还有 tool_name 和 tool_input。例如 PreToolUse 拦截 Bash 时收到：

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

在脚本里用 jq 取字段即可，项目根目录可以通过环境变量 $CLAUDE_PROJECT_DIR 获取。

输出：退出码决定结果

退出码	含义
0	成功，操作继续；部分事件（如 SessionStart、UserPromptSubmit）的标准输出会加入 Claude 的上下文
2	阻止操作；标准错误输出会作为原因反馈给 Claude
其他	非阻塞错误，操作继续执行

特别注意：退出码 1 不会阻止操作，想拦截必须用退出码 2。

输出：用 JSON 精细控制

需要更精细的控制时，退出码为 0 并输出 JSON。例如在 PreToolUse 中拒绝一次调用并告诉 Claude 原因：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

permissionDecision 可选 allow、deny、ask，多个 Hooks 结论不同时，优先级为 deny > ask > allow。

---

5 个实用 Claude Code Hooks 示例

示例一：改完文件自动格式化

写入 .claude/settings.json，每次 Claude 编辑或新建文件后自动运行 Prettier：

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

示例二：禁止修改敏感文件

新建 .claude/hooks/protect-files.sh：

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

执行 chmod +x .claude/hooks/protect-files.sh，再注册到 PreToolUse：

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

示例三：需要确认时弹出桌面通知

Claude 在等你批准权限或回复时，弹出系统通知，不用一直盯着终端。Linux 写法：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

macOS 把 command 换成 osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"' 即可（写进 JSON 时双引号需要转义）。

示例四：记录 Claude 执行过的命令

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

示例五：上下文压缩后重新提醒关键规则

长会话压缩之后，部分细节可能丢失。用 SessionStart 配合 compact matcher，在压缩后重新注入关键信息：

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

---

用 Hooks 节省 Claude Code Token

Hooks 也是省 Token 的利器：让 PreToolUse Hook 改写测试命令，只保留 FAIL、ERROR 附近的输出，Claude 不用读几千行日志，上下文能从几万 Token 降到几百 Token。更多方法见《Claude Code Token 消耗太快？10 个 Claude Code 省 Token 技巧》。

---

Claude Code Hooks 安全注意事项

• Hooks 以你的用户权限执行任意命令，添加别人提供的 Hooks 前务必读懂脚本内容；
• 多个 Hooks 会并行执行，一个返回 deny 不会阻止其他 Hooks 运行；
• PostToolUse 无法撤销已经执行的操作，需要拦截就用 PreToolUse；
• 需要硬性允许或禁止某类操作时，优先使用权限规则（permissions.allow / permissions.deny），Hooks 作为补充。

---

常见问题 (FAQ)

Q: Claude Code Hooks 配置在哪个文件？

答： 写在 settings 文件的 hooks 字段中：~/.claude/settings.json 对所有项目生效，.claude/settings.json 对当前项目生效并可提交到 Git，.claude/settings.local.json 只对自己生效。

Q: Hook 怎么阻止 Claude 执行某个操作？

答： 在 PreToolUse 事件的脚本中以退出码 2 退出，并把原因写到标准错误输出，Claude Code 会拦截这次工具调用并把原因反馈给 Claude；退出码 1 不会阻止操作。

Q: matcher 怎么同时匹配多个工具？

答： 用竖线或逗号分隔工具名，例如 Edit|Write；匹配某个 MCP 服务器的全部工具时写成 mcp__服务器名__.，末尾的 . 不能省略。

Q: 怎么查看当前生效的 Hooks？

答： 在 Claude Code 会话中输入 /hooks，可以浏览所有已配置的 Hooks 及其来源；需要临时关闭全部 Hooks 时，在设置中加入 disableAllHooks 为 true。

Q: Hooks 和 CLAUDE.md 应该怎么分工？

答： 希望 Claude 理解和遵守的规范写进 CLAUDE.md，必须每次都执行或必须拦截的动作，例如格式化、保护敏感文件、发送通知，用 Hooks 实现。