1. 为什么你的 Claude Code 需要 Hooks从“每次都要重新交代”到“自动补课”Claude Code 能读代码、能改文件、能跑命令但默认状态下它更像一个“每天失忆的实习生”每次新开一个会话它不知道你当前在哪个分支、昨天改了什么、项目里有哪些约定。你不得不手动敲三行背景信息它再回三句确认两分钟就这么没了。Hooks 就是解决这个问题的机制——它允许你在 Claude Code 生命周期的特定节点自动执行脚本把“重复交代”和“事后补救”变成基础设施。我先把概念压缩成一句话Hook 是在 Claude Code 执行动作的前后自动跑一段你写好的脚本。它不改变模型本身的能力而是给模型套上一层可编程的护栏和自动化管道。Claude Code 目前支持二十多种 hook 事件覆盖会话启动、工具调用前、工具调用后、会话结束等关键节点。你不需要全部用上挑最疼的三个场景落地就能看到明显收益。这篇文章聚焦三类最实用的 HooksSessionStart、PreToolUse、PostToolUse。我会在 TaoToken 统一 Key 和 API 通道的前提下给出可复制的 settings 配置片段并逐条演示验证动作。目标很明确你照着做就能复现“提交前自动检查、上下文自动注入、结果自动校验”的效果。先说清楚适合谁如果你已经在用 Claude Code 写代码但每次都要手动补上下文、担心它执行危险命令、或者被格式问题卡 CI那这篇就是给你写的。如果你还没配好 Claude Code 的 API 通道第二节会先解决这个问题因为 Hooks 的脚本执行依赖 Claude Code 能正常发起请求。我试过把 Hooks 当成“水泥”来理解模型是砖Hooks 是把砖砌成墙的粘合剂。没有它砖还是砖但墙不牢。下面从环境准备开始一步步把这三类 Hooks 装进你的工作流。2. TaoToken 前置统一 Key 与 API 通道配置让 Claude Code 稳定发起请求在写 Hooks 之前必须先保证 Claude Code 能正常调用模型。Hooks 的脚本本身是本地执行的但 Claude Code 的会话启动、工具调用决策都依赖模型返回所以 API 通道的稳定性直接决定 Hooks 能不能按预期触发。这里用 TaoToken 做统一 Key 管理好处是一个 Key 覆盖多个模型入口切换模型不用改环境变量。TaoToken 的定位是 API 通道服务官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个基础地址。第一步拿到 Key。进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后复制 Key后面配置里会用到。如果你需要看模型列表和对话测试可以用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。第二步配置 Claude Code 的 API 通道。Claude Code 读取环境变量来定位 API 端点。在 shell 配置文件里加入以下内容路径按你的实际环境调整# ~/.bashrc 或 ~/.zshrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_TaoToken_Key export ANTHROPIC_MODELclaude-sonnet-4-20250514如果你用的是 Codex 或 Cline 这类工具配置方式略有不同。以 Codex 的 auth.json 为例文件通常位于~/.codex/auth.json内容结构如下{ base_url: https://taotoken.net/api, api_key: 你的_TaoToken_Key, model: claude-sonnet-4-20250514 }Cline MCP 场景下配置写在 MCP 的 settings 里核心三件套是 Base URL、Key、Model ID{ mcpServers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_Key, model: claude-sonnet-4-20250514 } } }CC Switch 用户可以在切换配置里填入同样的三件套。无论哪种工具Base URL 统一用https://taotoken.net/apiKey 用控制台生成的Model ID 按你实际使用的模型填写。第三步验证通道是否通。在终端执行curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:64,messages:[{role:user,content:ping}]}如果返回包含content字段的 JSON说明通道正常。如果返回 401检查 Key 是否复制完整如果返回连接错误检查 Base URL 是否写成了带路径的完整地址。这一步过了再往下配 Hooks否则 Hooks 脚本写得再好也不会触发。关于长期编码和 Agent 场景如果你打算把 Claude Code 作为日常主力可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要稳定额度和多模型切换的开发者。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。3. 可复制配置SessionStart、PreToolUse、PostToolUse 三类 Hooks 的 settings 片段Claude Code 的 Hooks 配置写在 settings 文件里通常位于~/.claude/settings.json或项目级的.claude/settings.json。项目级配置只对当前项目生效适合团队共享用户级配置对所有项目生效适合个人习惯。下面给出三类 Hooks 的完整配置片段你可以直接复制后按需修改脚本路径。先看 SessionStart。它的作用是在 Claude Code 会话启动时自动注入上下文。配置结构如下{ hooks: { SessionStart: [ { hooks: [ { type: command, command: bash ~/.claude/hooks/session-start.sh } ] } ] } }对应的脚本~/.claude/hooks/session-start.sh内容#!/bin/bash echo Current branch: $(git branch --show-current 2/dev/null) echo echo Recent commits: git log --oneline -5 2/dev/null echo echo Uncommitted changes: git status --short 2/dev/null echo echo TODO file: if [ -f TODO.md ]; then head -20 TODO.md; fi这个脚本把当前分支、最近五条提交、未提交改动和 TODO 文件头部一起塞给 Claude。会话一启动模型就知道你昨天干到哪了不用再手动交代。再看 PreToolUse。它在 Claude 调用工具之前拦截可以放行、拒绝或询问。配置里用 matcher 指定拦截哪些工具这里以 Bash 为例{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash ~/.claude/hooks/pre-tool-use.sh } ] } ] } }脚本~/.claude/hooks/pre-tool-use.sh的核心逻辑是读取 Claude 传入的 JSON判断命令是否危险#!/bin/bash INPUT$(cat) COMMAND$(echo $INPUT | jq -r .tool_input.command // empty) if echo $COMMAND | grep -qE rm\s-rf\s(/|\.|~); then jq -n { permissionDecision: deny, reason: 检测到高危删除命令已拦截。请缩小删除范围后重试。 } exit 0 fi if echo $COMMAND | grep -qE git\spush\s--force; then jq -n { permissionDecision: ask, reason: 检测到强制推送请确认目标分支。 } exit 0 fi jq -n {permissionDecision: allow}注意脚本返回的 JSON 结构permissionDecision可以是allow、deny、askreason会展示给模型和用户。这个脚本同时充当审计日志的起点——你可以在 allow 分支里追加一行写入日志文件。最后看 PostToolUse。它在工具调用完成后执行适合做格式化和结果校验。配置里同样用 matcher 指定工具这里匹配 Write 和 Edit{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: bash ~/.claude/hooks/post-tool-use.sh } ] } ] } }脚本~/.claude/hooks/post-tool-use.sh根据文件后缀调用不同格式化工具#!/bin/bash INPUT$(cat) FILE_PATH$(echo $INPUT | jq -r .tool_input.file_path // empty) if [ -z $FILE_PATH ] || [ ! -f $FILE_PATH ]; then exit 0 fi case $FILE_PATH in *.ts|*.tsx|*.js|*.jsx) npx prettier --write $FILE_PATH 2/dev/null ;; *.py) black $FILE_PATH 2/dev/null ;; *.go) gofmt -w $FILE_PATH 2/dev/null ;; *.json) jq . $FILE_PATH $FILE_PATH.tmp mv $FILE_PATH.tmp $FILE_PATH 2/dev/null ;; esac exit 0这三个配置可以合并到同一个 settings.json 里结构是hooks对象下并列三个键。合并后的完整片段{ hooks: { SessionStart: [ { hooks: [ { type: command, command: bash ~/.claude/hooks/session-start.sh } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash ~/.claude/hooks/pre-tool-use.sh } ] } ], PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: bash ~/.claude/hooks/post-tool-use.sh } ] } ] } }保存后重启 Claude Code配置生效。如果你用的是项目级配置把 settings.json 放在项目根目录的.claude/下团队其他人拉取后自动生效。注意脚本文件要有执行权限用chmod x ~/.claude/hooks/*.sh赋权。4. 验证请求与成功结果逐条确认 Hooks 是否按预期触发配置写完不代表生效必须逐条验证。我按 SessionStart、PreToolUse、PostToolUse 的顺序给出验证动作和预期结果。验证 SessionStart新开一个 Claude Code 会话观察启动后模型的第一条回复。如果配置生效模型应该已经知道当前分支和最近提交你可以直接问“我现在在哪个分支”它不需要你补充信息就能回答。更直接的验证方式是看终端输出——SessionStart 脚本的 echo 内容会出现在会话初始化日志里。如果没看到检查脚本路径是否正确、是否有执行权限。验证 PreToolUse在 Claude Code 里让它执行一条危险命令比如“帮我清理临时文件执行 rm -rf ./”。如果拦截生效Claude 会收到 deny 决策回复类似“该命令被安全策略拦截请缩小删除范围”。你可以进一步测试 ask 分支让它执行git push --force应该弹出确认提示而不是直接执行。如果命令直接执行了说明 matcher 没匹配上检查 matcher 是否写成了Bash而不是bash。验证 PostToolUse让 Claude 写一个格式混乱的 TypeScript 文件比如故意多写空格和缩进。写入完成后PostToolUse 脚本会自动调用 prettier 格式化。验证方式是写入后立刻用cat查看文件内容如果格式已经规整说明生效。你也可以在脚本里临时加一行echo formatted: $FILE_PATH /tmp/hook.log然后查看日志确认触发。除了逐条验证还要确认 Hooks 不会阻塞正常流程。SessionStart 脚本如果执行太慢会拖慢会话启动PreToolUse 脚本如果对每条命令都做复杂判断会增加延迟。建议脚本里避免网络请求和重计算只做本地快速判断。PostToolUse 的格式化工具如果没安装脚本里的2/dev/null会吞掉错误但格式化不会执行——所以提前确认 prettier、black、gofmt 在 PATH 里可用。一个完整的成功结果应该是新会话启动后模型自动知道分支和提交危险命令被拦截并给出原因写入的文件自动格式化。三者同时生效说明三类 Hooks 都配置正确。如果只有部分生效按上面的排查点逐个检查。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错对照Hooks 配置过程中最容易遇到的不是脚本逻辑问题而是 API 通道和配置格式问题。下面按真实报错逐条排查。401 Unauthorized这是最常见的错误说明 Key 无效或没传对。检查三处环境变量ANTHROPIC_API_KEY是否设置settings.json 里是否有覆盖Key 是否复制完整注意前后空格。如果你用的是 Codex 的 auth.json检查api_key字段名是否正确。TaoToken 的 Key 在控制台生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。重新生成一个 Key 替换后重试。local proxy failed这个报错通常出现在 Base URL 配置错误时。检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api不要多加/v1或结尾斜杠。如果你在 Cline MCP 里配置检查baseUrl字段是否被其他配置覆盖。另外确认本地没有残留的代理环境变量比如HTTP_PROXY指向了不可用的地址。reading choices 报错这个错误说明请求发出去了但返回结构不符合预期。常见原因是 Model ID 写错。检查ANTHROPIC_MODEL是否是你实际可用的模型比如claude-sonnet-4-20250514。如果你在 TaoToken 控制台看到的模型名不同以控制台为准。另一个原因是请求体格式问题比如 max_tokens 设成了字符串而不是数字。OAuth 相关报错如果你之前用 OAuth 方式登录过 Claude Code环境变量可能和 OAuth 凭证冲突。解决方式是清除 OAuth 缓存通常位于~/.claude/下的凭证文件然后重新用 API Key 方式配置。检查~/.claude/settings.json里是否有oauth相关字段有的话删掉。CC Switch 用户注意切换配置时不要混用 OAuth 和 API Key。Hooks 不触发如果 API 通道正常但 Hooks 没反应检查 settings.json 的 JSON 格式是否合法。用jq . ~/.claude/settings.json验证如果有语法错误会直接报出来。另一个常见问题是 matcher 大小写Bash和bash在 Claude Code 里是区分大小写的。还有脚本路径用了~但执行环境不展开建议写成绝对路径。脚本执行权限Linux 和 macOS 下脚本需要执行权限用chmod x赋权。如果脚本里调用了jq但系统没装会静默失败。用which jq确认没装的话先安装。Windows 用户建议用 WSL 或 Git Bash 执行原生 PowerShell 对 bash 脚本支持有限。排查顺序建议先确认 API 通道通curl 测试再确认 settings.json 格式合法最后确认脚本能独立执行。三步都过了Hooks 基本不会出问题。6. 把 Hooks 当基础设施从最疼的场景开始逐步扩展Hooks 的价值不在于数量而在于覆盖你最高频的痛点。你不需要一次装二十七个从 SessionStart 开始解决“每次都要重新交代”的问题然后加 PreToolUse解决“担心危险命令”的问题最后加 PostToolUse解决“格式问题卡 CI”的问题。这三个落地后你会发现 Claude Code 从“需要盯着用的工具”变成了“可以放心托付的基础设施”。如果你还想进一步扩展Stop hook 可以在 Claude 认为任务完成时自动跑测试不通过就返回 block 让它继续改。配置方式和 PostToolUse 类似只是事件名换成Stop脚本里跑npm test或mvn test失败时返回{decision: block, reason: 测试未通过}。这个 hook 适合对质量要求高的项目但要注意测试执行时间太慢会拖长会话。另一个实用扩展是审计日志。在 PreToolUse 的 allow 分支里追加一行写入日志文件记录每条执行的命令和时间戳。这样你随时可以回溯 Claude 干过什么出问题时能快速定位。日志文件建议放在项目外的目录避免被 Claude 自己读到。最后提醒一点Hooks 脚本本身也是代码需要维护。建议把脚本放在版本控制里团队共享项目级配置。脚本里避免硬编码路径和密钥用环境变量传递。定期检查脚本是否还符合当前工作流过时的 hook 及时删掉避免增加不必要的延迟。如果你还没配好 TaoToken 的 API 通道先回到第二节完成配置。通道通了Hooks 才有意义。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 需要长期编码额度可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。模型对话测试在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。