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把一次交互拆成了一根有节点的流水线。现阶段我经常用到的，主要是这六个事件：
| 事件 | 触发时机 | 典型用途 |
|---|---|---|
| PreToolUse | Claude调用任意工具之前 | 参数校验、敏感命令拦截、日志记录 |
| PostToolUse | 工具执行完成后 | 检查执行结果、自动格式化、触发后续动作 |
| UserPromptSubmit | 用户消息提交后、AI处理前 | 注入上下文、改写提问、加载项目规范 |
| Notification | Claude完成一次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\s+if=.*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读出JSON（Claude 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阶段如果脚本退出码非0，Claude 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个子代理，分别扫描不同模块的TODO，SubagentStop里写死一个累加器，每个子代理完工就把输出的摘要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_URL="http://localhost:1234/v1" export ANTHROPIC_AUTH_TOKEN="local-test-token" export ANTHROPIC_MODEL="local-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：命中的文件跑本地linter
- Stop：把本次会话的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工作流里最顺手的那把螺丝刀。
