1. 为什么我把Hooks当成Claude Code的“自动驾驶开关”先说说我为什么会盯上这个功能。用Claude Code用久了你会发现一个很尴尬的阶段它确实能帮你写代码、查报错、跑测试但每次对话都要你手动去触发下一步。比如你想让它“改完代码自动跑一遍单测”“提交之前自动检查一下有没有把密钥打进diff里”“长任务跑完自动拍个快照存档”这些事如果靠人肉盯进程Claude Code就退化成了一个带提示词的终端谈不上真正的自动化。我第一次意识到Hooks这个东西不简单是在一次批量重构的时候。那次我要对几十个模块做统一的异常处理改造任务本身并不难但重复性极高。我自己写了个简单的Shell脚本想兜底结果发现Claude Code在调用工具之前、之后、以及整轮对话结束的时候都能插入我们自己的脚本去干预流程。那一刻我突然明白这东西其实是给AI接上“条件反射”的神经系统。你不需要每一步都喊口令只要把规则提前设定好它会自己在合适的时机做该做的事。Hooks的官方定位很简单在Claude Code生命周期的关键节点上执行自定义脚本。听起来和Git的Hook、ESLint的pre-commit hook很像但实际用下来它的想象力要大得多因为挂钩的对象不是某个工具而是整个Agent的工作循环。这篇文章我不会去复述官方文档那玩意儿你自己能看。我想聊的是我实际用Hooks做过什么、怎么设计的、哪些配置让我踩了坑、以及拿到手之后怎么扩展。如果你正准备入坑Claude Code或者已经在用但觉得“这玩意儿还差点意思”那这篇应该能给你不少思路。2. 事件模型与生命周期Hooks到底挂在哪些环节上2.1 六个核心事件节点Hooks之所以能“自动化”是因为Claude Code把一次交互拆成了一根有节点的流水线。现阶段我经常用到的主要是这六个事件事件触发时机典型用途PreToolUseClaude调用任意工具之前参数校验、敏感命令拦截、日志记录PostToolUse工具执行完成后检查执行结果、自动格式化、触发后续动作UserPromptSubmit用户消息提交后、AI处理前注入上下文、改写提问、加载项目规范NotificationClaude完成一次API调用后有新信息桌面通知、进度上报Stop一轮完整对话结束自动提交、生成摘要、记账SubagentStop子代理执行完毕汇总多个子代理产出、清理临时文件这里要特别注意一个点PreToolUse和PostToolUse都是按工具名匹配来触发的不是全局钩子。你可以在配置里写多个规则让不同的脚本管不同的工具。比如对Bash做命令审计对Edit做文件变更记录对Write做关键目录白名单控制。2.2 同步、异步与阻塞语义Hooks脚本的运行模式分两种一种是你等它跑完再继续一种是你放它后台跑你干别的。官方术语叫阻塞式和非阻塞式。我在配置里用过timeout: 0让脚本超时无限等待也用过默认的异步模式去发通知。这个设计直接影响流程稳定性阻塞式适合校验类场景。比如PreToolUse要拦截危险命令必须等脚本返回之后才决定放不放行。异步式适合通知类场景。比如Stop事件里发个推送没必要让主流程卡着等推送响应。2.3 配置从哪来优先级如何Hooks配置写在settings.json里这个文件按加载顺序分为四个层级企业策略文件、用户全局文件、项目本地文件、命令行参数。实际生效时项目级配置会覆盖用户级企业策略优先级最高。如果你用VS Code插件插件的配置文件又是单独加载的。我在做实验时出现过的“为什么我的hook没生效”十有八九就是层级被覆盖了。我自己习惯把所有跟团队协作相关的Hooks放在项目根目录的.claude/settings.json里个人偏好类的比如桌面通知放在用户全局配置里。这样切项目的时候个人通知不会跑到别人电脑上而团队规范类的东西跟着仓库走。3. 从零搭一个可用的Hooks配置格式、脚本写法与热加载3.1 基础配置模板照着抄就行先看一个最简单的settings.json这段配置我一直在用用来拦截rm -rf之类的危险命令{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: /path/to/guard-bash.sh, timeout: 10 } ] } ] } }这里有几个关键字段要解释一下。matcher是匹配工具名的模式支持精确匹配和通配符。type目前我用到的只有command表示执行一条shell命令。timeout是超时秒数超过这个时间脚本还没返回Claude Code会按失败处理。对应地guard-bash.sh可以这么写#!/bin/bash input_json$(cat) command_str$(echo $input_json | jq -r .tool_input.command // empty) if [ -z $command_str ]; then echo {\decision\: \allow\, \reason\: \No command provided\} exit 0 fi if echo $command_str | grep -qE rm\s-rf\s/|mkfs\.|dd\sif.*of/dev/sd; then echo {\decision\: \deny\, \reason\: \Dangerous command blocked by guard: $command_str\} exit 0 fi echo {\decision\: \allow\, \reason\: \Command is safe\} exit 0这套逻辑的本质是先从stdin读出JSONClaude Code会把工具调用信息打包传给你再用jq提取命令内容匹配危险模式则输出deny否则放行。脚本退出码为0不代表一定放行最终决策取决于你输出的JSON里的decision字段。3.2 给Hooks传上下文stdin、JSON、环境变量这是我最初最懵的地方。Hooks脚本并不是“你自己在终端里随便敲一条命令”它需要从标准输入接收一串JSON里面包含session_id、transcript_path、tool_name、tool_input等字段。拿PostToolUse举例你收到的JSON大致长这样{ session_id: abc123, transcript_path: /path/to/transcript.jsonl, tool_name: Edit, tool_input: { file_path: /project/src/main.py, old_string: ..., new_string: ... }, tool_response: { success: true } }我写脚本的习惯是第一步永远先cat整段输入然后用jq做字段提取再根据业务逻辑输出决策或执行副作用最后用exit 0收尾。调试阶段可以在脚本开头加一行echo $(date) — $input_json /tmp/hook-debug.log把原始输入留底不然出问题你连输入是什么都不知道。3.3 改完配置怎么让它生效Hooks的配置是每次工具调用前重新读取的不是常驻内存。你改了settings.json下一次触发就会用新配置不需要重启Claude Code。但要注意如果你通过/hook命令在会话里临时加过Hook那些临时配置只对当前会话有效关掉会话就没了。配置方式生效范围持久性项目级settings.json当前项目永久跟随仓库用户级settings.json所有项目永久本机/hook命令设置当前会话临时命令行--hooks参数本次启动临时4. 三个让我血压升高的前置条件和截断规则4.1 为什么你的脚本明明写了却不执行我遇到过最迷惑的情况配置写得没有任何语法错误脚本权限也加了chmod x但PreToolUse就是不触发。后来反复测试才发现我犯了个低级错误——matcher写的是小写bash而Claude Code内部工具名是Bash。这个匹配是大小写敏感的。还有一次是脚本路径问题。Claude Code执行command时的当前工作目录不是你项目的根目录你若用相对路径去指脚本它可能跑到别的目录找文件。从我踩坑的经验来看绝对路径放第一位。如果确实要用相对路径先想想你的脚本会从哪里被执行。另一个非常隐蔽的坑是当Claude Code运行的会话不在项目目录内启动时它会自动找一个最近的可用项目目录作为工作区你的“绝对路径”看似正确但脚本文件在另一个目录那也执行不了。所以我的建议是在脚本第一行加个set -euo pipefail再把关键路径打出来宁可调试期多打点日志也不要生产环境里瞎猜。4.2 输出格式与退出码的模糊地带Hook的输出格式必须是JSON而且不同事件能接受的字段不同。PreToolUse返回的是决策对象{decision: allow, reason: safe}JSON必须是一行有效的JSON末尾不能有多余输出。我在调试时发现脚本里如果顺手echo了一行log这一行log会被Claude Code尝试当作JSON解析直接报错。所以生产中必须把日志写到stderr或文件别在stdout里夹杂非JSON文本。关于退出码脚本返回非0并不等于“拒绝执行”它只是告诉Claude Code这个Hook出错了。PostToolUse阶段如果脚本退出码非0Claude Code会认为工具结果异常PreToolUse阶段非0退出码则可能导致工具调用被中断。所以我的建议是脚本内自己捕获异常自己输出JSON决策最终统一exit 0把控制权掌握在JSON字段而不是退出码上。4.3 超时和失控如何给自己留后路timeout设太小脚本跑不完会误伤正常操作设太大脚本一旦卡死会拖垮整个任务。我一般这样区分场景校验类脚本PreToolUse设置5-10秒通知类脚本Notification、Stop设置0秒无限或干脆不设复杂的工作流脚本比如拉取远程数据、调用外部API设置30秒以上还有个细节如果你的脚本需要相互协调比如一个设了标志位另一个清标志位要注意它们在不同事件里是独立进程环境变量不共享唯一的沟通渠道是文件系统。我会把中间状态写到/tmp/claude-hook-state/下然后加个简单的锁文件策略避免并发执行互相覆盖。5. 更野一点的玩法审计、代码卫生与多智能体级联5.1 自动给每个工具调用上“行车记录仪”我很反感每次手动去翻transcript查“刚才到底跑过什么命令”。后来我用PostToolUse做了个全量审计脚本只要工具名是Bash或者Edit执行完就把工具名、目标路径、关键参数追加到一个按日期命名的JSONL文件里。#!/bin/bash json$(cat) timestamp$(date %Y-%m-%d %H:%M:%S) tool$(echo $json | jq -r .tool_name) input$(echo $json | jq -c .tool_input) log_file${CLAUDE_PROJECT_DIR:-$HOME}/.claude/logs/tool-audit-$(date %Y%m%d).jsonl mkdir -p $(dirname $log_file) echo {\time\:\$timestamp\,\tool\:\$tool\,\input\:$input} $log_file echo {\success\: true} exit 0这个日志文件让我在复盘“模型为什么突然改了某个文件”的时候有了实锤。它也间接帮我定位过好几次“是不是有人手动改了配置导致行为异常”的悬案。5.2 代码卫生写入前强制规范写入后自动修正我在团队里推过一条规矩任何对源文件的修改都要先过一遍项目里的lint规则。这个用Hooks实现很简单——PreToolUse匹配Write和Edit提取file_path如果是项目内的源码文件先跑一次git diff --check和eslint --no-fix静态检测命中规则就拒绝写入让模型换一种方式再写。但只做PreToolUse还不够。有些场景是模型写出来的代码legacy味太重强制拒绝容易把对话卡死。于是我在PostToolUse里加了“格式化回调”如果检测到Edit的目标文件位于src/目录就用prettier自动格式化它然后git add那个文件。看起来效果还不错代码风格一致性明显上来了。5.3 用Stop事件搭一个轻量级“验收流水线”Stop事件是整轮对话结束的信号。我在这里接了一个叫做“验收流水线”的脚本开关路径是检查git工作区是否干净。如果检测到工作区有未提交变更脚本会做四件事生成简短变更摘要git diff --stat 读最近几个commit的风格模板把摘要写入一个临时文件调用一个内部服务生成任务追踪的引用ID往钉钉群里发一条带摘要的webhook消息这套东西的成本极低但省去了“任务结束还要人工补记录”的环节。我现在跑长任务的时候基本是“挂上就去做别的事结束之后看群消息”。5.4 子代理联动汇总多个任务结果Claude Code支持在主任务里派生子代理去并行处理不同子任务。SubagentStop事件就是为这个场景准备的。我给一个整理代码文档的任务配过主代理拆出去5个子代理分别扫描不同模块的TODOSubagentStop里写死一个累加器每个子代理完工就把输出的摘要append到一个汇总文件等全部结束后主代理统一读取汇总文件来生成最终文档。虽然实现不算复杂但体验上的感觉就是“真的像在指挥一个小团队”。6. 平时让我省心的组合拳Hooks加第三方模型和本地模型的使用配置6.1 为什么我要把Claude Code接到别的模型上先交代一下背景我在日常工作中会同时用几个模型服务商有时候项目要求用本地模型跑离线任务有时候又要赶着测试不同模型对同一份代码的理解能力。Claude Code默认只连官方模型但因为它本身支持通过环境变量或配置文件来指定API端点所以也能接到兼容的第三方网关或本地推理服务上。我的测试流程是这样先在本地启动一个支持OpenAI兼容接口的推理服务比如Ollama、LM Studio这类然后确认它暴露的端口再拿到一个兼容的base URL。接着在Claude Code的配置里把模型相关参数指过去让它把请求发到本地服务端口。整个过程不需要改任何Hooks逻辑——只要你能换后端模型Hooks这套事件机制是完全中性的它只认“工具调用”这个抽象层。6.2 配置样例与注意事项以我常用的环境变量方式为例注意具体变量名和格式要以你装的版本为准export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_AUTH_TOKENlocal-test-token export ANTHROPIC_MODELlocal-model-name还要确认一下推理服务有没有把/v1/messages这个路由正确转发给Claude Code——这个常常是接不上的核心原因。我踩过的坑是有些本地服务虽然兼容OpenAI的/chat/completions但不兼容Anthropic的/v1/messages格式Claude Code发过去的请求会直接失败。这个排查起来很费时间最快的办法是打开Claude Code的调试日志看HTTP状态码和返回体。有一点我必须提醒不要使用来源不明的第三方封装或破解面板。这类东西要么封禁风险极高要么可能把你的对话内容转发到未知服务器。我在团队内部只允许用官方API或内网网关本地模型也只用开源推理框架直连不走任何灰色代理。这些涉及到账号安全和数据隐私的底线不能因为“图省事”就去碰。6.3 配合Hooks的典型工作流接到本地模型之后我用Hooks做了这么一套“断网可跑”的流程UserPromptSubmit自动在提示词里注入项目README摘要和当前git分支PreToolUse拦截所有触网类命令curl、wget等在离线环境下直接允许但记录日志PostToolUse命中的文件跑本地linterStop把本次会话的token消耗、耗时、输出摘要存到本地CSV这套流程让我在没网的环境下也能跑通一批AI辅助开发任务。而且因为有Hooks把“规范记录”自动化了换模型这件事反而变得很透明——不管后面接谁代码质量和审计日志是一样的。7. 几个我实际踩过的坑以及对应解法7.1 通配符匹配了不该匹配的工具matcher支持正则和通配符如Bash*但如果你写得太宽会把Bash工具误伤。我一开始为了省事写了个.去匹配所有工具结果导致PostToolUse在每次Read之后也跑了一遍完整审计整个对话速度肉眼可见地变慢。解法尽可能精确到工具名不要贪省事。必要的时候用多个规则条目而不是一条正则通配。7.2 Hook脚本中执行慢命令拖垮主流程我试过在PostToolUse里调一个远程API做语义校验接口偶尔要两三秒才返回叠加在多次工具调用上整个会话的响应速度完全不可接受。解法把慢操作改成异步。比如把结果写进一个本地任务队列由系统定时任务去消费或者干脆用背景启动并立刻返回成功主流程不等它。7.3 配置了Hook但没生效八成是路径或层级问题我把这个单拎出来再强调一次因为它太常见了先在终端里用echo $CLAUDE_CONFIG_DIR看看配置目录在哪儿再确认.claude/settings.json是不是放在项目根目录。VS Code插件和CLI读的配置来源不同你CLI里生效的配置插件里不一定认。7.4 在Windows环境下跑Hook脚本Windows上写bash脚本要注意Claude Code在Windows里执行bash命令依赖Git Bash提供的bash解释器。如果你的脚本用了Linux特有的命令如jq要么提前装好要么改用PowerShell脚本。我测试过的方案是用wsl跑bash前提是WSL里装了jq等工具。更稳妥的做法是Windows上Hook脚本尽量用node或python写跨平台兼容性会好很多。7.5 长会话导致状态文件爆炸Stop事件里我一开始会把整个transcript复制一份存档跑几小时后发现磁盘占用翻了几倍。后来改成了只复制摘要、token统计和关键diff原始transcript本来就存在会话目录里没必要重复存。8. 我这套配置在真实项目里的一个完整回放为了让上面的内容不止于纸上谈兵我放一个简化版的settings.json这是我目前一个工作项目的实际配置骨架你可以直接拿去改{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: /home/user/bin/guard-bash.sh, timeout: 5 } ] }, { matcher: Write|Edit, hooks: [ { type: command, command: /home/user/bin/check-src-write.sh, timeout: 8 } ] } ], PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: /home/user/bin/auto-lint.sh, timeout: 15 } ] } ], Stop: [ { hooks: [ { type: command, command: /home/user/bin/session-summary.sh, timeout: 30 } ] } ] } }对应脚本我都放在项目隐藏目录下路径写绝对路径。这样我在不同机器上同步配置时只要保证脚本路径存在换机器跑就不会因为路径漂移而出问题。真实跑一个任务的流程是这样我输入需求“修复最新feature分支上的eslint错误”UserPromptSubmit注入当前分支名和package.json里的lint脚本Claude Code开始读文件PreToolUse放行所有Read请求PostToolUse不做额外处理它尝试修改文件PreToolUse先看是不是src/下源码是则先检查文件是否在改动白名单里我用一个本地文件记录允许AI改动的目录写入后PostToolUse自动跑eslint如果还有错会把错误输出回传给模型模型继续修全部修完对话结束Stop事件触发生成一段“修复了X个文件涉及模块A/B剩余问题清单”的摘要发到团队群我回头从审计日志里看模型到底改了哪些文件确认没有越界这套东西真正跑通之后你才会感受到“AI自动化的天花板不在模型而在流程设计”。模型只是执行的大脑Hooks才是你给它设定的神经反射弧。写到这里我最想说的是Hooks目前还处于“API稳定但生态不厚”的阶段很多玩法都需要自己拿脚本去堆。但正因为如此现在研究它的人能沉淀下来很多壁垒性的经验。等官方把更多事件类型、更多内置策略放出来之后早期这批踩坑的人会占很大便宜。如果你手头已经有Claude Code在跑项目建议从最小成本的PreToolUse审计开始试。先让它把所有工具调用都记下来跑三五天之后你再回看那个日志就会很自然地产出下一个自动化需求可能是危险命令拦截、可能是提交信息生成、也可能是自动标注意外行为。顺着需求往下做Hooks会成为你在AI工作流里最顺手的那把螺丝刀。