钩子系统参考

原文：Hooks reference

一句话

在 Claude Code 生命周期特定节点自动执行自定义命令、HTTP 端点或 LLM 提示。

什么时候翻这页

需要在工具执行前/后自动运行脚本
想要拦截或修改 Claude 的某些行为
需要根据文件变化自动触发操作
想要配置 MCP 工具的交互流程

核心概念

钩子事件（hook events）：Claude Code 生命周期中的特定触发点，如 PreToolUse（工具使用前）、PostToolUse（工具使用后）
匹配器（matcher）：过滤钩子何时触发的条件，如只对特定工具名称生效
钩子处理器（hook handlers）：实际执行的命令、HTTP 端点、MCP 工具或提示
异步钩子（async hooks）：在后台运行而不阻塞 Claude 执行的钩子
决策控制（decision control）：钩子可以决定是否允许或阻止某些操作

怎么做

钩子配置结构

选择钩子事件（如 PreToolUse）
添加匹配器组（如 "Bash" 只匹配 Bash 工具）
定义一个或多个钩子处理器（如命令脚本）

基本配置示例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

钩子处理器编写

#!/bin/bash
# 从 stdin 读取 JSON 输入
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  # 返回拒绝决策
  jq -n '{
    hookSpecificOutput: {
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked"
    }
  }'
else
  exit 0  # 无决策，继续正常流程
fi

命令 / 配置速查

钩子位置与作用域

位置	作用域	是否可共享
`~/.claude/settings.json`	所有项目	否，仅限本地机器
`.claude/settings.json`	单个项目	是，可提交到仓库
`.claude/settings.local.json`	单个项目	否，会被 git 忽略
管理策略设置	组织范围	是，管理员控制
插件 `hooks/hooks.json`	插件启用时	是，随插件分发

常用钩子事件

事件	触发时机
`SessionStart`	会话开始或恢复时
`UserPromptSubmit`	用户提交提示后，Claude 处理前
`PreToolUse`	工具调用执行前
`PostToolUse`	工具调用成功后
`Stop`	Claude 完成响应后
`SessionEnd`	会话终止时

钩子处理器类型

类型	描述	适用场景
`command`	执行 shell 命令	文件操作、API 调用、自定义脚本
`http`	发送 HTTP 请求	与 Web 服务集成
`mcp_tool`	调用 MCP 工具	与模型上下文协议工具交互
`prompt`	发送 LLM 提示	基于语言模型的决策
`agent`	启动代理验证	需要多轮工具访问的复杂验证

初学者易错点

忽略匹配器：忘记添加匹配器会导致钩子对所有事件触发，影响性能
路径问题：使用相对路径可能导致钩子找不到脚本，推荐使用 ${CLAUDE_PROJECT_DIR}
JSON 格式错误：钩子输出的 JSON 必须严格格式正确，否则可能导致解析失败
超时设置：长时间运行的钩子应设置适当的超时，避免阻塞 Claude
安全风险：命令钩子拥有系统完整权限，应谨慎处理用户输入

语义检索

钩子系统参考

一句话

什么时候翻这页

核心概念

怎么做

钩子配置结构

基本配置示例

钩子处理器编写

命令 / 配置速查

钩子位置与作用域

常用钩子事件

钩子处理器类型

初学者易错点

相关词条