hooks 是什么

当 Claude Code 编辑文件、完成任务或需要输入时自动运行 shell 命令。格式化代码、发送通知、验证命令并强制执行项目规则。

你可以把 hook 理解成一条规则：

1. 某个事件发生
2. 匹配某个工具或场景
3. 自动执行一个动作

这些动作可以是：

• shell command
• HTTP webhook
• prompt 型判断
• agent 型评估

hooks 最大的价值，是把“你本来每次都要手动做的检查”变成自动流程。

常见配置位置

• ~/.claude/settings.json：用户级，对所有项目生效
• .claude/settings.json：项目级，适合团队共享
• .claude/settings.local.json：本地项目配置，不建议提交
• plugin 内的 hooks/hooks.json
• 某些 skill / subagent frontmatter 内的 component-scoped hooks

---

基本结构

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

关键字段说明

字段	作用	示例
hooks	hook 顶层配置入口	{ "PreToolUse": [...] }
matcher	匹配工具名或模式	"Write"、"Edit|Write"、"*"
type	hook 类型	"command"、"http"、"mcp_tool"、"prompt"、"agent"
command	执行的 shell 命令	"$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"
timeout	超时秒数	30
once	每会话只跑一次	true

注意：这些字段属于配置协议的一部分，不要为了中文化把它们翻掉。

---

matcher 怎么用

形式	含义	例子
精确匹配	只匹配某个工具	"Write"
正则匹配	匹配多个工具	`"Edit
全匹配	匹配全部工具	"*" 或 ""
MCP 工具模式	匹配 MCP 工具	"mcp__memory__.*"

如果你配的是 InstructionsLoaded，它还有几种常见 matcher 值：

matcher 值	含义
session_start	会话刚启动时加载的 instructions
nested_traversal	向下遍历目录时加载的 instructions
path_glob_match	通过 path glob 匹配加载的 instructions

如果你不确定先配什么，最常见的起点是：

• Bash
• Write
• Edit|Write

---

五种 hook 类型

1. command（本地命令）

最常见的类型。适合：

• shell 校验
• 安全扫描
• 自动格式化
• 日志记录

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

2. http（HTTP 调用）

适合把事件发给 webhook 或外部系统。

{
  "type": "http",
  "url": "https://example.com/hook"
}

常见用途：

• 通知系统
• 团队消息流
• 外部审计系统

3. mcp_tool（MCP 工具调用）

这是上游在 v2.1.118 明确补进来的 hook 类型，适合：

• 你已经把验证逻辑做成 MCP server
• 不想每次再绕一层 shell
• 希望 hook 直接调用 MCP tool

典型配置会直接指定：

• server
• tool

而不是本地 command 或远程 url。

4. prompt（提示词）

让模型根据 prompt 判断是否该继续，常见于：

• 任务完成检查
• 结束前质量判断
• prompt 合规性判断

5. agent（代理）

让 Claude 用独立 agent 做更复杂的评估，适合：

• 架构规则检查
• 多步验证
• 比较复杂的质量门禁

---

常见事件

当前最值得先掌握的事件：

事件	什么时候触发	最常见用途
PreToolUse	工具执行前	校验、阻止、改输入
PostToolUse	工具执行后	验证、补上下文、记录
Setup	每个 session 的一次性初始化阶段	安装依赖、准备工具、生成临时环境
UserPromptSubmit	用户提交 prompt 时	prompt 校验
Stop / SubagentStop	Claude / subagent 结束时	完成度判断
SessionStart / SessionEnd	会话开始 / 结束	初始化、清理、日志

更完整的生态还包括：

• PermissionRequest
• PermissionDenied
• PostToolUseFailure
• UserPromptExpansion
• PostToolBatch
• Notification
• TaskCreated
• TaskCompleted
• CwdChanged
• WorktreeCreate
• WorktreeRemove

---

在 .claude/settings.json 里加入：

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.sh\""
          }
        ]
      }
    ]
  }
}

在 hooks中添加脚本：

mkdir -p ~/.claude/hooks
cp security-scan.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/security-scan.sh