1. Claude Code hooks 不执行的真实场景与排查思路
Claude Code 的 hooks 机制，简单说就是在工具调用前后自动跑一段命令。PreToolUse 在 Claude 准备执行工具（比如改文件、跑命令）之前触发，PostToolUse 在工具执行完之后触发。你可以用它做 lint、format、typecheck、日志记录，甚至拦截危险操作。适合谁？适合已经在用 Claude Code 写代码、想让流程自动化的开发者，尤其是团队里想统一代码规范的场景。
但很多人第一次配 hooks 就翻车：明明.claude/settings.json里写了PreToolUse，跑claude --auto-approve "修改 src/index.js"之后 lint 和 format 一个都没执行。或者直接报Error: Hook 'PreToolUse' failed、Hook timeout、Unknown hook event: 'pre_tool_use'。这类「Claude hooks not executing / Pre-post hooks skipped」的问题，我实测下来原因集中在几个点：JSON 格式写错、事件名大小写不对、hooks 值写成了字符串而不是数组、命令路径找不到、超时太短、配置文件放错目录、版本太旧不支持 hooks。
这篇就按「先定位、再修复、最后验证」的顺序，把可复制的settings.json片段和逐条验证动作给你。同时我会说明怎么把 endpoint 和鉴权统一改到 TaoToken 通道，避免因为网络或鉴权问题让 hook 触发链路看起来「没反应」。你跟着做，基本能覆盖 90% 以上的 hooks 不执行场景。
排查的核心思路是：hooks 不执行，不一定是 hooks 本身的问题，也可能是 Claude Code 根本没加载到你的配置，或者工具调用压根没发生。所以验证要分层——先确认配置被加载，再确认事件被触发，最后确认命令能跑通。
2. TaoToken 前置：统一 endpoint 与鉴权，排除链路干扰
在排查 hooks 之前，我建议先把 Claude Code 的请求通道固定下来。原因很实际：如果你的 endpoint 或鉴权不稳定，工具调用可能中途失败，hooks 自然看起来「被跳过」。把通道统一到 TaoToken，能让「配置加载 → 工具调用 → hook 触发」这条链路更可控。
TaoToken 是一个面向开发者的模型调用统一入口，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。它适合谁？适合需要稳定调用 Claude 系列模型、又想把 key 和 endpoint 集中管理的开发者。你可以在控制台创建 API Key，然后在 Claude Code 里把 Base URL 指向 TaoToken 的 API 地址。
具体操作上，先到控制台生成 key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。生成后复制保存，后面配置里要用。如果你还没决定用哪个模型，可以先在模型对话页试试：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，确认模型能正常返回，再去配 Claude Code。
这里要强调一个排查逻辑：hooks 不执行时，先确认 Claude Code 本身能正常完成一次工具调用。如果连工具调用都失败，hooks 当然不会触发。把 endpoint 和鉴权改到 TaoToken 统一通道后，你可以用一次简单的文件修改任务来验证链路是否通。链路通了，再去看 hooks 配置，问题范围就缩小了很多。
配置 Claude Code 使用 TaoToken 时，核心是三件套：Base URL、API Key、Model ID。Base URL 填https://taotoken.net/api，API Key 填你在控制台生成的那串，Model ID 填你要用的模型名。这三样缺一不可，而且要和 hooks 配置分开检查——hooks 是本地执行逻辑，endpoint 是网络请求逻辑，两者互不干扰，但都会影响你看到的最终现象。
如果你用的是 Claude Code 的 coding plan 或长期编码场景，可以了解下 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它更适合需要持续调用、频繁触发工具调用的工作流，hooks 在这种场景下价值最大。
3. 可复制的 settings.json hooks 配置与逐条验证
这一节是重点。先给你一份可以直接复制的.claude/settings.json，路径是项目根目录下的.claude/settings.json。注意 hooks 的值必须是数组，事件名必须是大驼峰。
{ "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "npm run lint" } ] } ], "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "npm run format" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "echo 'session done'" } ] } ] } }如果你用的是更早的简化写法，也见过这种形式：
{ "hooks": { "PreToolUse": ["npm run lint"], "PostToolUse": ["npm run format"] } }两种写法取决于你的 Claude Code 版本。关键是：事件名PreToolUse、PostToolUse必须大写驼峰，不能写成pre_tool_use或preToolUse。hooks 的值如果是字符串而不是数组，很多版本会直接忽略。
配好之后，逐条验证。第一步，验证 JSON 合法性：
python3 -m json.tool .claude/settings.json如果输出格式化后的 JSON，说明格式没问题；如果报错，先修 JSON。第二步，确认配置文件位置。必须在项目根目录：
pwd ls -la .claude/settings.json第三步，确认 Claude Code 加载了配置：
claude --debug 2>&1 | grep -i "hook\|settings"你应该能看到类似Loaded settings from .claude/settings.json和 hook 注册相关的日志。如果完全看不到 settings 加载记录，说明文件位置或权限有问题。
第四步，触发一次工具调用。用一个明确会改文件的任务：
claude --auto-approve "在 src/index.js 末尾加一行注释"观察终端输出里有没有 hook 执行记录。如果 lint 命令本身有输出，你应该能看到。第五步，如果怀疑超时，临时加大超时：
{ "hooks": { "PreToolUse": ["npm run lint"], "hookTimeout": 60000 } }或者用环境变量：
export CLAUDE_HOOK_TIMEOUT=60000第六步，检查命令是否存在、是否可执行：
which npm npm run lint如果手动跑都失败，hook 里更不可能成功。必要时用绝对路径，比如/usr/local/bin/npm run lint。
把 endpoint 和鉴权改到 TaoToken 的操作，和 hooks 配置是分开的。你可以在 Claude Code 的配置里设置 Base URL 为https://taotoken.net/api，API Key 用控制台生成的那串。这样工具调用走统一通道，hooks 在本地执行，两者各司其职。验证时先确认工具调用成功，再看 hooks 日志。
4. 验证请求与成功结果：从日志确认 hooks 真的跑了
验证 hooks 是否执行，最直接的办法是看 debug 日志。跑：
claude --debug 2>&1 | grep -i hook成功的输出里，你应该能看到 PreToolUse 在工具调用前被触发、命令开始执行、退出码为 0，然后 PostToolUse 在之后触发。如果 hook 命令有 stdout，也会出现在日志里。
另一种验证方式是在 hook 命令里加一个明显的副作用，比如写文件：
{ "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "echo \"pre-hook triggered at $(date)\" >> /tmp/claude-hook.log" } ] } ] } }然后触发一次文件修改，再去看：
cat /tmp/claude-hook.log如果文件里有记录，说明 hook 确实执行了。这个方法特别适合排查「命令跑了但没输出」的情况。
成功结果还包括：工具调用正常完成、lint 和 format 按预期生效、没有Hook failed或Hook timeout报错。如果你把通道切到 TaoToken，还要确认请求返回正常，没有 401 或连接错误。401 通常意味着 API Key 不对或没带上；连接错误则要检查 Base URL 是否写成了https://taotoken.net/api。
我试过在同一个项目里同时验证 hooks 和通道：先跑一次不带 hooks 的任务确认模型调用通，再加上 hooks 确认本地命令执行。两步分开，出问题时定位快很多。如果两步都通过，但合起来失败，那大概率是 hook 命令本身影响了工具调用的退出状态，比如 lint 返回非零导致整个 hook 被标记为 failed。
5. 本篇常见错误排查：401、local proxy failed、reading choices、OAuth
这一节对照真实报错逐条排查。第一类，鉴权相关。如果你看到401 Unauthorized，检查 API Key 是否正确、是否过期、请求头有没有带上。用 TaoToken 的话，确认 key 是在控制台生成的，并且 Base URL 是https://taotoken.net/api。API Keys 管理页：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。
第二类，local proxy failed。这通常和本地网络配置有关，不是 hooks 本身的问题。先确认你的 endpoint 配置正确，再确认没有多余的本地转发设置干扰。把通道统一到 TaoToken 后，这类问题会少很多。
第三类，error reading choices或类似响应解析错误。这往往说明返回体不是预期的模型响应格式，可能是 endpoint 指错了，或者请求被中间层改写了。检查 Base URL 和 Model ID 是否匹配。
第四类，OAuth 相关报错。如果你用的是需要 OAuth 的客户端，确认 token 刷新正常。Claude Code 的鉴权配置和 hooks 配置是两套东西，别混在一起改。
第五类，hooks 配置本身。Unknown hook event: 'pre_tool_use'说明事件名写错了，改成PreToolUse。Hook 'PreToolUse' failed说明命令返回非零，手动跑一遍命令修好它。Hook timeout说明超过默认 30 秒，加hookTimeout或环境变量。
如果你用 CC Switch、Cline MCP 或 Codex 的auth.json，记得三件套要写全：Base URL、Key、Model ID。缺一个都可能导致调用失败，进而让你误以为 hooks 没执行。接入文档在这里：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
排查清单可以按这个顺序走：先python3 -m json.tool验证 JSON，再确认事件名大写驼峰，再确认 hooks 值是数组，再手动跑 hook 命令，再用which检查命令存在，再考虑绝对路径和超时，最后确认配置文件在项目根目录、版本支持 hooks。每一步都能缩小范围。
6. 把 hooks 接入 TaoToken 统一通道的长期做法
长期来看，hooks 要稳定执行，前提是工具调用链路稳定。把 endpoint 和鉴权统一到 TaoToken，能减少因为网络或鉴权波动导致的「假性 hooks 不执行」。具体做法：在 Claude Code 配置里固定 Base URL 为https://taotoken.net/api，API Key 用控制台统一管理，Model ID 按项目需要选。
如果你做的是长期编码或 Agent 类工作流，hooks 会频繁触发，这时候通道稳定性尤其重要。Coding Plan 更适合这种场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它和 hooks 配合，能把 lint、format、测试这些动作自动化。
配置时记住三件套：Base URL、Key、Model ID。Claude Code 的 hooks 配置放在.claude/settings.json，通道配置放在对应的鉴权位置，两者分开维护。验证时先确认模型调用通，再确认 hooks 触发。遇到 401 查 key，遇到 timeout 加超时，遇到事件名错误改大小写。
最后给你一个实用技巧：在 hook 命令里加时间戳日志，写到/tmp下。这样每次触发都有记录，排查时不用猜。配合claude --debug 2>&1 | grep -i hook，基本能定位所有 hooks 不执行的问题。通道方面，需要生成 key 就去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，需要看接入细节就去 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。把这两块都固定下来，hooks 该跑的时候就会跑。
