Agent Hooks 实战入门：手把手配置你的第一个 Hook（二）

前言在上一篇文章《深入理解 Agent HooksClaude Code 自动化扩展机制详解一》中我们系统介绍了 Hooks 的核心概念、五种类型以及生命周期事件。相信你已经对 Hooks 有了初步的理论认识。本文目标很简单带你亲手完成第一个 Hook 的配置。不管你是刚接触 Claude Code 的新手还是想系统学习 Hooks 的开发者跟着本文操作你将在 10 分钟内掌握 Hooks 的基本配置方法并获得多个可直接复用的实战配置。主包以codebuddy来配置以下的hooks如需下载cli请到腾讯云官网查看文档一、找到并打开配置文件1.1 配置文件位置CodeBuddy Code兼容 Claude Code 规范的 Hooks 配置存储在 JSON 格式的设置文件中根据作用范围不同有以下几个位置作用域文件路径说明用户级~/.codebuddy/settings.json适用于所有项目个人配置项目级项目根目录/.codebuddy/settings.json项目共享可提交 Git项目本地项目根目录/.codebuddy/settings.local.json本地配置不提交 Git用户级的配置位置1.2 查看配置文件是否存在Windows步骤一找到settings.json文件用任意文本编辑器VS Code、记事本等打开。注意如果该目录或文件不存在请新建一个。1.3 打开配置文件然后用你喜欢的编辑器打开我的内容差不多是这样1.4 配置优先级当多个配置文件同时存在时Hooks 会合并而非覆盖。优先级为项目本地 项目级 用户级这意味着你可以在用户级配置通用规则在项目级覆盖特定行为。二、编写你的第一个 Hook首先按传统给出我们的速通宝典—直接给出提示词,让AI自己配这是一个会提醒你操作的hooks我们直接回车-回车-回车可能会看到配置好了如果没有以下配置需要手动贴进去然后回来/reload一下然后就可以听到铺天盖地的notification 叮叮叮的声音 说明配置完成每一次操作都会叮一下正文2.1 场景说明我们来实现一个最实用也最安全的 Hook阻止 Claude 执行rm -rf危险命令。这个场景非常适合作为入门示例因为逻辑简单直观检测命令是否包含危险字符串效果立竿见影保护重要数据不被误删便于理解流程PreToolUse 事件的典型应用2.2 完整配置代码在settings.json中写入以下内容{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:echo {\hookSpecificOutput\:{\hookEventName\:\PreToolUse\,\permissionDecision\:\deny\,\permissionDecisionReason\:\禁止执行包含 rm -rf 的危险命令\}} exit 2}]}]}}等等这个配置会阻止所有 Bash 命令我们需要更精细的控制。让我们改进一下配合脚本使用。2.3 改进版配合脚本检测步骤一创建脚本目录和文件mkdir-p~/.codebuddy/hooks创建文件~/.codebuddy/hooks/check-dangerous-command.sh#!/bin/bash# 读取 stdin 中的 JSON 数据input$(cat)# 提取命令内容需要 jq 工具command$(echo$input|jq-r.tool_input.command // empty)# 检查是否包含危险命令if[[$command*rm -rf*]]||[[$command*rm -rf /*]];thenecho{hookSpecificOutput:{hookEventName:PreToolUse,permissionDecision:deny,permissionDecisionReason:禁止执行 rm -rf 危险命令请手动操作}}exit2fi# 安全放行exit0步骤二给脚本执行权限chmodx ~/.codebuddy/hooks/check-dangerous-command.sh步骤三修改配置文件{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:~/.codebuddy/hooks/check-dangerous-command.sh}]}]}}2.4 配置字段详解让我们拆解这个配置字段说明hooks顶层字段所有 Hook 配置的容器PreToolUse事件名称表示工具执行前matcher匹配器Bash表示匹配 Bash 工具调用typeHook 类型command表示执行 Shell 命令command要执行的命令路径执行流程Claude 准备执行 Bash 命令PreToolUse 事件触发匹配器Bash匹配成功执行脚本check-dangerous-command.sh脚本检查命令内容返回deny阻止或返回0放行三、验证 Hook 是否生效3.1 触发测试在 CodeBuddy Code 中尝试让 Claude 执行请帮我删除测试目录rm -rf ./test-dir预期结果如果 Hook 配置正确你会看到类似提示禁止执行 rm -rf 危险命令请手动操作3.2 查看执行日志使用--debug模式启动 CodeBuddy Codecodebuddy--debug在日志中可以看到[DEBUG] Executing hooks for PreToolUse:Bash [DEBUG] Found 1 hook matchers [DEBUG] Matched 1 hooks for query Bash [DEBUG] Hook command completed with status 23.3 常见问题排查问题可能原因解决方案Hook 未触发配置文件格式错误检查 JSON 语法Hook 未触发matcher 不匹配确认工具名称正确脚本执行失败没有执行权限chmod x script.sh脚本执行失败路径错误使用绝对路径Windows 报错脚本不兼容确保 Git Bash 可用3.4 使用 /hooks 命令检查在 CodeBuddy Code 会话中输入/hooks这会显示当前已注册的 Hooks 列表确认你的 Hook 是否已被识别。四、实战配置示例合集以下是一系列开箱即用的配置你可以根据需要复制到自己的配置文件中。示例一敏感文件保护场景阻止 Claude 修改.env、.git、密钥文件等敏感内容。{hooks:{PreToolUse:[{matcher:Write|Edit,hooks:[{type:command,command:python3 \$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/protect-sensitive.py\ 2/dev/null || python \$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/protect-sensitive.py\}]}]}}脚本protect-sensitive.py#!/usr/bin/env python3importjsonimportsys SENSITIVE_PATTERNS[.env,.git,id_rsa,.pem,credentials]datajson.load(sys.stdin)file_pathdata.get(tool_input,{}).get(file_path,)forpatterninSENSITIVE_PATTERNS:ifpatterninfile_path:output{hookSpecificOutput:{hookEventName:PreToolUse,permissionDecision:deny,permissionDecisionReason:f禁止修改敏感文件{file_path}}}print(json.dumps(output))sys.exit(2)sys.exit(0)示例二代码自动格式化场景每次编辑或新建文件后自动运行代码格式化工具。{hooks:{PostToolUse:[{matcher:Write|Edit,hooks:[{type:command,command:FILE$(cat | jq -r .tool_input.file_path // empty); if [ -n \$FILE\ ]; then prettier --write \$FILE\ 2/dev/null || true; fi}]}]}}注意需要项目中有prettier和jq安装。可根据项目替换为black、gofmt等工具。如果没有jq可以创建脚本文件来解析。示例三空闲提醒通知场景当 Claude 等待用户输入超过 60 秒时发送桌面通知。{hooks:{Notification:[{matcher:idle_prompt,hooks:[{type:command,command:notify-send \CodeBuddy Code\ \Claude 正在等待你的输入\}]}]}}macOS 可替换为osascript-edisplay notification Claude 正在等待你的输入 with title CodeBuddy CodeWindows PowerShell[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType WindowsRuntime]$null$template[Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)$textNodes$template.GetElementsByTagName(text)$textNodes.Item(0).AppendChild($template.CreateTextNode(CodeBuddy Code))$null$textNodes.Item(1).AppendChild($template.CreateTextNode(Claude 正在等待你的输入))$null$toast[Windows.UI.Notifications.ToastNotification]::new($template)[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier(CodeBuddy Code).Show($toast)示例四任务完成度智能检查Prompt Hook场景Claude 完成响应时让 AI 判断是否真正完成了用户要求的任务。{hooks:{Stop:[{hooks:[{type:prompt,prompt:你是一个任务完成度检查器。分析以下对话上下文判断 Claude 是否完成了用户要求的所有任务。\n\n上下文$ARGUMENTS\n\n检查要点\n1. 用户的核心需求是否被解决\n2. 是否有遗漏的子任务\n3. 代码是否可运行\n\n返回 JSON 格式{\ok\: true} 表示完成{\ok\: false, \reason\: \具体原因\} 表示需要继续。,timeout:30}]}]}}示例五会话启动自动加载上下文场景每次启动新会话时自动注入项目特定的上下文信息。{hooks:{SessionStart:[{hooks:[{type:command,command:cat \$CODEBUDDY_PROJECT_DIR/.codebuddy/context.md\ 2/dev/null || echo 项目启动成功}]}]}}在项目根目录创建.codebuddy/context.md## 项目上下文 - 技术栈Node.js TypeScript React - 代码规范ESLint Prettier - 提交规范Conventional Commits - 注意事项请勿修改 .env 文件五、总结本文要点回顾步骤要点配置位置用户级~/.codebuddy/settings.json或项目级编写 Hook理解matcher、type、command三个关键字段验证方法使用/hooks查看注册--debug查看日志实战技巧脚本放.codebuddy/hooks/用$CODEBUDDY_PROJECT_DIR引用项目路径最佳实践建议从小配置开始先配置一个简单的 Hook验证流程后再逐步扩展脚本与配置分离复杂逻辑放脚本文件配置文件保持简洁注意跨平台兼容Windows 用户确保脚本能在 Git Bash 中运行善用$ARGUMENTSPrompt Hook 中使用$ARGUMENTS获取完整上下文下篇预告本系列的第三篇文章将深入探讨Hooks 进阶技巧包括如何修改工具输入参数modifiedInput多 Hook 协作与执行顺序MCP 工具的 Hook 配置复杂场景的完整实战案例敬请期待参考资料CodeBuddy Code Hooks 官方文档Claude Code Hooks 官方文档本文首发于 CSDN作者kingwu