Hook 机制实战:让 ClaudeCode 主动通知你

冬奇Lab
98 阅读7分钟

引言

你有没有遇到过这样的场景?

场景 1: 多终端协作

[你开了 3 个终端,让 AI 并行处理任务]
终端1: 正在重构用户模块...
终端2: 正在添加测试...
终端3: 正在优化性能...

[20分钟后,你回来检查]
你: "等等,哪个任务完成了?我怎么知道?"
[需要逐个终端查看,效率低下]

场景 2: 需要人工确认的关键操作

你: "帮我部署到生产环境"

AI: [完成打包、测试]
AI: "所有检查通过,准备部署到生产环境"
AI: ⚠️  [等待用户确认] 请输入 'deploy' 继续,或 'abort' 取消

[此时你需要收到通知,而不是一直盯着屏幕]

场景 3: 代码质量保障

你: "实现用户登录功能"

AI: [生成代码...]
AI: "✅ 代码已生成"

[你忘记执行代码审查...]
[代码质量有问题,需要返工]

这些问题的根源在于:

  • 缺少通知机制: 任务完成后无法及时感知,需要人工盯着
  • 缺少自动化流程: 重复性工作需要手动执行,容易遗漏

答案是: Hook 机制

Hook(钩子)是 Claude Code 提供的事件触发机制,允许你在特定事件发生时自动执行自定义脚本或 LLM 评估。Claude Code 支持 12 种 Hook 事件类型,常见的有:

  • Stop: Claude 完成响应时触发,可用于验证任务完成、自动继续多轮工作
  • Notification: 通知发送时触发,可用于桌面/Slack 通知
  • PreToolUse: 工具执行前触发,可用于权限控制、参数修改
  • PostToolUse: 工具成功执行后触发,可用于自动代码格式化、运行 lint
  • UserPromptSubmit: 用户提交提示词前触发,可用于验证/过滤输入

核心理念: 让 AI 在关键时刻主动通知你,而不是被动等待

本文将深入探讨 Claude Code 的 Hook 机制,让你的 AI 辅助开发体验更加自动化和高效。

阅读本文后,你将学会:

  • 理解 Hook 的工作原理和配置方式
  • 掌握所有 12 种 Hook 事件类型
  • 配置任务完成自动通知和自动化工作流
  • 掌握 Hook 的最佳实践

一、Hook 机制基础

1.1 Hook 的工作原理

**Hook(钩子)**是 Claude Code 提供的事件触发机制,允许你在特定事件发生时自动执行自定义脚本或 LLM 评估。

核心概念:

事件发生 → 触发 Hook → 执行脚本/LLM评估 → 返回结果 → 继续或中断

Hook 的生命周期:

1. 注册 Hook
   ↓
2. 监听事件
   ↓
3. 事件触发
   ↓
4. 执行 Hook 脚本/LLM评估
   ↓
5. 获取返回值
   ↓
6. 根据返回值决定是否继续(可阻止的 Hook)

05-01-hook-lifecycle.png

1.2 Hook 配置方式

Hook 可以通过两种方式配置:

方式 1: 通过 /hooks 命令配置(交互式)

在 Claude Code 交互式终端中输入:

> /hooks

这会打开 Hook 管理界面,你可以:

  • 查看已配置的 Hook
  • 添加新的 Hook 规则
  • 编辑或删除现有 Hook

方式 2: 通过 JSON 配置文件(推荐)

全局配置 (~/.claude/settings.json):

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "Check if all tasks complete. $ARGUMENTS"
      }]
    }],
    "Notification": [{
      "matcher": "permission_prompt",
      "hooks": [{
        "type": "command",
        "command": "notify-send 'Claude Code' 'Permission needed'"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write",
        "async": true
      }]
    }]
  }
}

项目级配置 (.claude/settings.json 或 .claude/settings.local.json):

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

配置优先级:

项目配置 > 全局配置 > 默认策略

1.3 Hook 配置类型

Hook 支持三种配置类型:

类型用途示例
command执行 shell 脚本{"type": "command", "command": "./script.sh"}
prompt快速 LLM 评估{"type": "prompt", "prompt": "Check if done"}
agent完整代理验证{"type": "agent", "prompt": "Run tests"}

二、Hook 事件类型详解

Claude Code 支持 12 种 Hook 事件类型,以下是完整说明:

2.1 Hook 类型总览

事件名称触发时机可阻止用途分类
SessionStart会话开始/恢复否初始化/上下文注入
UserPromptSubmit用户提交提示词前是验证/过滤
PreToolUse工具执行前是权限控制/参数修改
PermissionRequest权限对话显示时是自动化权限决策
PostToolUse工具成功执行后否格式化/验证
PostToolUseFailure工具执行失败后否错误处理/告警
Notification通知发送时否桌面/Slack 通知
SubagentStart子代理生成时否上下文注入
SubagentStop子代理完成时是结果验证
StopClaude 完成响应时是自动继续/验证完成
PreCompact上下文压缩前否备份/清理
SessionEnd会话结束时否清理/日志

2.2 详细说明

SessionStart

触发来源: startup(新建) | resume(恢复) | clear(/clear后) | compact(压缩后)

用途: 加载开发上下文、设置环境变量、初始化工具链

配置示例:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'Session started'"
      }]
    }]
  }
}

UserPromptSubmit

用途: 验证提示词、阻止敏感请求、添加动态上下文

输出控制: 退出码 2 或 "decision": "block" 可阻止提示

配置示例:

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/validate-prompt.sh"
      }]
    }]
  }
}

PreToolUse

支持匹配: Bash | Edit | Write | Read | Glob | Grep | mcp__*

决策类型: allow | deny | ask

配置示例:

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

PermissionRequest

用途: 在 CI/CD 或无头模式下自动批准/拒绝权限请求

配置示例:

{
  "hooks": {
    "PermissionRequest": [{
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/auto-permission.sh"
      }]
    }]
  }
}

PostToolUse

用途: 自动代码格式化、运行 lint、日志记录

配置示例:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write",
        "async": true
      }]
    }]
  }
}

PostToolUseFailure

用途: 错误日志记录、发送告警、故障诊断

配置示例:

{
  "hooks": {
    "PostToolUseFailure": [{
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/log-error.sh"
      }]
    }]
  }
}

Notification

通知类型: permission_prompt | idle_prompt | auth_success | elicitation_dialog

配置示例:

{
  "hooks": {
    "Notification": [{
      "matcher": "permission_prompt",
      "hooks": [{
        "type": "command",
        "command": "notify-send 'Claude Code' 'Permission needed'"
      }]
    }]
  }
}

SubagentStart

匹配值: Bash | Explore | Plan 或自定义代理名

用途: 为子代理注入安全策略和上下文

配置示例:

{
  "hooks": {
    "SubagentStart": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/inject-context.sh"
      }]
    }]
  }
}

SubagentStop

用途: 验证子代理结果,决定是否继续/停止

配置示例:

{
  "hooks": {
    "SubagentStop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "Verify subagent result: $ARGUMENTS"
      }]
    }]
  }
}

Stop

用途: 验证任务完成、自动继续多轮工作

配置示例:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "Check if all tasks complete. $ARGUMENTS"
      }]
    }]
  }
}

PreCompact

触发器: manual(/compact命令) | auto(自动压缩)

用途: 备份重要上下文、清理临时文件

配置示例:

{
  "hooks": {
    "PreCompact": [{
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/backup-context.sh"
      }]
    }]
  }
}

SessionEnd

结束原因: clear | logout | prompt_input_exit | other

用途: 清理临时文件、保存会话统计

配置示例:

{
  "hooks": {
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/cleanup.sh"
      }]
    }]
  }
}

三、实战案例

3.1 案例 1: 任务完成自动通知

需求: 多终端协作时,任务完成自动发送系统通知

实现: 使用 Stop Hook 触发通知

步骤 1: 创建通知脚本

# ~/.claude/hooks/notify-complete.sh
#!/bin/bash

# 根据操作系统选择通知方式
OS=$(uname -s)

case "$OS" in
    Darwin)  # macOS
        osascript -e 'display notification "任务完成" with title "Claude Code"'
        ;;
    Linux)
        notify-send "Claude Code" "✅ 任务完成"
        ;;
    *)
        echo "Unsupported OS: $OS"
        ;;
esac

exit 0

步骤 2: 赋予执行权限

chmod +x ~/.claude/hooks/notify-complete.sh

步骤 3: 配置 Hook

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/notify-complete.sh"
      }]
    }]
  }
}

3.2 案例 2: 权限请求自动通知

需求: 当需要权限确认时,自动发送通知提醒

实现: 使用 Notification Hook

配置示例:

{
  "hooks": {
    "Notification": [{
      "matcher": "permission_prompt",
      "hooks": [{
        "type": "command",
        "command": "notify-send -u critical 'Claude Code' '需要权限确认'"
      }]
    }]
  }
}

3.3 案例 3: 代码自动格式化

需求: 每次编辑或写入文件后,自动运行格式化工具

实现: 使用 PostToolUse Hook

配置示例:

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

注意: 使用 "async": true 让格式化在后台执行,不阻塞主流程。

3.4 案例 4: 任务完成验证

需求: 任务完成后自动验证是否所有任务都已完成

实现: 使用 Stop Hook + prompt 类型

配置示例:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "检查以下任务是否全部完成:\n$ARGUMENTS\n如果还有未完成的任务,请继续执行。"
      }]
    }]
  }
}

四、最佳实践

4.1 Hook 配置最佳实践

✅ DO(推荐做法)

  1. 使用项目级配置: 项目特定的 Hook 放在 .claude/settings.local.json,不提交到 Git
  2. 异步执行耗时操作: 对于格式化、lint 等耗时操作,使用 "async": true
  3. 合理使用 matcher: 精确匹配工具类型,避免不必要的 Hook 触发
  4. 错误处理: Hook 脚本应包含错误处理,避免因 Hook 失败影响主流程
  5. 日志记录: 重要操作记录日志,便于调试和审计

❌ DON'T(避免的做法)

  1. Hook 执行时间过长: Hook 脚本应快速执行(建议 < 5 秒),耗时操作使用异步
  2. 阻塞关键流程: 可阻止的 Hook(如 PreToolUse)应谨慎使用,避免误拦截
  3. 敏感信息泄露: Hook 脚本中不要硬编码敏感信息,使用环境变量
  4. 过度依赖 Hook: Hook 是辅助工具,不应替代正常的权限管理和代码审查流程

4.2 Hook 类型选择指南

场景推荐 Hook说明
任务完成通知StopClaude 完成响应时触发
权限请求通知Notification权限对话显示时触发
代码自动格式化PostToolUse工具成功执行后触发
危险命令拦截PreToolUse工具执行前拦截
输入验证UserPromptSubmit用户提交前验证
错误告警PostToolUseFailure工具失败时告警
会话初始化SessionStart会话开始时加载上下文

4.3 配置管理最佳实践

1. 配置文件版本管理

# 项目级配置提交到 Git
git add .claude/settings.json
git commit -m "feat: add Claude Code hooks config"

# 全局配置不提交(个人设置)
echo "~/.claude/settings.json" >> ~/.gitignore_global

2. Hook 脚本组织

.claude/
├── settings.json              # 项目配置(提交到 Git)
├── settings.local.json        # 本地配置(不提交)
└── hooks/
    ├── notify-complete.sh     # 通知脚本
    ├── validate-bash.sh       # 验证脚本
    └── auto-format.sh         # 格式化脚本

3. 调试技巧

# 测试 Hook 脚本独立运行
~/.claude/hooks/notify-complete.sh

# 查看 Hook 执行日志
tail -f ~/.claude/logs/hook-execution.log

# 使用 shellcheck 检查脚本语法
shellcheck ~/.claude/hooks/*.sh

4.4 性能优化

1. 异步执行

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "./format.sh",
        "async": true
      }]
    }]
  }
}

2. 精确匹配

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",  // 只匹配 Bash,不匹配其他工具
      "hooks": [...]
    }]
  }
}

3. 快速退出

#!/bin/bash
# Hook 脚本开头快速检查,不满足条件立即退出
if [ "$1" != "important-task" ]; then
    exit 0
fi
# 继续执行...

五、常见问题与调试

5.1 Hook 未触发

排查步骤:

# 1. 检查配置文件格式
jq . ~/.claude/settings.json

# 2. 检查 Hook 脚本权限
ls -l ~/.claude/hooks/*.sh
chmod +x ~/.claude/hooks/*.sh

# 3. 测试脚本独立运行
~/.claude/hooks/notify-complete.sh

# 4. 查看 Hook 执行日志
tail -f ~/.claude/logs/hook-execution.log

5.2 Hook 执行失败

调试技巧:

# 1. 添加调试输出
set -x
# 脚本内容...
set +x

# 2. 重定向错误到日志
./hook.sh 2>> ~/.claude/logs/hook-errors.log

# 3. 使用 shellcheck 检查语法
shellcheck ~/.claude/hooks/*.sh

5.3 性能问题

优化方法:

# 1. 异步执行耗时操作
command &  # 后台执行

# 2. 添加超时限制
timeout 5s ./slow-script.sh

# 3. 快速退出非关键场景
if [ "$condition" != "important" ]; then
    exit 0
fi

六、总结

6.1 核心要点回顾

通过本文,我们深入探讨了 Claude Code 的 Hook 机制:

Hook 机制

  • 原理: 事件驱动,在特定时机自动执行脚本或 LLM 评估
  • 类型: 12 种 Hook 事件类型,覆盖完整的开发生命周期
  • 配置: 通过 /hooks 命令或 JSON 配置文件
  • 应用: 智能通知、自动化 QA、安全拦截、工作流自动化

6.2 快速配置指南

第 1 步: 创建 Hook 脚本

mkdir -p ~/.claude/hooks

cat > ~/.claude/hooks/notify-complete.sh << 'EOF'
#!/bin/bash
notify-send "Claude Code" "✅ 任务完成"
exit 0
EOF

chmod +x ~/.claude/hooks/notify-complete.sh

第 2 步: 配置 Hook

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/notify-complete.sh"
      }]
    }]
  }
}

第 3 步: 验证配置

# 启动 Claude Code
claude

# 执行一个任务,完成后应该收到通知
> 帮我创建一个 hello.txt 文件

参考资料

💡 思考题: 你的开发流程中,有哪些操作可以通过 Hook 自动化?如果让你设计一个 Hook,你会选择什么触发时机?

🔗 相关文章:

如果这篇文章对你有帮助,欢迎点赞、收藏、分享!有任何问题或建议,欢迎在评论区留言讨论。让我们一起学习,一起成长!

也欢迎访问我的个人主页发现更多宝藏资源

avatar
文章
阅读
粉丝