Claude Code 钩子

Claude Code 钩子是用户自定义的 Shell 命令，会在 Claude Code 生命周期的特定节点自动执行。

借助钩子，你可以对 Claude Code 的行为实现精准控制，确保某些操作（如代码格式化、日志记录）必定触发，而非依赖大模型自主选择是否执行。

钩子的典型应用场景

钩子能帮你实现很多实用功能，常见场景包括：

消息通知：当 Claude Code 等待输入或需要权限时，自动发送桌面/邮件提醒
自动格式化：编辑 .ts 文件后自动运行 prettier，修改 .go 文件后执行 gofmt
操作日志：记录 Claude 执行的所有命令，用于合规审计或调试排障
代码规范校验：若 Claude 生成的代码不符合项目规范（如命名规则），自动给出反馈
文件权限管控：阻止 Claude 修改生产环境配置文件或敏感目录（如 .env、.git）

相比于通过提示词约束 Claude 的行为，钩子是应用级的硬规则，只要触发对应事件就会强制执行，稳定性和可靠性更高。

重要安全提醒

钩子运行时会直接使用当前系统环境的凭证（如环境变量、用户权限），存在一定安全风险：

恶意钩子代码可能泄露你的敏感数据（如 API 密钥、项目源码）
错误的钩子命令可能导致文件误删、系统异常

必做安全操作：

注册钩子前，务必逐行审查命令的逻辑和权限
避免在钩子中执行来源不明的脚本
详细安全最佳实践，可参考官方文档的安全注意事项

钩子事件类型说明

Claude Code 内置了多个生命周期事件，你可以为不同事件绑定钩子命令。每个事件会传递不同的上下文数据，且对 Claude 行为的影响方式不同。

事件名称	触发时机	核心作用
`PreToolUse`	工具调用之前	可拦截工具执行（如阻止修改敏感文件），并向 Claude 反馈调整建议
`PermissionRequest`	弹出权限请求对话框时	自动批准或拒绝权限申请
`PostToolUse`	工具调用完成后	执行后置操作（如格式化代码、记录日志）
`UserPromptSubmit`	用户提交提示词后、Claude 处理前	预处理用户输入（如补充上下文信息）
`Notification`	Claude 发送通知时	自定义通知方式（如桌面弹窗、短信提醒）
`Stop`	Claude 完成响应时	执行收尾工作（如清理临时文件）
`SubagentStop`	子代理任务完成时	处理子代理的执行结果
`PreCompact`	即将执行上下文压缩操作时	自定义压缩规则
`SessionStart`	启动新会话或恢复旧会话时	初始化会话环境（如加载项目配置）
`SessionEnd`	会话结束时	保存会话数据、清理环境

快速入门：实现命令日志记录

下面以 记录 Claude 执行的所有 Bash 命令 为例，带你一步步完成钩子的配置和使用。

前置准备

安装 jq 工具（用于命令行解析 JSON 数据）：

macOS：brew install jq
Linux：sudo apt install jq / sudo yum install jq
Windows：下载 jq 官方安装包，或通过 WSL 安装

步骤 1：打开钩子配置界面

在 Claude Code 的交互界面中，输入斜杠命令 /hooks，回车后选择要绑定的事件 —— 这里我们选 PreToolUse（工具调用前触发，适合记录命令）。

步骤 2：添加事件匹配器

匹配器的作用是 限定钩子的触发条件，只在指定工具被调用时执行钩子命令。

选择 + Add new matcher…
输入匹配关键词 Bash，表示仅当 Claude 调用 Bash 工具时触发钩子

小技巧：输入 * 可以匹配所有工具，实现全局钩子

步骤 3：添加钩子命令

选择 + Add new hook…，输入以下命令（功能：提取命令内容和描述，写入日志文件）：

jq -r '"\(.tool_input.command) - \(.tool_input.description // "无描述信息")"' >> ~/.claude/bash-command-log.txt

命令说明：

jq -r ...：提取 JSON 中的命令（command）和描述（description），无描述时显示"无描述信息"
>> ~/.claude/...：将内容追加写入用户主目录下的日志文件

步骤 4：选择配置存储位置

配置保存位置决定钩子的生效范围：

User settings：保存到用户级配置（~/.claude/settings.json），所有项目生效
Project settings：保存到当前项目配置（.claude/settings.local.json），仅当前项目生效

这里我们选 User settings，实现全局命令日志记录。选择后按 Esc 键退出配置界面，钩子即注册完成。

步骤 5：验证钩子配置

再次输入 /hooks 命令，可查看已配置的钩子列表

或直接打开配置文件 ~/.claude/settings.json，会看到如下配置内容：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"无描述信息\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

步骤 6：测试钩子效果

在 Claude Code 中输入指令：帮我执行 ls 命令
执行完成后，在终端中查看日志文件：
```
cat ~/.claude/bash-command-log.txt
```
若日志中出现如下内容，说明钩子配置成功：
```
ls - Lists files and directories
```

实用钩子示例

下面提供几个常用的钩子配置，你可以直接复制使用或按需修改。

📌 完整示例代码可参考官方仓库：bash 命令验证器示例

示例 1：自动格式化 TypeScript 文件

功能：编辑/写入 .ts 文件后，自动用 prettier 格式化代码

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write", // 匹配“编辑”和“写入”工具
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

示例 2：自动修复 Markdown 文件格式

功能：为无语言标签的代码块自动补全标签、清理多余空行

第一步：添加钩子配置

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
          }
        ]
      }
    ]
  }
}

第二步：创建格式化脚本

在项目目录下新建文件 .claude/hooks/markdown_formatter.py，粘贴以下代码：

实例

#!/usr/bin/env python3
"""
Markdown 格式化工具：自动补全代码块语言标签、清理多余空行
"""
import json
import sys
import re
import os

def detect_language(code):
"""根据代码内容自动检测编程语言"""
code = code.strip()
# 检测 JSON
if re.search(r'^\s*[{\[]', code):
try:
json.loads(code)
return 'json'
except:
pass
# 检测 Python
if re.search(r'^\s*def\s+\w+\s*\(', code, re.M) or re.search(r'^\s*(import|from)\s+\w+', code, re.M):
return 'python'
# 检测 JavaScript/TypeScript
if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', code) or re.search(r'=>|console\.(log|error)', code):
return 'javascript'
# 检测 Bash
if re.search(r'^#!.*\b(bash|sh)\b', code, re.M) or re.search(r'\b(if|then|fi|for|in|do|done)\b', code):
return 'bash'
# 默认文本格式
return 'text'

def format_markdown(content):
"""格式化 Markdown 内容"""
# 为无标签代码块补全语言
fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
def add_lang(match):
indent, info, body, closing = match.groups()
if not info.strip():
lang = detect_language(body)
return f"{indent}```{lang}\n{body}{closing}\n"
return match.group(0)
content = re.sub(fence_pattern, add_lang, content)
# 清理多余空行（仅清理代码块外的内容）
content = re.sub(r'\n{3,}', '\n\n', content)
return content.rstrip() + '\n'

if __name__ == "__main__":
try:
# 读取 Claude 传递的 JSON 数据
input_data = json.load(sys.stdin)
file_path = input_data.get('tool_input', {}).get('file_path', '')
# 仅处理 .md/.mdx 文件
if not file_path.endswith(('.md', '.mdx')):
sys.exit(0)
# 读取并格式化文件
if os.path.exists(file_path):
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
formatted_content = format_markdown(content)
# 仅在内容变化时写入
if formatted_content != content:
with open(file_path, 'w', encoding='utf-8') as f:
f.write(formatted_content)
print(f"已格式化 Markdown 文件：{file_path}")
except Exception as e:
print(f"格式化失败：{e}", file=sys.stderr)
sys.exit(1)

第三步：赋予脚本执行权限

chmod +x .claude/hooks/markdown_formatter.py

示例 3：Claude 等待输入时发送桌面通知

功能：当 Claude 需要用户输入时，自动弹出桌面提醒（适用于 Linux/macOS）

{
  "hooks": {
    "Notification": [
      {
        "matcher": "", // 匹配所有通知事件
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code 提示' '请你输入指令或确认权限'"
          }
        ]
      }
    ]
  }
}

示例 4：禁止修改敏感文件

功能：阻止 Claude 编辑 .env、package-lock.json 等敏感文件

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

说明：脚本返回状态码 2 时，Claude Code 会拦截此次工具调用，从而阻止文件修改。