Claude Code Hooks 用法

Claude Code Hooks 是在 Agent 生命周期特定点自动执行的确定性脚本，用于自动化工作流、安全门控和环境管理。与 CLAUDE.md 的”建议性”指令不同，Hook 保证每次都执行。

概述

Hook 的配置遵循三层嵌套：事件名（何时触发）→ 匹配器（过滤条件）→ 处理器（执行什么）。支持 20+ 种事件类型，覆盖会话、工具、代理三个级别。

用法

配置位置

位置	作用域
`~/.claude/settings.json`	所有项目
`.claude/settings.json`	当前项目（可提交 Git）
`.claude/settings.local.json`	当前项目（不提交）
Plugin `hooks/hooks.json`	插件范围
Skill/Agent frontmatter	特定 Skill/Agent 活跃期间

基本配置结构

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/check.sh"
          }
        ]
      }
    ]
  }
}

核心事件

事件	时机	能否阻断
`PreToolUse`	工具执行前	是（exit 2）
`PostToolUse`	工具成功后	是（decision: block）
`PermissionRequest`	权限弹窗时	是（allow/deny）
`Stop`	Claude 完成回复	是（阻止结束）
`SessionStart`	会话开始/恢复	否
`Notification`	需要注意力	否
`FileChanged`	监控的文件变更	否
`SubagentStart/Stop`	SubAgent 生命周期	否

处理器类型

类型	说明	适用
`command`	Shell 命令（stdin 接收 JSON）	最常用
`http`	POST 请求	集成外部服务
`prompt`	单轮 LLM 评估	需要语义判断
`agent`	启动 SubAgent 验证	复杂验证

退出码

码	效果
0	成功，处理 JSON 输出
2	阻断操作
其他	非阻断错误

常用示例

阻止危险命令：

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo "Blocked dangerous command" >&2
  exit 2
fi
exit 0

编辑后自动格式化：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{"type": "command", "command": "npx prettier --write \"$TOOL_INPUT_FILE\""}]
    }]
  }
}

桌面通知：

{
  "hooks": {
    "Notification": [{
      "matcher": "idle_prompt",
      "hooks": [{"type": "command", "command": "osascript -e 'display notification \"Claude 完成了\" with title \"Claude Code\"'"}]
    }]
  }
}

注意事项

Hook 的 stdout 必须只包含 JSON，shell profile 启动文本会导致解析失败
HTTP Hook 的失败是非阻断的（连接错误不会阻止操作）
可用 /hooks 命令查看已配置的 Hook
disableAllHooks: true 可临时禁用所有 Hook
企业管理策略的 disableAllHooks 不能被用户覆盖

版本说明

本页面基于 2026 年 3 月 Claude Code 文档。事件类型和配置格式可能随版本变化。

参见

Hook — Hook 作为通用概念
Claude Code — Claude Code 整体架构
claude-code-extension-system — 扩展体系速查