用法

Claude Code Hooks 教程：怎么配置 hooks、选事件、套用现成示例

发布于 2026 年 10 月 30 日 · 最后核对 2026 年 10 月 30 日

Hooks 是用户自定义的 shell 命令，Claude Code 在生命周期的特定时刻运行它们。执行的是 hook 而不是模型，所以这个动作一定会发生。这一页是操作步骤：hook 放在哪里、一条 hook 长什么样、哪些事件最常用、四个可以直接粘贴的示例、退出码怎么拦截操作、hook 没反应时看什么。内容按 Anthropic 的 Automate actions with hooks 和 Hooks reference 中文整理，2026 年 10 月 30 日对照原文核对。

Hooks 是什么，什么时候该用

Hooks 是用户自定义的 shell 命令。Claude Code 在生命周期的特定时刻运行它们，让你获得确定性的控制：某些动作一定会发生，而不是依赖 LLM 自己决定要不要运行。可以用 hooks 来落实项目规则、自动化重复任务，以及把 Claude Code 接进你已有的工具。

Anthropic 给出的用法包括：编辑后格式化文件、在命令执行前拦截命令、Claude 需要输入时发通知、会话开始时注入上下文。需要判断而不是确定性规则的决定，指南指向 prompt hook 和 agent hook，它们用 Claude 模型来评估条件。想在每次会话开始时注入上下文，指南建议改用 CLAUDE.md。想给 Claude 额外的指令和可执行命令，见技能（skills）。

安全提醒：command hook 以你的完整用户权限执行 shell 命令，可以修改、删除或访问你的用户账号能访问的任何文件。添加到配置之前，先审查并测试所有 hook 命令。

Hooks 配置在哪里

Hooks 定义在 JSON 设置文件里。hook 加在哪里，决定了它的作用范围：

在 Claude Code 里输入 /hooks，会打开一个只读的 hooks 浏览器，列出已配置的 hooks，并标明每个 hook 的来源，例如用户设置、项目设置、本地设置、某个插件或当前会话。想停用 hooks，在设置文件里写 "disableAllHooks": true。Claude Code 运行时直接编辑设置文件，文件监视器通常会自动读取 hook 的改动。

在交互会话里，Claude Code 会先扣住所有设置文件里的 hooks，包括你自己的 ~/.claude/settings.json，直到你接受该文件夹的工作区信任对话框，或者接受某个信任范围覆盖到它的上级目录。

一条 hook 的结构

配置分三层嵌套：选一个要响应的 hook 事件，比如 PreToolUse 或 Stop；加一个 matcher 组来过滤触发时机，比如“只对 Bash 工具”；再定义匹配时要运行的一个或多个 hook handler。每个事件名都是同一个 hooks 对象里的键。下面是 Anthropic 指南里的第一个 hook，macOS 上的桌面通知：

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

如果你的设置文件里已经有 hooks 键，把新事件作为已有事件键的同级项加进去，不要替换整个对象。

内层 hooks 数组里的每个对象是一个 hook handler。大多数 hook 用 "type": "command"，运行一条 shell 命令。另外还有四种类型："type": "http"、"type": "mcp_tool"、"type": "prompt" 和 "type": "agent"。Agent hook 是实验性的，可能会变。handler 的常用字段：

Matcher 怎么写

没有 matcher 时，hook 在对应事件每次发生时都会触发。matcher 字段用来过滤触发时机，怎么求值取决于它包含哪些字符：

每种事件匹配的字段不同：PreToolUse 和 PostToolUse 匹配工具名，SessionStart 匹配会话的启动方式（startup、resume、clear、compact、fork），Notification 匹配通知类型。Matcher 区分大小写。UserPromptSubmit、Stop 等少数事件不支持 matcher，每次发生都会触发。

if 字段比 matcher 更细，matcher 只在组的层面按工具名过滤。下面这个配置只在 Claude 用 git 命令时运行 hook，而不是所有 Bash 命令：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

这个过滤是尽力而为的，所以指南说，要强制执行硬性的允许或拒绝，请用权限系统，不要用 hook。

最常用的事件

事件触发时，Claude Code 会并行运行匹配的 hooks。指南列出的事件远不止这些；下表是本页示例用到的，加上几个常见的。

四个可以直接粘贴的示例

每个都是 Anthropic 指南里现成可用的配置块。Bash 示例用 jq 解析 JSON：macOS 上用 brew install jq 安装，Debian 和 Ubuntu 上用 apt-get install jq，也可以看 jq 的下载页。

Claude 需要输入时收到通知

这个 hook 用 Notification 事件，Claude Code 在 Claude 等待输入或权限时触发它。macOS 的写法在上一节里；下面是 Linux 的，用 notify-send。加到 ~/.claude/settings.json：

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

空的 matcher 对所有通知类型都触发。只想在特定情况触发，把它设成某个通知类型，例如 permission_prompt（Claude 需要你批准一次工具使用）或 idle_prompt（Claude 大约 60 秒前回答完，之后你一直没有输入）。macOS 上没有通知时：osascript 通过内置的“脚本编辑器”（Script Editor）应用发通知，如果脚本编辑器没有通知权限，命令会静默失败。Linux 上，notify-send 需要桌面通知守护进程，无头服务器、SSH 会话和大多数容器都没有。

编辑后自动格式化代码

这个 hook 用 PostToolUse 事件加 Edit|Write matcher，所以只在文件编辑类工具之后运行。命令用 jq 取出被编辑的文件路径，再交给 Prettier。加到项目根目录的 .claude/settings.json：

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

测试方法：让 Claude 往一个 JavaScript 文件里加一行带单引号字符串的代码，然后打开文件：用 Prettier 的默认设置，hook 会把它们改成双引号。hook 成功时，Claude Code 不会在对话里显示任何东西，所以要看被编辑的文件有没有被重新格式化。Bash 命令也可能改写文件；想让某个特定文件不管怎么变化都被重新格式化，改用 FileChanged hook。

拦截对受保护文件的编辑

这个示例阻止 Claude 修改敏感文件，比如 .env、package-lock.json，或者 .git/ 里的任何东西。Claude 会收到说明编辑为什么被拦截的反馈，从而调整做法。hook 调用一个脚本，脚本拿目标文件路径和一组受保护的模式比对，并用退出码 2 拦截编辑。把脚本存成 .claude/hooks/protect-files.sh：

#!/bin/bash
# protect-files.sh

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

# Normalize Windows backslash separators so the patterns below match
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

hook 脚本必须可执行，Claude Code 才能运行它。在 macOS 和 Linux 上：

chmod +x .claude/hooks/protect-files.sh

然后在 .claude/settings.json 里加一个 PreToolUse hook，在任何 Edit 或 Write 工具调用之前运行这个脚本：

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

测试方法：让 Claude 往你的 .env 文件里加一行注释。Claude Code 会在编辑执行之前拦截它，并把脚本的 Blocked: 消息作为反馈交给 Claude。

压缩之后重新注入上下文

Claude 的上下文窗口满了以后，压缩（compaction）会把对话总结一遍来腾出空间，这可能丢掉重要细节。用带 compact matcher 的 SessionStart hook，在每次压缩之后重新注入关键上下文。你的命令写到 stdout 的纯文本，Claude Code 会加进 Claude 的上下文。加到项目根目录的 .claude/settings.json：

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

可以把 echo 换成任何会产生动态输出的命令，比如用 git log --oneline -5 显示最近的提交。

退出码，以及拦截是怎么生效的

Hooks 通过 stdin、stdout、stderr 和退出码与 Claude Code 通信。事件触发时，Claude Code 把和事件相关的数据以 JSON 传给你脚本的 stdin。对一条 Bash 命令，PreToolUse hook 收到的字段包括 session_id、cwd、hook_event_name、tool_name 和 tool_input，其中 tool_input.command 是那条 shell 命令。下面这个脚本拦截一条命令：

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

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2                                               # exit 2 = block the action
fi

exit 0  # exit 0 = no decision; the normal permission flow applies

• 退出码 0 表示成功。PreToolUse hook 退出码 0 时，这次工具调用仍然走正常的权限流程，因为退出码 0 并不等于批准。对 UserPromptSubmit、UserPromptExpansion、SessionStart 和 PostModelSwitch hooks，Claude Code 会把纯文本 stdout 加进 Claude 的上下文。对其他大多数事件，stdout 写进调试日志，不会显示在对话记录里。
• 退出码 2 在可以拦截的事件上阻止操作。把原因写到 stderr：随拦截一起给出的消息就是 hook 的 stderr。取决于事件，Claude 会把它当作反馈来调整，或者用户能看到它，或者根本不显示消息。有些事件不能拦截：对 SessionStart 等，退出码 2 只把 stderr 显示给用户，执行继续。
• 其他任何退出码是非阻塞错误：操作照常进行，但失败即拦截的 hook 除外，例如把 onFailure 设为 "block" 的 hook。在 PreToolUse 等事件上，你会在对话记录里看到一条 <hook name> hook error 提示。

退出码为 0 的 hook，Claude 永远看不到它的 stderr。想从 PostToolUse hook 向 Claude 传一条警告，改用退出码 2，这样即使工具已经运行过，Claude 也能看到 stderr。PostToolUse hook 无法撤销已经发生的动作，因为工具已经执行了。

退出码只能让你拦截或保持沉默。想要更细的控制，退出码用 0，并往 stdout 打印一个 JSON 对象。每个 hook 只选一种方式：退出码 2 加 stderr 消息来拦截，或者退出码 0 加 JSON 来做结构化控制。例如，PreToolUse hook 可以拒绝一次工具调用并告诉 Claude 原因：

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

返回 "deny" 时，Claude Code 取消这次工具调用，并把 permissionDecisionReason 反馈给 Claude。返回 permissionDecision: "deny" 的 hook，即使在 bypassPermissions 模式下或带 --dangerously-skip-permissions 时，也会拦截工具。多个 hook 匹配同一个事件时，每个 hook 的命令都会运行完，Claude Code 才合并结果，所以某个 hook 返回 deny 并不会阻止同级的其他 hook 执行。

怎么调试 hook

• 运行 /hooks，确认 hook 出现在正确的事件下面。
• 把一段示例 JSON 通过管道喂给脚本来测试，再检查退出码（命令见下方）。
• 按 Ctrl+O 打开对话记录视图，找 hook 的结果。成功时什么都看不到，除非 hook 的 JSON 带出了什么内容。阻塞错误会显示随拦截给出的消息。非阻塞错误会显示一条 <hook name> hook error 提示和一句简短说明。
• 要看完整的执行细节，包括 hook 的退出码、stdout 和 stderr，读调试日志。用 claude --debug-file /tmp/claude.log 启动 Claude Code，把日志写到一个已知路径，再在另一个终端里 tail -f /tmp/claude.log。如果启动时没加这个参数，在会话中运行 /debug 开启日志并找到日志路径。

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?  # Check the exit code

claude --debug-file /tmp/claude.log
tail -f /tmp/claude.log

常见问题排查

stop_hook_active 的检查写法如下：

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

常见问题

来源

• Claude Code：Automate actions with hooks（第一个 hook、示例、matcher、排错，2026 年 10 月 30 日核对）
• Claude Code：Hooks reference（hook 位置、handler 字段、退出码、调试、安全注意事项，2026 年 10 月 30 日核对）