钩子系统参考

原文：Hooks reference

一句话

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

什么时候翻这页

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

核心概念

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

怎么做

钩子配置结构

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

基本配置示例

{
  "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

命令 / 配置速查

钩子位置与作用域

常用钩子事件

钩子处理器类型

初学者易错点

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

相关词条

• hooks-guide 钩子快速入门指南
• settings Claude Code 配置系统
• permissions 权限控制系统
• mcp 模型上下文协议工具集成
• agent-teams 代理团队协作
• plugins 插件系统扩展