1. 为什么 Claude Code 需要 Hooks从“AI 说它跑过了”到“真的跑过了”如果你用 Claude Code 写过一段时间代码大概率遇到过这种场景让它改完一个函数它回复“已完成测试通过”但你手动跑一遍npm test红的。或者它生成的代码风格和项目里 Prettier 配置完全对不上缩进两格变四格单引号变双引号。再或者它在你没注意的时候往代码里塞了一个console.log提交上去被同事在 Review 里圈出来。这些问题的根源不是 Claude Code 不会写代码而是它缺少一个“在正确时机自动执行正确动作”的机制。Hooks 就是补上这一环的东西。它让你在 Claude Code 的工作流里插入检查点文件保存时自动格式化、提交前自动跑测试、代码里出现敏感词时自动扫描、任务完成时自动提醒。你不需要每次手动敲命令也不需要反复在对话里提醒它“记得跑测试”——Hooks 会在事件触发时自动执行。这篇文章围绕四个真实场景展开保存即格式化、提交前跑测试、敏感词扫描、任务完成提醒。每个场景我都会给出settings.json里的配置骨架、TaoToken 统一 Key/API 通道的接入方式以及逐条验证动作。你跟着配完每条 Hook 都能复现生效。2. TaoToken 前置统一 Key 与 API 通道在配置 Hooks 之前先把模型调用通道理清楚。Claude Code 本身是一个客户端工具它需要连接到一个兼容 Anthropic API 的服务端点。TaoToken 提供的就是这个通道一个统一的 Key一个统一的 API 地址让你在 Claude Code、Coding Plan、模型对话等多个入口之间不用反复切换配置。你需要准备的东西很简单一个 TaoToken 账号登录后进入控制台在 API Keys 页面生成一个 Key复制保存确认 API 端点地址为https://taotoken.net/api配置方式有两种。第一种是环境变量适合在终端里直接跑 Claude Code 的场景export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的TaoToken Key第二种是写进 Claude Code 的配置文件适合长期使用。配置文件通常位于~/.claude/settings.json或项目根目录的.claude/settings.json。Hooks 的配置也写在这个文件里所以后面我们会把 Key 配置和 Hooks 配置放在同一个文件中管理。注意API 地址不要加 UTM 参数直接使用https://taotoken.net/api即可。控制台和 API Keys 页面在配置过程中会用到建议提前打开。如果你还没有 Key可以先去控制台创建。整个流程不需要额外安装任何东西Claude Code 本身通过 npm 安装后就能用。3. 可复制配置settings.json 中的 Hooks 骨架Claude Code 的 Hooks 配置写在settings.json的hooks字段里。每个 Hook 由三部分组成触发事件event、匹配条件matcher、执行命令command。下面是一个完整的配置骨架包含四个场景的 Hook 定义。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key }, hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATH\ 2/dev/null || true } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \[Hook] 即将执行命令: $CLAUDE_TOOL_INPUT\ .claude/hook-audit.log } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: bash .claude/hooks/on-stop.sh } ] } ] } }这个骨架里包含了三个事件类型PostToolUse在工具调用完成后触发适合做格式化和扫描PreToolUse在工具调用前触发适合做审计和拦截Stop在 Claude Code 完成一轮任务后触发适合做提醒和汇总。3.1 保存即格式化PostToolUse Prettier第一个场景是文件保存后自动格式化。Claude Code 在写入或编辑文件后会触发PostToolUse事件我们在这个事件上挂一个 Prettier 命令。{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATH\ 2/dev/null || true } ] } ] } }这里的$CLAUDE_FILE_PATH是 Claude Code 传入的环境变量指向被修改的文件路径。matcher字段用正则匹配工具名称Write|Edit表示文件写入和编辑操作都会触发。|| true的作用是即使 Prettier 报错也不阻断后续流程避免因为格式化工具本身的问题导致 Claude Code 卡住。如果你用的是 Python 项目把命令换成black或ruff format即可{ command: ruff format \$CLAUDE_FILE_PATH\ 2/dev/null || true }3.2 提交前跑测试PreToolUse 测试命令第二个场景是在 Claude Code 执行git commit之前自动跑测试。这里用PreToolUse事件匹配Bash工具然后检查命令内容是否包含git commit。{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: if echo \$CLAUDE_TOOL_INPUT\ | grep -q git commit; then npm test -- --passWithNoTests 21 | tail -20; fi } ] } ] } }这段命令的逻辑是如果 Claude Code 准备执行的 Bash 命令里包含git commit就先跑npm test并把最后 20 行输出打印出来。如果测试失败输出会显示在 Claude Code 的对话里你可以根据结果决定是否继续提交。注意这个 Hook 不会自动阻断提交它只是把测试结果展示出来。如果你希望测试失败时直接阻止提交可以把命令改成npm test || exit 1这样非零退出码会中断后续操作。3.3 敏感词扫描PostToolUse grep 检查第三个场景是扫描代码中是否出现了不该出现的敏感词比如硬编码的密钥、调试用的console.log、或者团队约定的禁用 API。{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: grep -nE (API_KEY|SECRET|password|console\\.log) \$CLAUDE_FILE_PATH\ echo [警告] 发现敏感词请检查 || true } ] } ] } }这个命令会在文件被修改后立即扫描如果匹配到敏感词就打印行号和警告信息。grep的-n参数显示行号-E启用扩展正则。匹配到内容时grep返回 0后面的 echo 会执行没匹配到时grep返回非零|| true保证整体退出码为 0不阻断流程。你可以根据项目需要调整正则表达式。比如加上TODO|FIXME来追踪待办事项或者加上内部域名、测试账号等。3.4 任务完成提醒Stop 自定义脚本第四个场景是 Claude Code 完成一轮任务后发送提醒。Stop事件在 Claude Code 结束当前回合时触发适合做汇总通知。先创建一个脚本文件.claude/hooks/on-stop.sh#!/bin/bash TIMESTAMP$(date %Y-%m-%d %H:%M:%S) echo [$TIMESTAMP] Claude Code 任务完成 .claude/hook-audit.log if command -v notify-send /dev/null; then notify-send Claude Code 任务已完成请检查变更 fi然后在settings.json里挂上这个脚本{ hooks: { Stop: [ { matcher: , hooks: [ { type: command, command: bash .claude/hooks/on-stop.sh } ] } ] } }matcher为空字符串表示匹配所有 Stop 事件。脚本里做了两件事写审计日志、发送桌面通知如果系统支持notify-send。如果你在 macOS 上可以把通知命令换成osascript -e display notification 任务已完成 with title Claude Code。4. 验证请求与成功结果配置写完后需要逐条验证 Hook 是否真的生效。下面是我实际跑过的验证步骤和预期结果。4.1 验证格式化 Hook在项目里创建一个测试文件故意写成不符合 Prettier 规范的格式const x1;const y 2 function test( ){return xy}然后在 Claude Code 里让它编辑这个文件比如“把 test 函数的返回值改成 x*y”。编辑完成后打开文件检查格式是否被自动修正。如果 Prettier 生效你会看到代码变成了const x 1; const y 2; function test() { return x * y; }如果格式没变检查settings.json里的路径是否正确以及npx prettier是否能在项目根目录下正常运行。4.2 验证测试 Hook在 Claude Code 里输入“帮我提交当前变更”它会尝试执行git commit。此时观察对话输出应该能看到npm test的运行结果。如果测试通过输出里会有绿色的 PASS 行如果失败会显示具体的失败用例。你也可以手动触发验证在 Claude Code 里执行git commit -m test看 Hook 是否拦截并展示测试输出。4.3 验证扫描 Hook创建一个包含敏感词的文件const API_KEY sk-test-123; console.log(debug);让 Claude Code 编辑这个文件保存后观察对话里是否出现[警告] 发现敏感词以及对应的行号。如果没出现检查grep命令里的正则是否匹配到了你的测试内容。4.4 验证提醒 Hook让 Claude Code 完成一个简单任务比如“在当前目录创建一个 hello.txt 文件”。任务结束后检查.claude/hook-audit.log是否多了一行时间戳记录。如果系统支持桌面通知还应该看到弹窗。5. 本篇常见错排查配置 Hooks 的过程中有几个坑我踩过这里列出来帮你省时间。Hook 不触发最常见的原因是settings.json的路径不对。Claude Code 会读取项目根目录的.claude/settings.json和用户目录的~/.claude/settings.json两个文件会合并。如果你改的是项目里的文件但没生效检查一下是不是被用户目录的配置覆盖了。环境变量为空$CLAUDE_FILE_PATH和$CLAUDE_TOOL_INPUT是 Claude Code 注入的变量不是系统环境变量。如果你在脚本里直接echo $CLAUDE_FILE_PATH发现是空的说明当前事件类型不提供这个变量。比如Stop事件就没有文件路径只有PostToolUse和PreToolUse才有。命令执行超时Hooks 默认有超时限制如果npm test跑太久会被中断。建议在 Hook 里只跑快速测试比如npm test -- --testPathPatternchanged或者用--bail参数让测试在第一个失败时停止。Prettier 找不到配置文件如果项目里的 Prettier 配置在子目录npx prettier可能读不到。可以在命令里显式指定配置路径npx prettier --config .prettierrc --write $CLAUDE_FILE_PATH。Hook 输出太多刷屏npm test的完整输出可能很长建议用tail -20或head -30截断。我在配置里用了tail -20只展示最后 20 行足够判断测试是否通过。Windows 环境兼容性上面的命令都是 bash 语法在 Windows 的 CMD 或 PowerShell 里需要调整。建议在 Windows 上使用 Git Bash 或 WSL 来运行 Claude Code这样 Hook 命令可以直接复用。6. 把 Hooks 接入你的日常流程四个场景配下来你会发现 Hooks 的核心价值不是“自动化”本身而是把那些“理应发生但容易被遗忘”的检查变成了默认行为。格式化、测试、扫描、提醒这四件事单独看都不复杂但每次手动执行都会消耗注意力。Hooks 把它们从待办清单里移除让你专注于代码逻辑本身。如果你还没有配置 TaoToken 的 API 通道建议先去控制台创建一个 Key然后把settings.json里的env字段填好。模型对话入口可以用来快速验证 Key 是否有效Coding Plan 适合长期编码场景接入文档里有更详细的参数说明。配置完成后从格式化 Hook 开始逐条验证确认每条都生效后再逐步加上测试和扫描。不要一次性全开否则出问题时排查起来会很麻烦。最后提醒一点Hooks 是辅助机制不是替代品。它不能替你判断代码逻辑是否正确也不能替代 Code Review。它的作用是确保你提交的代码在格式、测试、安全扫描这些可程序化定义的维度上始终处于可控状态。把规则定义清楚让系统自动执行你只需要在关键节点做决策。
