使用 hooks 自动化操作

​

设置你的第一个 hook

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

你可以自动化什么

​

在 Claude 需要输入时获得通知

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

osascript -e 'display notification "test"'

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

notify-send 'Claude Code' 'test'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

编辑后自动格式化代码

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

​

阻止对受保护文件的编辑

#!/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

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

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

​

压缩后重新注入上下文

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

​

审计配置更改

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

当目录或文件更改时重新加载环境

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

自动批准特定权限提示

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Hooks 如何工作

• "type": "http"：将事件数据 POST 到 URL。请参阅 HTTP hooks。
• "type": "mcp_tool"：在已配置的 MCP 服务器上调用工具。请参阅 MCP tool hooks。
• "type": "prompt"：单轮 LLM 评估。请参阅 Prompt-based hooks。
• "type": "agent"：具有工具访问权限的多轮验证。Agent hooks 是实验性的，可能会改变。请参阅 Agent-based hooks。

​

合并来自多个 hooks 的结果

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

读取输入并返回输出

​

Hook 输入

• hook_event_name：触发 hook 的事件
• tool_name：Claude 即将使用的工具
• tool_input：Claude 传递给工具的参数。对于 Bash，其 command 字段包含 shell 命令。

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

​

Hook 输出

#!/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 hook，Claude Code 会将其 视为纯文本 的 stdout 添加到 Claude 的上下文中。
• 退出 2：将原因写入 stderr。根据事件的不同，Claude 会将其作为反馈接收以便进行调整，或者向用户显示，或者不显示任何消息（如 ConfigChange 和 Elicitation）。某些事件无法被阻止：对于 SessionStart 等事件，退出 2 会向用户显示 stderr，并继续执行。有关完整列表，请参阅 每个事件的退出码 2 行为。
• 任何其他退出码：有关每个事件的例外情况（例如 WorktreeCreate 在任何非零退出时都会失败），请参阅 退出码输出。对于其他事件，除非该 hook 属于失败时会阻止操作的 hook，否则请根据 hook 打印到 stdout 的内容找到对应的情况：
  • 通过 schema 验证的已解析对象：Claude Code 忽略退出码，仅由 JSON 决定结果，hook 不会被报告为错误。
  • 未通过 schema 验证的已解析对象，或 Claude Code 尝试解析为 JSON 但不是有效 JSON 的 stdout：操作作为非阻止错误继续进行。请查看 <hook name> hook error 通知中的验证或解析消息。
  • Claude Code 视为纯文本 的 stdout，或空 stdout：操作作为非阻止错误继续进行。会话记录显示 <hook name> hook error 通知，然后是 stderr 的第一行，前缀为 Failed with non-blocking status code:。要捕获完整的 stderr，请使用 claude --debug 或在会话中运行 /debug 启用 调试日志。

​

结构化 JSON 输出

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

• 从 网络路径 读取
• 标记为 requiresUserInteraction 的 MCP 工具
• 在该设置到达 Claude Code 的会话中，您的组织设置为 ask 的连接器工具 有关 "allow" 在计划模式下的作用，请参阅 计划模式下的 hook 批准。

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

使用匹配器过滤 hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

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

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

使用 if 字段按工具名称和参数过滤

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

​

配置 hook 位置

​

基于提示的 hooks

• "ok": true：操作继续
• "ok": false：发生的情况取决于事件：
  • Stop 和 SubagentStop：reason 被反馈给 Claude，以便它继续工作，除非响应也设置 "impossible": true 来标记该条件为永远无法满足的条件，在这种情况下 Claude Code 允许停止并且该轮次结束
  • PreToolUse：工具调用被拒绝；默认情况下该轮次结束，拒绝 reason 在聊天中显示为警告行。在 hook 上设置 continueOnBlock: true 以改为将 reason 作为工具错误返回给 Claude，以便它可以调整并继续
  • PostToolUse：默认情况下该轮次结束，reason 在聊天中显示为警告行。设置 continueOnBlock: true 以将 reason 反馈给 Claude 并继续该轮次
  • PostToolBatch、UserPromptSubmit 和 UserPromptExpansion：该轮次结束，reason 在聊天中显示为警告行

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

基于代理的 hooks

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

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

• 2xx 状态：要阻止工具调用，请在响应体中返回相应的 hookSpecificOutput 字段。
• 任何其他状态，或请求失败：Claude Code 会报告非阻塞错误并允许操作继续。要让失败的端点阻止该操作，请在 hook 上设置 onFailure: "block"。

​

限制和故障排除

​

限制

• 命令 hooks 仅通过 stdout、stderr 和退出代码通信。它们无法触发 / 命令或工具调用。通过 additionalContext 返回的文本被注入为 Claude 作为纯文本读取的系统提醒。HTTP hooks 改为通过响应体通信。
• Hook 超时因类型而异。通过 timeout 字段（以秒为单位）按 hook 覆盖。
  • command、http、mcp_tool：10 分钟。Claude Code 对 UserPromptSubmit、PreModelSwitch 和 PostModelSwitch hooks 将此默认值降低到 30 秒，对 MessageDisplay 降低到 10 秒。
  • prompt：30 秒。
  • agent：60 秒。
  • SessionEnd 任何类型的 hooks 共享 1.5 秒的预算。如果你的设置为每个 hook 设置了更长的 timeout，Claude Code 会将预算提高到匹配，最多 60 秒。
• PostToolUse hooks 无法撤销操作，因为工具已经执行。
• PermissionRequest hook 在 Claude Code 即将向您请求权限时触发，或在它原本会自动拒绝无法显示提示的调用时触发。在带 -p 标志的非交互模式中，它们在 dontAsk 模式之外仍会运行，而没有 hook 做出决策且无其他方式可以应答的调用会被拒绝。
• Stop hooks 在 Claude 完成响应时触发，而不仅仅在任务完成时。它们不在用户中断时触发。API 错误触发 StopFailure 代替。
• 当多个 PreToolUse hooks 返回 updatedInput 来重写工具的参数时，最后完成的获胜。由于 hooks 并行运行，顺序是非确定性的。避免有多个 hook 修改同一工具的输入。

​

Hooks 和权限模式

• 对 "allow" 仍然有效的限制：返回 "allow" 的 hook 不会绕过设置中的拒绝规则，并且在以下情况下也无法抑制提示：
  • 从网络路径读取
  • 标记为 requiresUserInteraction 的 MCP 工具
  • 在该设置会传达到 Claude Code 的会话中，您的组织设置为 ask 的连接器工具

• "deny" 在每种权限模式下都有效：返回 permissionDecision: "deny" 的 hook 会阻止工具，即使在 bypassPermissions 模式或使用 --dangerously-skip-permissions 时也是如此。PreToolUse hook 在任何权限模式检查之前触发，在每个权限模式中，包括 dontAsk。这让您能够强制执行用户无法通过更改其权限模式来绕过的策略。

​

Hook 未触发

• 运行 /hooks 并确认 hook 出现在正确的事件下
• 对于 skill frontmatter 中的 hook，请调用该 skill 或让 Claude 调用它，然后再次运行 /hooks。/hooks 不会列出会话中尚未调用的 skill 中的 hook。如果 /hooks 仍未列出该 hook，请检查其他原因，例如未能解析的 frontmatter 或某项 skill hook 的限制
• 检查匹配器模式是否与工具名称完全匹配。匹配器区分大小写
• 验证你是否触发了正确的事件类型：PreToolUse 在工具执行前触发，PostToolUse 在之后触发。PermissionRequest hook 在 Claude Code 即将要求你获得权限时触发；有关非交互模式情况，请参阅限制

​

Hook 输出中的错误

• 你的脚本意外以非零代码退出。通过管道传递示例 JSON 来手动测试它：
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• 如果你看到”command not found”，使用绝对路径或 ${CLAUDE_PROJECT_DIR} 来引用脚本。为了完全避免 shell 引用，添加 "args": [] 来切换到 exec 形式，它直接生成脚本而不使用 shell
• 如果你看到”jq: command not found”，安装 jq 或使用 Python/Node.js 进行 JSON 解析
• 如果消息包含 blocking because Git Bash wasn't found，说明您使用的是 Windows，Claude Code 未找到 Git Bash，并且失败或超时的 hook 阻止了该工具调用。有关修复方法，请参阅在没有 Git Bash 的 Windows 上失败的 hook
• 如果通知显示 JSON 验证消息，你的 hook 的 stdout 解析为 JSON 但未通过架构验证。如果显示 JSON 解析消息，stdout 看起来像 JSON 对象但不是有效的 JSON。即使在退出 0 时也会发生两者。 要修复解析失败，使用 JSON 编码器（如 jq）而不是字符串连接来构建有效负载，以便值内的引号和反斜杠被转义。参考的退出代码输出部分涵盖了退出代码和 JSON 组合
• 如果脚本根本没有运行，使其可执行：chmod +x ./my-hook.sh

​

/hooks 显示未配置 hooks

• 文件编辑通常会自动拾取。如果几秒钟后它们还没有出现，文件监视器可能错过了更改：重新启动你的会话以强制重新加载。
• 验证你的 JSON 有效：不允许尾随逗号和注释
• 确认设置文件在正确的位置：.claude/settings.json 用于项目 hooks，~/.claude/settings.json 用于全局 hooks
• 如果菜单显示 Only hooks from managed settings run here，说明您的组织设置了 allowManagedHooksOnly。您的用户、项目和本地设置文件中的 hook 不会运行，也不会列出

​

Stop hook 达到阻止上限

#!/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

​

Hook JSON 无效果

• JSON 前面有额外输出：有其他内容先写入了 stdout，通常是您的 shell profile 中无条件的 echo，导致输出不再以 { 开头。请参阅 JSON 之前的 shell profile 输出。
• 字段位于错误的层级：将每个字段的位置与 JSON 输出格式进行比较。例如，permissionDecision 应位于 hookSpecificOutput 内部，而不是顶层。请参阅字段位于错误的层级。

​

JSON 之前的 shell profile 输出

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# 在 ~/.zshrc 或 ~/.bashrc 中
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

字段位于错误的层级

​

检查 hook 的执行结果

• 成功：您看不到任何内容，除非 hook 的 JSON 显示了某些内容，例如 systemMessage 或 Stop hook 反馈。
  • 要确认 hook 已运行，请检查其效果，例如被重新格式化的文件
• 阻止错误：在大多数事件上，您会看到随阻止一起返回的消息，例如 Blocked: rm commands are not allowed。在少数事件上，例如 ConfigChange 和 Elicitation，您不会看到消息。退出码 2 介绍了该消息的来源。
• 非阻止错误：您会看到 <hook name> hook error 通知，其中包含简短说明，例如 Failed with non-blocking status code: 之后的 stderr 第一行，或 JSON 验证或解析消息。操作会继续进行。

​

了解更多

• Hooks 参考：完整的事件架构、JSON 输出格式、异步 hooks 和 MCP 工具 hooks
• 安全考虑：在共享或生产环境中部署 hooks 之前查看
• Bash 命令验证器示例：完整的参考实现