Claude Code Hooks 介绍

发布时间： 更新时间： 总字数：1629 阅读时间：4m 作者：IP：上海 网址

在 Claude Code (CLI) 中，Hooks（钩子） 是一个非常强大的机制，允许在 Agent 运行生命周期的特定关键点自动执行自定义逻辑。本文总结的分类表格以及详细的使用示例。

介绍

Claude Code 的 Hooks 由两个核心维度组成：处理程序类型 (Handler Types)（即 Hook 的运行方式）和 生命周期事件 (Lifecycle Events)（即什么时候触发 Hook）。所有 Hooks 都在 ~/.claude/settings.json（全局）或项目下的 .claude/settings.json 中配置。

Hook 处理程序类型 (Handler Types)

这决定了 Hook 被触发后，将以什么方式来执行你的逻辑。

类型 (type) 描述 适用场景与特性
command 执行一段 Shell 命令或脚本。 最常用。接收标准输入（JSON 格式），通过退出码（Exit 0 允许，Exit 2 阻断）控制流程。
prompt 触发一次单轮大模型 (LLM) Prompt 评估。 适合需要模糊判断的轻量级检查。例如：“检查这段命令是否安全”。
agent 唤起一个有工具使用权限的子 Agent (Subagent) 进行多轮任务。 适合复杂的深度验证。例如：“验证新写的代码是否都被测试覆盖，若没有则不许停止”。
http 将事件数据的 JSON 通过 POST 请求发送给外部 Webhook。 适合将事件流式传输到外部监控平台或触发外部 CI/CD 管道。
mcp_tool 直接调用已连接的 MCP (Model Context Protocol) 服务器中的工具。 适合与外部系统（如 Jira、Slack 或本地特殊工具）进行确定性交互。

核心生命周期事件 (Lifecycle Events)

有将近 30 种事件，以下是最常用的 6 个核心事件：

事件名称 (Event) 触发时机 是否可阻断 Agent？ 典型使用场景
PreToolUse Claude 决定调用某个工具（如编辑文件、执行命令）之前。 ✅ 可阻断 (Exit 2) 安全审查：阻止读取 .env 敏感文件，或拦截危险的 rm -rf 命令。
PostToolUse 工具成功调用执行之后。 ❌ 不可阻断 (已执行) 自动化：在 Claude 写入文件后立即执行 Prettier/gofmt 格式化、Lint 检查。
PermissionRequest Claude 请求用户授权（如执行 Bash 之前）时。 ✅ 可阻断 / 自动放行 权限控制：针对特定只读命令自动放行，减少开发过程中的手动点击打断。
Stop Claude 认为任务已完成，准备停止会话前。 ✅ 可阻断 (Exit 2) 质量门禁：检查单元测试是否全部通过，若没通过则拒绝停止并要求它修复。
SessionStart 会话刚启动或恢复时。 ❌ 仅注入上下文 上下文注入：自动读取最新的项目开发规范、当前 Git 状态并喂给 Claude。
Notification Claude 需要用户输入或发出通知时。 ❌ 仅用于通知 系统集成：给你的电脑发系统弹窗，或发送 Slack 消息通知你“它卡住了”。

使用示例

可以通过在项目根目录下创建/修改 .claude/settings.json 来配置 Hooks。Claude Code 具有一套强大的 matcher 机制，用于精确匹配触发 Hook 的工具名称（如 Bash, Write, Edit 等）。

示例 1：代码自动化（修改后自动格式化）

使用 command 类型和 PostToolUse 事件。每次 Claude 编辑（Edit）或写入（Write）文件后，静默执行代码格式化，不需要人工干预。

json 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE_PATH=$(jq -r '.tool_input.file_path'); if [[ \"$FILE_PATH\" == *.ts || \"$FILE_PATH\" == *.js ]]; then npx prettier --write \"$FILE_PATH\"; fi"
          }
        ]
      }
    ]
  }
}

注释：Claude 会将 JSON 事件数据传递给 Hook 的 stdin，这里用 jq 解析出了被修改的文件路径并对其执行 prettier。

示例 2：安全防护（拦截危险或敏感操作）

使用 command 类型和 PreToolUse 事件。如果在工具使用之前退出码为 2（Exit 2），Claude Code 会直接阻断操作并将 stderr 作为错误告诉 AI。

json 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.tool_input.file_path'); if [[ \"$FILE\" == *\".env\"* ]]; then echo '禁止读取或修改环境变量敏感文件！'; exit 2; else exit 0; fi"
          }
        ]
      }
    ]
  }
}

注释：当 AI 尝试读取或修改 .env 时，脚本会执行 exit 2。AI 会收到阻断信息，从而彻底保护了你的 Secret 环境。

示例 3：通过 Webhook 发送通知

使用 http 类型和 Notification 事件。如果你离开座位让 Claude 自动处理长任务，当它卡住需要你的确认时，发请求到你配置的后端/Webhook。

json 
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook-endpoint.com/claude-notify"
          }
        ]
      }
    ]
  }
}

示例 4：大模型质量门禁（Agent类型）

使用 agent 类型和 Stop 事件。当 AI 认为自己写完代码准备“交差”时，启动一个挂载了验证工具的子代理检查它。

json 
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "agent",
            "prompt": "请使用 Bash 工具运行 `npm test`，如果发现任何测试失败，请阻止停止（block），并要求主 Agent 修复失败的测试用例。"
          }
        ]
      }
    ]
  }
}
  • 注释：这是 Claude Code 最独特的功能之一，能利用大模型的自省能力防止 AI “半途而废”。如果子代理发现测试没过，主 Agent 将被迫继续干活。*
最新评论