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

引言

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

场景 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)

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 支持三种配置类型:

二、Hook 事件类型详解

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

2.1 Hook 类型总览

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: 任务完成自动通知

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

实现: 使用StopHook 触发通知

步骤 1: 创建通知脚本

# ~/.claude/hooks/notify-complete.sh#!/bin/bash# 根据操作系统选择通知方式OS=$(uname-s)case"$OS"inDarwin)# macOSosascript -e'display notification "任务完成" with title "Claude Code"';;Linux)notify-send"Claude Code""✅ 任务完成";;*)echo"Unsupported OS:$OS";;esacexit0

步骤 2: 赋予执行权限

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

步骤 3: 配置 Hook

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

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

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

实现: 使用NotificationHook

配置示例:

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

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

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

实现: 使用PostToolUseHook

配置示例:

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

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

3.4 案例 4: 任务完成验证

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

实现: 使用StopHook +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 类型选择指南

4.3 配置管理最佳实践

1. 配置文件版本管理

# 项目级配置提交到 Gitgitadd.claude/settings.jsongitcommit -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"];thenexit0fi# 继续执行...

五、常见问题与调试

5.1 Hook 未触发

排查步骤:

# 1. 检查配置文件格式jq.~/.claude/settings.json# 2. 检查 Hook 脚本权限ls-l ~/.claude/hooks/*.shchmod+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.sh2>>~/.claude/logs/hook-errors.log# 3. 使用 shellcheck 检查语法shellcheck~/.claude/hooks/*.sh

5.3 性能问题

优化方法:

# 1. 异步执行耗时操作command&# 后台执行# 2. 添加超时限制timeout5s ./slow-script.sh# 3. 快速退出非关键场景if["$condition"!="important"];thenexit0fi

六、总结

6.1 核心要点回顾

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

Hook 机制

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

6.2 快速配置指南

第 1 步: 创建 Hook 脚本

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

第 2 步: 配置 Hook

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

第 3 步: 验证配置

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

参考资料

• Claude Code Hooks 参考
• Bash Scripting Best Practices

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

🔗相关文章:

• 上一篇: 权限管理实战

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

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