Claude Code Hooks 完全指南：用 Shell 命令精准控制 AI 行为

本文是对官方文档 https://code.claude.com/docs/en/hooks-guide 的中文要点摘要,完整内容以原文为准。

什么是 Hooks

Hooks 是用户自定义的 Shell 命令,在 Claude Code 工作流的特定节点自动触发。与依赖 LLM「自己决定是否运行某个工具」不同,Hooks 提供确定性控制——无论 AI 怎么判断,该执行的操作一定会执行。

典型用途:

• 每次文件保存后自动运行 prettier / black 格式化
• Claude 等待输入时发送桌面通知
• 拦截危险的 rm -rf 类命令
• 每次任务结束后运行测试套件
• 将 Claude 的操作日志发送到外部系统

需要更灵活判断的场景,还可以用 prompt-based hooks(让 Claude 模型评估条件)或 agent-based hooks(派生子 Agent 执行复杂验证)。

Hook 事件类型

PreToolUse 是最常用的拦截点,可以在此阻止危险命令或不合规操作。

配置格式

Hooks 配置写在 settings.json 的 hooks 字段中:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validator.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

关键字段说明:

• matcher:按工具名过滤,支持正则,多个用 | 分隔;不填则匹配所有
• type:command(Shell)、http(HTTP 回调)、mcp_tool(MCP 工具)、prompt(模型判断)、agent(子 Agent)
• timeout:超时秒数
• if:条件表达式,使用权限规则语法进一步过滤

退出码与 JSON 输出

Hook 脚本通过退出码和 stdout JSON 控制 Claude 的行为:

不同事件对 exit 2 的处理不同:PreToolUse 会阻止该工具调用、UserPromptSubmit 会阻断并清除该 prompt、Stop/SubagentStop 会阻止停止并让 Claude 继续。而 PostToolUse(工具已经执行完毕,无法回退)、SessionStart、Notification、SessionEnd 等事件无法被 exit 2 阻断,此时只会把 stderr 展示给 Claude 或用户并继续。

若需要更精细的控制,可以改为 exit 0 并向 stdout 打印 JSON(注意:exit 2 时 Claude Code 会忽略 JSON,二者不要混用)。对于支持阻断的 Stop、SubagentStop、UserPromptSubmit 等事件,可用顶层的 decision 字段并配 reason 反馈原因:

{
  "decision": "block",
  "reason": "禁止删除生产环境文件"
}

不同事件使用不同的决策字段:PreToolUse 用 hookSpecificOutput.permissionDecision(取值 allow/deny/ask 等)。完整对照见参考文档的决策控制表。

Prompt-Based 与 Agent-Based Hooks

Prompt-based hooks 不执行固定脚本,而是把 Hook 事件上下文连同你的 prompt 发送给 Claude 模型(可用 model 字段指定所用模型),让模型做单轮判断:

{
  "type": "prompt",
  "prompt": "检查即将执行的命令是否可能损坏生产数据库。如果风险高,拒绝执行。"
}

模型只需返回一个放行/拒绝的 JSON 决策:放行则照常继续;拒绝则按事件类型处理——PreToolUse 会拒绝该工具调用并把 reason 作为工具报错返回给 Claude、Stop/SubagentStop 会把 reason 反馈给 Claude 让它继续工作、PostToolUse/UserPromptSubmit 等则结束本轮并把 reason 作为警告显示。

Agent-based hooks 更进一步,可以派生一个子 Agent 执行多步骤验证(如读取文件、搜索代码、运行命令),再根据结果决定是否允许操作。它复用与 prompt hooks 相同的放行/拒绝响应格式,但默认超时更长,可进行多轮工具调用。该特性目前仍属实验性,生产场景建议优先用 command hooks。

配置文件位置

实用示例

桌面通知(Notification 事件):

#!/bin/bash
osascript -e 'display notification "Claude 在等你" with title "Claude Code"'

拦截危险删除命令(PreToolUse + Bash):

#!/bin/bash
command=$(cat - | jq -r '.tool_input.command')
if [[ "$command" == rm\ -rf* ]]; then
  echo "禁止执行 rm -rf" >&2
  exit 2
fi
exit 0

自动格式化(PostToolUse + Write/Edit):

{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "prettier --write \"$CLAUDE_PROJECT_DIR\"/src"
    }]
  }]
}

提示:脚本中引用工程根目录请用官方提供的 $CLAUDE_PROJECT_DIR。

安全注意事项

• Hooks 以当前用户权限执行任意 Shell 命令,风险与执行本地脚本相同
• 只配置来源可信的 Hook 脚本,不要将 GitHub 上的 Hook 直接复制进生产配置
• 避免将 Hook 接收的 JSON 输入未经验证地拼入 Shell 命令(防止注入攻击)
• 项目级 .claude/settings.json 中的 Hooks 在所有协作者机器上都会执行,提交前需团队审核

与其他扩展机制的关系

完整事件 schema、JSON 输入输出格式、异步 Hooks、MCP 工具 Hooks 等高级特性,详见官方参考文档 Hooks reference。