1. 為什么你的 Claude Code 需要 Hooks從“每次都要重新交代”到“自動(dòng)補(bǔ)課”Claude Code 能讀代碼、能改文件、能跑命令但默認(rèn)狀態(tài)下它更像一個(gè)“每天失憶的實(shí)習(xí)生”每次新開一個(gè)會(huì)話它不知道你當(dāng)前在哪個(gè)分支、昨天改了什么、項(xiàng)目里有哪些約定。你不得不手動(dòng)敲三行背景信息它再回三句確認(rèn)兩分鐘就這么沒(méi)了。Hooks 就是解決這個(gè)問(wèn)題的機(jī)制——它允許你在 Claude Code 生命周期的特定節(jié)點(diǎn)自動(dòng)執(zhí)行腳本把“重復(fù)交代”和“事后補(bǔ)救”變成基礎(chǔ)設(shè)施。我先把概念壓縮成一句話Hook 是在 Claude Code 執(zhí)行動(dòng)作的前后自動(dòng)跑一段你寫好的腳本。它不改變模型本身的能力而是給模型套上一層可編程的護(hù)欄和自動(dòng)化管道。Claude Code 目前支持二十多種 hook 事件覆蓋會(huì)話啟動(dòng)、工具調(diào)用前、工具調(diào)用后、會(huì)話結(jié)束等關(guān)鍵節(jié)點(diǎn)。你不需要全部用上挑最疼的三個(gè)場(chǎng)景落地就能看到明顯收益。這篇文章聚焦三類最實(shí)用的 HooksSessionStart、PreToolUse、PostToolUse。我會(huì)在 TaoToken 統(tǒng)一 Key 和 API 通道的前提下給出可復(fù)制的 settings 配置片段并逐條演示驗(yàn)證動(dòng)作。目標(biāo)很明確你照著做就能復(fù)現(xiàn)“提交前自動(dòng)檢查、上下文自動(dòng)注入、結(jié)果自動(dòng)校驗(yàn)”的效果。先說(shuō)清楚適合誰(shuí)如果你已經(jīng)在用 Claude Code 寫代碼但每次都要手動(dòng)補(bǔ)上下文、擔(dān)心它執(zhí)行危險(xiǎn)命令、或者被格式問(wèn)題卡 CI那這篇就是給你寫的。如果你還沒(méi)配好 Claude Code 的 API 通道第二節(jié)會(huì)先解決這個(gè)問(wèn)題因?yàn)?Hooks 的腳本執(zhí)行依賴 Claude Code 能正常發(fā)起請(qǐng)求。我試過(guò)把 Hooks 當(dāng)成“水泥”來(lái)理解模型是磚Hooks 是把磚砌成墻的粘合劑。沒(méi)有它磚還是磚但墻不牢。下面從環(huán)境準(zhǔn)備開始一步步把這三類 Hooks 裝進(jìn)你的工作流。2. TaoToken 前置統(tǒng)一 Key 與 API 通道配置讓 Claude Code 穩(wěn)定發(fā)起請(qǐng)求在寫 Hooks 之前必須先保證 Claude Code 能正常調(diào)用模型。Hooks 的腳本本身是本地執(zhí)行的但 Claude Code 的會(huì)話啟動(dòng)、工具調(diào)用決策都依賴模型返回所以 API 通道的穩(wěn)定性直接決定 Hooks 能不能按預(yù)期觸發(fā)。這里用 TaoToken 做統(tǒng)一 Key 管理好處是一個(gè) Key 覆蓋多個(gè)模型入口切換模型不用改環(huán)境變量。TaoToken 的定位是 API 通道服務(wù)官網(wǎng)地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不帶 UTM 參數(shù)配置時(shí)直接用這個(gè)基礎(chǔ)地址。第一步拿到 Key。進(jìn)入控制臺(tái)創(chuàng)建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。創(chuàng)建后復(fù)制 Key后面配置里會(huì)用到。如果你需要看模型列表和對(duì)話測(cè)試可以用模型對(duì)話頁(yè)面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。第二步配置 Claude Code 的 API 通道。Claude Code 讀取環(huán)境變量來(lái)定位 API 端點(diǎn)。在 shell 配置文件里加入以下內(nèi)容路徑按你的實(shí)際環(huán)境調(diào)整# ~/.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內(nèi)容結(jié)構(gòu)如下{ base_url: https://taotoken.net/api, api_key: 你的_TaoToken_Key, model: claude-sonnet-4-20250514 }Cline MCP 場(chǎng)景下配置寫在 MCP 的 settings 里核心三件套是 Base URL、Key、Model ID{ mcpServers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_Key, model: claude-sonnet-4-20250514 } } }CC Switch 用戶可以在切換配置里填入同樣的三件套。無(wú)論哪種工具Base URL 統(tǒng)一用https://taotoken.net/apiKey 用控制臺(tái)生成的Model ID 按你實(shí)際使用的模型填寫。第三步驗(yàn)證通道是否通。在終端執(zhí)行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說(shuō)明通道正常。如果返回 401檢查 Key 是否復(fù)制完整如果返回連接錯(cuò)誤檢查 Base URL 是否寫成了帶路徑的完整地址。這一步過(guò)了再往下配 Hooks否則 Hooks 腳本寫得再好也不會(huì)觸發(fā)。關(guān)于長(zhǎng)期編碼和 Agent 場(chǎng)景如果你打算把 Claude Code 作為日常主力可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它適合需要穩(wěn)定額度和多模型切換的開發(fā)者。接入文檔在 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. 可復(fù)制配置SessionStart、PreToolUse、PostToolUse 三類 Hooks 的 settings 片段Claude Code 的 Hooks 配置寫在 settings 文件里通常位于~/.claude/settings.json或項(xiàng)目級(jí)的.claude/settings.json。項(xiàng)目級(jí)配置只對(duì)當(dāng)前項(xiàng)目生效適合團(tuán)隊(duì)共享用戶級(jí)配置對(duì)所有項(xiàng)目生效適合個(gè)人習(xí)慣。下面給出三類 Hooks 的完整配置片段你可以直接復(fù)制后按需修改腳本路徑。先看 SessionStart。它的作用是在 Claude Code 會(huì)話啟動(dòng)時(shí)自動(dòng)注入上下文。配置結(jié)構(gòu)如下{ hooks: { SessionStart: [ { hooks: [ { type: command, command: bash ~/.claude/hooks/session-start.sh } ] } ] } }對(duì)應(yīng)的腳本~/.claude/hooks/session-start.sh內(nèi)容#!/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這個(gè)腳本把當(dāng)前分支、最近五條提交、未提交改動(dòng)和 TODO 文件頭部一起塞給 Claude。會(huì)話一啟動(dòng)模型就知道你昨天干到哪了不用再手動(dòng)交代。再看 PreToolUse。它在 Claude 調(diào)用工具之前攔截可以放行、拒絕或詢問(wèn)。配置里用 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判斷命令是否危險(xiǎn)#!/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: 檢測(cè)到高危刪除命令已攔截。請(qǐng)縮小刪除范圍后重試。 } exit 0 fi if echo $COMMAND | grep -qE git\spush\s--force; then jq -n { permissionDecision: ask, reason: 檢測(cè)到強(qiáng)制推送請(qǐng)確認(rèn)目標(biāo)分支。 } exit 0 fi jq -n {permissionDecision: allow}注意腳本返回的 JSON 結(jié)構(gòu)permissionDecision可以是allow、deny、askreason會(huì)展示給模型和用戶。這個(gè)腳本同時(shí)充當(dāng)審計(jì)日志的起點(diǎn)——你可以在 allow 分支里追加一行寫入日志文件。最后看 PostToolUse。它在工具調(diào)用完成后執(zhí)行適合做格式化和結(jié)果校驗(yàn)。配置里同樣用 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根據(jù)文件后綴調(diào)用不同格式化工具#!/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這三個(gè)配置可以合并到同一個(gè) settings.json 里結(jié)構(gòu)是hooks對(duì)象下并列三個(gè)鍵。合并后的完整片段{ 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配置生效。如果你用的是項(xiàng)目級(jí)配置把 settings.json 放在項(xiàng)目根目錄的.claude/下團(tuán)隊(duì)其他人拉取后自動(dòng)生效。注意腳本文件要有執(zhí)行權(quán)限用chmod x ~/.claude/hooks/*.sh賦權(quán)。4. 驗(yàn)證請(qǐng)求與成功結(jié)果逐條確認(rèn) Hooks 是否按預(yù)期觸發(fā)配置寫完不代表生效必須逐條驗(yàn)證。我按 SessionStart、PreToolUse、PostToolUse 的順序給出驗(yàn)證動(dòng)作和預(yù)期結(jié)果。驗(yàn)證 SessionStart新開一個(gè) Claude Code 會(huì)話觀察啟動(dòng)后模型的第一條回復(fù)。如果配置生效模型應(yīng)該已經(jīng)知道當(dāng)前分支和最近提交你可以直接問(wèn)“我現(xiàn)在在哪個(gè)分支”它不需要你補(bǔ)充信息就能回答。更直接的驗(yàn)證方式是看終端輸出——SessionStart 腳本的 echo 內(nèi)容會(huì)出現(xiàn)在會(huì)話初始化日志里。如果沒(méi)看到檢查腳本路徑是否正確、是否有執(zhí)行權(quán)限。驗(yàn)證 PreToolUse在 Claude Code 里讓它執(zhí)行一條危險(xiǎn)命令比如“幫我清理臨時(shí)文件執(zhí)行 rm -rf ./”。如果攔截生效Claude 會(huì)收到 deny 決策回復(fù)類似“該命令被安全策略攔截請(qǐng)縮小刪除范圍”。你可以進(jìn)一步測(cè)試 ask 分支讓它執(zhí)行g(shù)it push --force應(yīng)該彈出確認(rèn)提示而不是直接執(zhí)行。如果命令直接執(zhí)行了說(shuō)明 matcher 沒(méi)匹配上檢查 matcher 是否寫成了Bash而不是bash。驗(yàn)證 PostToolUse讓 Claude 寫一個(gè)格式混亂的 TypeScript 文件比如故意多寫空格和縮進(jìn)。寫入完成后PostToolUse 腳本會(huì)自動(dòng)調(diào)用 prettier 格式化。驗(yàn)證方式是寫入后立刻用cat查看文件內(nèi)容如果格式已經(jīng)規(guī)整說(shuō)明生效。你也可以在腳本里臨時(shí)加一行echo formatted: $FILE_PATH /tmp/hook.log然后查看日志確認(rèn)觸發(fā)。除了逐條驗(yàn)證還要確認(rèn) Hooks 不會(huì)阻塞正常流程。SessionStart 腳本如果執(zhí)行太慢會(huì)拖慢會(huì)話啟動(dòng)PreToolUse 腳本如果對(duì)每條命令都做復(fù)雜判斷會(huì)增加延遲。建議腳本里避免網(wǎng)絡(luò)請(qǐng)求和重計(jì)算只做本地快速判斷。PostToolUse 的格式化工具如果沒(méi)安裝腳本里的2/dev/null會(huì)吞掉錯(cuò)誤但格式化不會(huì)執(zhí)行——所以提前確認(rèn) prettier、black、gofmt 在 PATH 里可用。一個(gè)完整的成功結(jié)果應(yīng)該是新會(huì)話啟動(dòng)后模型自動(dòng)知道分支和提交危險(xiǎn)命令被攔截并給出原因?qū)懭氲奈募詣?dòng)格式化。三者同時(shí)生效說(shuō)明三類 Hooks 都配置正確。如果只有部分生效按上面的排查點(diǎn)逐個(gè)檢查。5. 本篇常見錯(cuò)排查401、local proxy failed、reading choices、OAuth 報(bào)錯(cuò)對(duì)照Hooks 配置過(guò)程中最容易遇到的不是腳本邏輯問(wèn)題而是 API 通道和配置格式問(wèn)題。下面按真實(shí)報(bào)錯(cuò)逐條排查。401 Unauthorized這是最常見的錯(cuò)誤說(shuō)明 Key 無(wú)效或沒(méi)傳對(duì)。檢查三處環(huán)境變量ANTHROPIC_API_KEY是否設(shè)置settings.json 里是否有覆蓋Key 是否復(fù)制完整注意前后空格。如果你用的是 Codex 的 auth.json檢查api_key字段名是否正確。TaoToken 的 Key 在控制臺(tái)生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。重新生成一個(gè) Key 替換后重試。local proxy failed這個(gè)報(bào)錯(cuò)通常出現(xiàn)在 Base URL 配置錯(cuò)誤時(shí)。檢查ANTHROPIC_BASE_URL是否寫成了https://taotoken.net/api不要多加/v1或結(jié)尾斜杠。如果你在 Cline MCP 里配置檢查baseUrl字段是否被其他配置覆蓋。另外確認(rèn)本地沒(méi)有殘留的代理環(huán)境變量比如HTTP_PROXY指向了不可用的地址。reading choices 報(bào)錯(cuò)這個(gè)錯(cuò)誤說(shuō)明請(qǐng)求發(fā)出去了但返回結(jié)構(gòu)不符合預(yù)期。常見原因是 Model ID 寫錯(cuò)。檢查ANTHROPIC_MODEL是否是你實(shí)際可用的模型比如claude-sonnet-4-20250514。如果你在 TaoToken 控制臺(tái)看到的模型名不同以控制臺(tái)為準(zhǔn)。另一個(gè)原因是請(qǐng)求體格式問(wèn)題比如 max_tokens 設(shè)成了字符串而不是數(shù)字。OAuth 相關(guān)報(bào)錯(cuò)如果你之前用 OAuth 方式登錄過(guò) Claude Code環(huán)境變量可能和 OAuth 憑證沖突。解決方式是清除 OAuth 緩存通常位于~/.claude/下的憑證文件然后重新用 API Key 方式配置。檢查~/.claude/settings.json里是否有oauth相關(guān)字段有的話刪掉。CC Switch 用戶注意切換配置時(shí)不要混用 OAuth 和 API Key。Hooks 不觸發(fā)如果 API 通道正常但 Hooks 沒(méi)反應(yīng)檢查 settings.json 的 JSON 格式是否合法。用jq . ~/.claude/settings.json驗(yàn)證如果有語(yǔ)法錯(cuò)誤會(huì)直接報(bào)出來(lái)。另一個(gè)常見問(wèn)題是 matcher 大小寫B(tài)ash和bash在 Claude Code 里是區(qū)分大小寫的。還有腳本路徑用了~但執(zhí)行環(huán)境不展開建議寫成絕對(duì)路徑。腳本執(zhí)行權(quán)限Linux 和 macOS 下腳本需要執(zhí)行權(quán)限用chmod x賦權(quán)。如果腳本里調(diào)用了jq但系統(tǒng)沒(méi)裝會(huì)靜默失敗。用which jq確認(rèn)沒(méi)裝的話先安裝。Windows 用戶建議用 WSL 或 Git Bash 執(zhí)行原生 PowerShell 對(duì) bash 腳本支持有限。排查順序建議先確認(rèn) API 通道通curl 測(cè)試再確認(rèn) settings.json 格式合法最后確認(rèn)腳本能獨(dú)立執(zhí)行。三步都過(guò)了Hooks 基本不會(huì)出問(wèn)題。6. 把 Hooks 當(dāng)基礎(chǔ)設(shè)施從最疼的場(chǎng)景開始逐步擴(kuò)展Hooks 的價(jià)值不在于數(shù)量而在于覆蓋你最高頻的痛點(diǎn)。你不需要一次裝二十七個(gè)從 SessionStart 開始解決“每次都要重新交代”的問(wèn)題然后加 PreToolUse解決“擔(dān)心危險(xiǎn)命令”的問(wèn)題最后加 PostToolUse解決“格式問(wèn)題卡 CI”的問(wèn)題。這三個(gè)落地后你會(huì)發(fā)現(xiàn) Claude Code 從“需要盯著用的工具”變成了“可以放心托付的基礎(chǔ)設(shè)施”。如果你還想進(jìn)一步擴(kuò)展Stop hook 可以在 Claude 認(rèn)為任務(wù)完成時(shí)自動(dòng)跑測(cè)試不通過(guò)就返回 block 讓它繼續(xù)改。配置方式和 PostToolUse 類似只是事件名換成Stop腳本里跑npm test或mvn test失敗時(shí)返回{decision: block, reason: 測(cè)試未通過(guò)}。這個(gè) hook 適合對(duì)質(zhì)量要求高的項(xiàng)目但要注意測(cè)試執(zhí)行時(shí)間太慢會(huì)拖長(zhǎng)會(huì)話。另一個(gè)實(shí)用擴(kuò)展是審計(jì)日志。在 PreToolUse 的 allow 分支里追加一行寫入日志文件記錄每條執(zhí)行的命令和時(shí)間戳。這樣你隨時(shí)可以回溯 Claude 干過(guò)什么出問(wèn)題時(shí)能快速定位。日志文件建議放在項(xiàng)目外的目錄避免被 Claude 自己讀到。最后提醒一點(diǎn)Hooks 腳本本身也是代碼需要維護(hù)。建議把腳本放在版本控制里團(tuán)隊(duì)共享項(xiàng)目級(jí)配置。腳本里避免硬編碼路徑和密鑰用環(huán)境變量傳遞。定期檢查腳本是否還符合當(dāng)前工作流過(guò)時(shí)的 hook 及時(shí)刪掉避免增加不必要的延遲。如果你還沒(méi)配好 TaoToken 的 API 通道先回到第二節(jié)完成配置。通道通了Hooks 才有意義。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 需要長(zhǎng)期編碼額度可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。模型對(duì)話測(cè)試在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。