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