钩子

钩子（Hook）是在 Claude Code 会话期间响应特定事件自动执行的脚本。它们支持自动化、验证、权限管理和自定义工作流。

概述

钩子是在 Claude Code 中发生特定事件时自动执行的操作（shell 命令、HTTP webhook、LLM 提示词（Prompt）或子代理（Subagent）评估）。它们接收 JSON 输入，并通过退出码和 JSON 输出传达结果。

核心功能：

• 事件驱动的自动化
• 基于 JSON 的输入/输出
• 支持命令、提示词、HTTP 和代理（Agent）钩子类型
• 针对特定工具的模式匹配

配置

钩子在设置文件中以特定结构配置：

• ~/.claude/settings.json — 用户设置（所有项目）
• .claude/settings.json — 项目设置（可共享，已提交）
• .claude/settings.local.json — 本地项目设置（不提交）
• 受管策略 — 组织范围的设置
• 插件（Plugin）的 hooks/hooks.json — 插件作用域的钩子
• 技能（Skill）/代理前置元数据（Frontmatter） — 组件生命周期钩子

基本配置结构

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

关键字段：

字段	描述	示例
matcher	匹配工具名称的模式（区分大小写）	"Write"、"Edit|Write"、"*"
hooks	钩子定义数组	[{ "type": "command", ... }]
type	钩子类型："command"（bash）、"prompt"（LLM）、"http"（webhook）或 "agent"（子代理）	"command"
command	要执行的 shell 命令	"$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"
timeout	可选的超时秒数（默认 60）	30
once	设为 true 则每个会话仅运行一次	true

匹配器模式

模式	描述	示例
精确字符串	匹配特定工具	"Write"
正则表达式模式	匹配多个工具	"Edit|Write"
通配符	匹配所有工具	"*" 或 ""
MCP 工具	服务器和工具模式	"mcp__memory__.*"

钩子类型

Claude Code 支持四种钩子类型：

命令钩子

默认的钩子类型。执行 shell 命令，通过 JSON stdin/stdout 和退出码进行通信。

{
  "type": "command",
  "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py\"",
  "timeout": 60
}

HTTP 钩子

在 v2.1.63 中添加。

远程 webhook 端点，接收与命令钩子相同的 JSON 输入。HTTP 钩子将 JSON POST 到 URL 并接收 JSON 响应。启用沙盒（Sandbox）时，HTTP 钩子通过沙盒路由。URL 中的环境变量插值出于安全考虑需要显式的 allowedEnvVars 列表。

{
  "hooks": {
    "PostToolUse": [{
      "type": "http",
      "url": "https://my-webhook.example.com/hook",
      "matcher": "Write"
    }]
  }
}

关键属性：

• "type": "http" — 标识为 HTTP 钩子
• "url" — webhook 端点 URL
• 启用沙盒时通过沙盒路由
• URL 中的任何环境变量插值需要显式的 allowedEnvVars 列表

提示词钩子

LLM 评估的提示词，钩子内容是 Claude 评估的提示词。主要与 Stop 和 SubagentStop 事件配合使用，用于智能任务完成检查。

{
  "type": "prompt",
  "prompt": "Evaluate if Claude completed all requested tasks.",
  "timeout": 30
}

LLM 评估提示词并返回结构化决策（详见基于提示词的钩子）。

代理钩子

基于子代理的验证钩子，生成专用代理来评估条件或执行复杂检查。与提示词钩子（单轮 LLM 评估）不同，代理钩子可以使用工具并执行多步推理。

{
  "type": "agent",
  "prompt": "Verify the code changes follow our architecture guidelines. Check the relevant design docs and compare.",
  "timeout": 120
}