1. 为什么要在 Claude Code 里折腾 hooksClaude Code 用久了会发现一个尴尬它写代码很快但有些动作你并不想让它自动做。比如它顺手rm -rf掉一个目录、把带SECRET的字符串写进源码、或者改完文件后忘了跑格式化。这些事靠人盯着不现实靠提示词约束也不稳真正靠谱的做法是挂 hooks——在工具调用前后插入你自己的脚本让规则由代码执行而不是靠模型自觉。hooks 是什么简单说就是 Claude Code 在特定生命周期节点触发的回调。它支持 PreToolUse工具执行前、PostToolUse工具执行后、UserPromptSubmit提交提示前、Stop响应结束等事件。你可以在这些节点上挂一段 shell 命令命令返回非零退出码就能拦截动作返回 0 就放行。适合谁适合已经把 Claude Code 当日常编码工具、想让自动化流程更可控的开发者尤其是团队里想统一规则、又不想每次口头提醒的人。零成本怎么理解不是指模型免费而是指你不需要额外买服务、不需要自建网关用一份统一的 Key 和 API 通道就能把 hooks 链路跑通。我试过在本地把 hooks 和统一 Key 接在一起整个链路从配置到验证大概十几分钟踩的坑主要集中在配置层级和退出码上。这篇就按「先讲场景 → 接 Key → 写配置 → 验证 → 排错 → 收尾」的顺序把可复制的片段都给你目标是一次跑通。核心检索词先点明Claude Code hooks 是一套事件回调机制能做什么能在工具执行前后拦截或追加动作适合谁适合想让编码流程自动化、可审计的开发者。下面进入实操。2. TaoToken 统一 Key 与 API 通道前置准备在写 hooks 之前得先让 Claude Code 能稳定调用模型。这里用 TaoToken 做统一入口好处是一个 Key 覆盖多种模型通道hooks 里如果要调用模型做二次判断比如让模型判断某条命令是否危险也能复用同一个通道不用再维护第二套凭证。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存。注意 Key 只在创建时完整显示一次丢了就重建。拿到 Key 后Claude Code 侧需要两个环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。Base URL 用https://taotoken.net/api不要带任何多余路径。环境变量写法分两种。临时生效直接在终端里 exportexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key永久生效写进 shell 配置文件。zsh 用户改~/.zshrcbash 用户改~/.bashrcecho export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.zshrc echo export ANTHROPIC_API_KEYsk-你的Key ~/.zshrc source ~/.zshrc验证环境变量是否生效echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY两条都应输出对应值。如果ANTHROPIC_API_KEY为空说明配置文件没 source 或者写错了文件。这一步别跳过后面 hooks 里如果调用模型读的就是这两个变量。关于模型 IDClaude Code 默认会用一个模型名如果你在 TaoToken 侧想指定具体模型可以在 settings 里配model字段。常见写法是claude-sonnet-4-5这类 ID具体以你账号下可用模型为准。三件套记牢Base URL、Key、Model ID缺一个都可能报 401 或模型不存在。注意Key 不要提交到 Git不要写进项目里的 settings.json 明文。项目级配置建议用环境变量引用或者放在settings.local.json并加入.gitignore。前置准备做完Claude Code 应该能正常对话了。可以先跑一句简单请求确认通道通再进入 hooks 配置。如果这一步就报错先解决通道问题别急着写 hooks否则排错会混在一起。3. 可复制的 settings.json hooks 配置片段Claude Code 的 hooks 配置放在 settings 文件里层级有三个项目级.claude/settings.json、用户级~/.claude/settings.json、本地不共享.claude/settings.local.json。团队共享的规则放项目级个人偏好放用户级含密钥或临时调试的放 local。hooks 字段的结构是「事件名 → 匹配器数组 → 命令」。下面给一份可直接复制的项目级.claude/settings.json覆盖 PreToolUse 和 PostToolUse 两个最常用事件。路径就是项目根目录下的.claude/settings.json原文一致别放错。{ model: claude-sonnet-4-5, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 .claude/hooks/guard_bash.py } ] } ], PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATH\ 2/dev/null || true } ] } ] } }逐段解释。model指定走 TaoToken 时用的模型 ID按你账号可用模型填。PreToolUse下matcher是Bash意思是只对 Bash 工具调用触发hooks数组里type为commandcommand是要执行的脚本路径。PostToolUse的matcher是Edit|Write用竖线表示匹配多个工具编辑或写入文件后触发 prettier 格式化。$CLAUDE_FILE_PATH是 Claude Code 注入的环境变量指向被操作的文件路径。不同版本变量名可能略有差异如果格式化没生效先打印一下所有CLAUDE_开头的变量确认env | grep CLAUDE_guard_bash.py 是拦截脚本放在.claude/hooks/下。它从 stdin 读 JSON里面包含工具名和参数判断命令是否危险危险就退出码 1 拦截安全就退出 0 放行。示例#!/usr/bin/env python3 import json import sys import re def main(): raw sys.stdin.read() try: payload json.loads(raw) except json.JSONDecodeError: sys.exit(0) command payload.get(tool_input, {}).get(command, ) danger [rrm\s-rf\s~, rrm\s-rf\s/, r:\(\)\{.*\};:] for pattern in danger: if re.search(pattern, command): print(fblocked dangerous command: {command}, filesys.stderr) sys.exit(1) sys.exit(0) if __name__ __main__: main()给脚本执行权限chmod x .claude/hooks/guard_bash.py如果你用 Cline MCP 或 Codex 的 auth.json 体系思路一样Base URL 填https://taotoken.net/apiKey 填你的 KeyModel ID 填可用模型。三件套对齐hooks 里调模型才不会 401。CC Switch 这类切换工具也是同样三个字段别只填 Key 漏了 Base URL。提示hooks 命令默认超时 60 秒复杂脚本要拆分或加超时控制。格式化这种快操作没问题跑全量测试就可能超时。配置保存后 Claude Code 会提示复审设置变更确认即可。hooks 不需要重启保存即生效。这一步做完链路已经搭好一半接下来验证。4. 触发验证与成功结果确认配置写完不验证等于没写。验证分三层脚本本身能跑、hooks 被触发、拦截和放行都符合预期。先单独测脚本。手动喂一段 JSON 给 guard_bash.pyecho {tool_input:{command:rm -rf ~/test}} | python3 .claude/hooks/guard_bash.py echo exit code: $?预期输出blocked dangerous command: rm -rf ~/test退出码 1。再喂一条安全命令echo {tool_input:{command:ls -la}} | python3 .claude/hooks/guard_bash.py echo exit code: $?预期无输出退出码 0。脚本层通过后再验证 Claude Code 是否真的调用它。在 Claude Code 里输入一句会触发 Bash 的请求比如「帮我删除 ~/test 目录」。如果 hooks 生效你会看到命令被拦截Claude Code 提示 hook 返回非零退出码动作没有执行。这就是 PreToolUse 拦截成功的标志。再验证 PostToolUse。让 Claude Code 编辑一个.js文件故意写成乱格式const a{b:1,c:2}保存后如果 prettier hook 生效文件会被自动格式化成const a { b: 1, c: 2 };打开文件确认格式变了说明 PostToolUse 触发成功。如果没变先确认 prettier 是否安装、$CLAUDE_FILE_PATH是否有值。验证模型通道是否走 TaoToken可以在 Claude Code 里问一句「你当前使用的模型 ID 是什么」或者看请求日志。更直接的方式是临时改错 Key看是否报 401确认请求确实打到 TaoToken。确认后改回正确 Key。成功结果长这样危险命令被拦、安全命令放行、编辑后自动格式化、模型请求正常返回。四件事都过hooks 链路就算跑通。任何一件不过进下一节排错。5. 常见报错与失败排查清单排错按「报错信息 → 可能原因 → 处理」来下面都是真实会遇到的。401 Unauthorized。原因通常是 Key 错、Key 过期、或者 Base URL 写错。检查echo $ANTHROPIC_API_KEY是否有值echo $ANTHROPIC_BASE_URL是否为https://taotoken.net/api。如果 Key 是从别处复制的注意有没有多余空格或换行。重建一个 Key 再试是最快的排除法。local proxy failed 或连接被拒。这类多半是 Base URL 带了多余路径比如写成https://taotoken.net/api/v1。正确写法就是https://taotoken.net/api不要加后缀。另外检查本机网络是否能正常访问该域名公司网络限制的话换网络环境再试。reading choices 相关报错。通常是响应结构不符合预期可能模型 ID 填错或者请求打到了不兼容的端点。确认model字段是你账号下真实可用的 ID别照抄网上的示例。三件套 Base URL、Key、Model ID 再对一遍。OAuth 相关报错。如果你之前用 OAuth 登录过别的通道环境变量可能被覆盖。检查 shell 配置文件里有没有旧的ANTHROPIC_变量清掉再 source。env | grep ANTHROPIC能列出所有相关变量逐个核对。hooks 不触发。先确认 settings 文件路径对不对项目级是.claude/settings.json不是项目根目录的settings.json。再确认 JSON 语法合法用python3 -m json.tool .claude/settings.json校验。matcher 写错也会导致不触发比如工具名大小写不对。hook 脚本报权限错误。chmod x给过权限了吗如果脚本用 python3 调用确认 python3 在 PATH 里。脚本第一行 shebang 写对#!/usr/bin/env python3。hook 超时。默认 60 秒格式化、lint 这类快操作没问题跑测试或构建容易超时。把重操作拆成异步或者只对特定文件类型触发减少执行次数。格式化没生效。$CLAUDE_FILE_PATH可能为空先env | grep CLAUDE_确认变量名。prettier 没装的话npx prettier会失败加|| true只是吞掉错误不解决根本问题先本地装好。拦截太激进。guard 脚本正则写太宽把正常命令也拦了。先用echo打印实际收到的 command 字段确认匹配逻辑再收窄正则。宁可先松后紧别一上来就全拦。排查顺序建议先通道401/连接→ 再配置JSON 语法/路径→ 再脚本权限/退出码→ 最后匹配器matcher/变量。一层层过别跳。6. 把 hooks 用起来的几个实用建议链路跑通后别急着堆一堆规则。先从一两条有即时反馈的开始比如格式化 hook 和危险命令拦截这两类效果肉眼可见调试也直观。规则多了之后每个 hook 的退出码和输出都要能看懂否则出问题不知道是哪条拦的。自动生成的规则文件哪怕是工具帮你写的也要人工过一遍。正则匹配范围、退出码逻辑、有没有误伤正常操作这些机器判断不了。把.claude/hooks/和 settings 纳入 Git 管理团队共享规则的同时也能追溯谁改了什么。hooks 能执行任意 shell 命令权限跟你的用户一致配置不当有风险。别从不可信来源直接复制 hook 脚本尤其是带网络请求或文件删除的。Claude Code 在设置变动后会提示复审认真看别一路回车。需要长期跑编码任务或 Agent 流程的可以了解下 Coding Plan把 hooks 和统一通道结合起来用规则和凭证都集中管理。验证模型通道是否正常用模型对话页面快速试一句就行。接入细节和更多配置示例在接入文档里排障时对照着看比盲猜快。最后一句实操经验hooks 的调试成本主要在「不知道有没有触发」所以每个脚本开头加一行日志到临时文件触发时写入时间戳和参数排查时一目了然。跑通之后把这行日志去掉保持干净。