Hooks 概述
Overview of Claude Code Hooks
Claude Code Hooks 是一套强大的生命周期钩子系统，允许你在 Claude Code 的关键执行节点插入自定义逻辑。通过 Hooks，你可以实现自动化工作流、安全检查、代码质量保障等多种高级功能，而无需手动干预。
什么是 Hooks
What are Hooks
Hooks（钩子）是在 Claude Code 执行生命周期中特定事件触发时自动运行的自定义脚本或处理器。它们的核心思想是事件驱动——当某个事件发生时，系统自动执行你预先配置的操作。
简单来说，Hooks 就像是你为 Claude Code 设置的"自动反应"机制：
- 当 Claude 准备调用某个工具时 → 你可以先做一次安全检查
- 当 Claude 写入文件后 → 你可以自动运行代码格式化
- 当一次会话结束时 → 你可以记录日志或发送通知
事件发生 → 触发 Hook → 执行你的自定义逻辑 → 继续（或中止）流程一个最简单的例子
A minimal example
以下配置会在每次工具调用后打印一条日志消息：
{
"hooks": {
"PostToolUse": [
{
"matcher": "*",
"handler": {
"type": "command",
"command": "echo 'Tool was used' >> /tmp/claude-hooks.log"
}
}
]
}
}与 Git Hooks 的类比
Analogy with Git Hooks
如果你熟悉 Git Hooks，那么理解 Claude Code Hooks 会非常容易。两者的核心思想完全一致：
| 特性 | Git Hooks | Claude Code Hooks |
|---|---|---|
| 触发方式 | Git 操作（commit、push 等） | Claude Code 事件（工具调用、会话开始等） |
| 配置位置 | .git/hooks/ 目录 | settings.json 的 hooks 字段 |
| 执行时机 | pre-commit、post-commit 等 | PreToolUse、PostToolUse 等 |
| 阻断能力 | pre-commit 返回非零可阻止提交 | PreToolUse 返回非零可阻止工具调用 |
| 脚本类型 | Shell 脚本 | Shell 命令、Prompt 注入、子代理 |
| 作用范围 | 单个 Git 仓库 | 用户级、项目级、本地级 |
正如 pre-commit Hook 可以在代码提交前运行 lint 检查一样，Claude Code 的 PreToolUse Hook 可以在工具调用前执行安全校验。
Hooks 的核心价值
Core value of Hooks
1. 自动化（Automation）
消除重复性的手动操作，让 Claude Code 的工作流更加顺畅：
- 文件写入后自动格式化代码
- 测试文件修改后自动运行相关测试
- 会话结束后自动生成工作报告
2. 安全检查（Security）
在关键操作执行前加入安全屏障：
- 阻止执行危险的 Shell 命令（如
rm -rf /） - 检查文件写入是否涉及敏感路径
- 验证 Git 操作是否符合团队规范
3. 工作流定制（Workflow Customization）
根据团队或项目的具体需求定制 Claude Code 的行为：
- 为特定项目注入额外的上下文信息
- 在工具调用前后添加自定义的处理逻辑
- 集成第三方工具和服务（Slack、JIRA 等）
4. 可观测性（Observability）
深入了解 Claude Code 的运行状态：
- 记录每次工具调用的详细日志
- 统计会话时长和工具使用频率
- 追踪异常行为和错误模式
配置位置
Configuration location
Hooks 的配置位于 settings.json 文件中的 hooks 字段。配置的基本结构如下：
{
"hooks": {
"<事件类型>": [
{
"matcher": "<匹配规则>",
"handler": {
"type": "<处理器类型>",
...
}
}
]
}
}配置字段说明
Configuration field reference
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
hooks | object | 是 | 顶层 hooks 配置对象 |
<事件类型> | array | 是 | 事件名称，如 PreToolUse，值为 hook 数组 |
matcher | string | 否 | 匹配规则，用于过滤特定工具或条件，* 表示全部匹配 |
handler | object | 是 | 处理器定义，指定要执行的操作 |
handler.type | string | 是 | 处理器类型：command、prompt 或 agent |
三层配置体系
Three-tier configuration system
Claude Code Hooks 支持三个层级的配置，每个层级有不同的作用范围和优先级：
用户级配置（User-level）
- 文件位置：
~/.claude/settings.json - 作用范围：对当前用户的所有项目生效
- 典型用途：全局安全规则、通用日志记录、个人偏好
// ~/.claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"handler": {
"type": "command",
"command": "python3 ~/.claude/scripts/safety-check.py"
}
}
]
}
}项目级配置（Project-level）
- 文件位置：
<项目根目录>/.claude/settings.json - 作用范围：对当前项目的所有协作者生效
- 典型用途：项目特定的代码规范、CI/CD 集成、团队约定
- 注意：此文件通常会提交到版本控制
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"handler": {
"type": "command",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
}
}
]
}
}本地级配置（Local-level）
- 文件位置：
<项目根目录>/.claude/settings.local.json - 作用范围：仅对当前开发者的本地环境生效
- 典型用途：个人调试脚本、本地特有的路径配置
- 注意：此文件不应提交到版本控制（应添加到
.gitignore）
// .claude/settings.local.json
{
"hooks": {
"Stop": [
{
"handler": {
"type": "command",
"command": "notify-send 'Claude Code 任务完成'"
}
}
]
}
}配置合并规则
Configuration merge rules
当多个层级同时定义了同一事件的 Hooks 时，系统会合并所有层级的配置，按以下顺序依次执行：
用户级 → 项目级 → 本地级注意：任何一个层级的 Hook 返回错误（非零退出码），都会影响后续 Hook 的执行和整体流程。
Hook 执行流程
Hook execution flow
以下是一个 Hook 在 Claude Code 中的完整执行流程：
┌─────────────────────────────────────────────────┐
│ Claude Code 执行流程 │
├─────────────────────────────────────────────────┤
│ │
│ 1. 事件发生（如：Claude 准备调用 Write 工具） │
│ │ │
│ ▼ │
│ 2. 查找匹配的 Hooks │
│ - 检查用户级配置 │
│ - 检查项目级配置 │
│ - 检查本地级配置 │
│ │ │
│ ▼ │
│ 3. 依次执行匹配的 Hooks │
│ - 通过 stdin 传入事件参数（JSON） │
│ - 等待处理器执行完成 │
│ - 检查退出码和输出 │
│ │ │
│ ▼ │
│ 4. 根据结果决定后续行为 │
│ - exitCode === 0 → 继续执行 │
│ - exitCode === 2 → 阻止操作（仅 Pre* 事件） │
│ - 其他非零 → 报告错误 │
│ │
└─────────────────────────────────────────────────┘执行时序示例
Execution timing example
以写入文件为例，一次完整的工具调用涉及以下步骤：
PreToolUse(Write) → [执行 Write 工具] → PostToolUse(Write)
│ │
├─ 安全检查 ├─ 自动格式化
├─ 路径验证 ├─ 运行 lint
└─ 权限校验 └─ 触发测试Hooks 与 Skills 的区别
Hooks vs Skills
Hooks 和 Skills 是 Claude Code 中两个容易混淆的概念，但它们的定位和使用方式截然不同：
| 维度 | Hooks | Skills |
|---|---|---|
| 触发方式 | 自动触发——事件驱动 | 主动调用——由 Claude 决定使用 |
| 执行时机 | 生命周期事件发生时 | Claude 认为需要时 |
| 用户感知 | 通常在后台静默运行 | Claude 会明确说明正在使用 |
| 配置方式 | settings.json 中的 hooks 字段 | 独立的 Skill 定义文件 |
| 适用场景 | 自动化、安全检查、日志 | 复杂任务、领域知识、专业能力 |
| 执行主体 | Shell 命令、Prompt、子代理 | Claude 自身 |
| 阻断能力 | 可以阻止操作继续 | 不能阻止其他操作 |
何时使用 Hooks
- 需要在每次特定操作时自动执行某些检查或处理
- 需要阻止某些不安全的操作
- 需要在 Claude 不感知的情况下静默运行后台任务
- 需要与外部系统集成（通知、日志、CI/CD）
何时使用 Skills
- 需要赋予 Claude 新的能力或专业知识
- 需要 Claude 主动决定何时使用某个能力
- 需要处理复杂的多步骤任务
- 需要 Claude 理解并运用领域特定的知识
快速开始
Quick start
要开始使用 Hooks，只需在你的 settings.json 中添加 hooks 配置即可。以下是一个最小可用配置：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"handler": {
"type": "command",
"command": "echo \"File written: $CLAUDE_FILE_PATH\" >> /tmp/claude-activity.log"
}
}
]
}
}这个配置会在每次 Claude 写入文件后，将文件路径记录到日志中。
注意事项
Important notes
- 安全性：Hooks 会执行任意命令，请确保配置来源可信。项目级配置（
.claude/settings.json）应当经过代码审查。 - 性能：Hook 脚本的执行时间会影响 Claude Code 的响应速度。尽量保持脚本轻量快速。
- 错误处理：Hook 脚本应当妥善处理错误情况，避免因脚本异常导致 Claude Code 工作流中断。
- 可移植性：如果 Hook 配置会被团队共享（项目级），请确保脚本在不同操作系统和环境中都能正常运行。
- 调试：可以通过在 Hook 脚本中添加日志输出来调试问题。使用
--debug标志启动 Claude Code 可以查看 Hook 的详细执行信息。