完整指南：用TaoToken統(tǒng)一Key打通Claude Code自動化工作流)
1. 為什么你的 Claude Code 自動化總在“最后一公里”掉鏈子很多人把 Claude Code 當成一個更聰明的代碼補全工具寫幾行提示詞讓它幫忙改改 bug、生成個函數用完就關。但真正讓團隊效率拉開差距的不是單次對話有多驚艷而是自動化工作流能不能穩(wěn)定跑起來。我見過太多項目提示詞里反復強調“每次改完代碼記得跑格式化”“提交前必須過 lint”結果 Claude 該忘還是忘該跳過還是跳過。這不是模型不聽話而是你用錯了機制——靠“記憶”驅動的約束天然就是概率性的。Hooks 系統(tǒng)就是來解決這個確定性問題的。它把“希望 AI 做的事”變成“事件觸發(fā)時必然執(zhí)行的腳本”。Claude Code 在工具調用前后、會話開始結束、任務創(chuàng)建完成等節(jié)點會拋出結構化事件你只要掛上自己的命令就能實現 100% 可靠的攔截、校驗、格式化和通知。而要把這套鏈路真正跑通繞不開一個現實問題API 通道的統(tǒng)一管理。本地開發(fā)、CI 流水線、多人協(xié)作如果每個環(huán)境都散落著不同的 Key 和 Base URLHooks 腳本里再硬編碼一堆敏感信息自動化越強風險越大。這篇指南聚焦 PreToolUse 和 PostToolUse 兩個最高頻的 Hook 事件從事件觸發(fā)到命令編排給出可直接復制的settings.json配置、Hook 腳本模板以及用 TaoToken 統(tǒng)一 Key/API 通道接入的完整驗證步驟。適合已經裝好 Claude Code、想把手動操作升級成可觀測、可回滾自動化鏈路的開發(fā)者。你不需要是 Shell 高手但得愿意動手改配置文件。我試過在三個不同項目里用同一套 Hook 模板最大的體會是配置的清晰度決定了排障的速度。下面從最核心的事件模型講起每一步都配上可運行的代碼和驗證方法。2. TaoToken 統(tǒng)一 Key 接入讓 Hooks 腳本不再散落敏感信息在寫第一個 Hook 之前先把 API 通道這件事理清楚。Claude Code 本身需要調用模型服務而你的 Hook 腳本里往往還要發(fā)通知、寫日志、調外部接口。如果每個腳本都從環(huán)境變量里讀不同的 Key或者更糟——直接硬編碼在.claude/hooks/目錄下那這套自動化鏈路就是個定時炸彈。團隊里任何人 clone 項目都可能因為缺 Key 跑不起來一旦 Key 泄露排查范圍又大得嚇人。TaoToken 在這里扮演的角色是統(tǒng)一的 API 通道和 Key 管理入口。你可以在控制臺創(chuàng)建項目級的 Key把模型對話、Coding Plan、API 調用都收斂到同一個 Base URL 下。對 Hooks 腳本來說這意味著你只需要維護一份環(huán)境變量所有腳本通過TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL來訪問不用關心底層是哪個模型供應商。具體操作上先到 TaoToken 控制臺創(chuàng)建一個 API Key。地址是https://taotoken.net/api-keys登錄后點“創(chuàng)建密鑰”給它起個能識別的名字比如claude-code-hooks-dev。創(chuàng)建完立刻復制頁面刷新后就看不到了。這個 Key 就是你后續(xù)所有配置里要用的憑證。拿到 Key 之后在項目根目錄創(chuàng)建.env文件記得加進.gitignore寫入兩行TAOTOKEN_API_KEYsk-你的實際密鑰 TAOTOKEN_BASE_URLhttps://taotoken.net/api注意 Base URL 這里不帶任何路徑后綴就是https://taotoken.net/api。有些教程會讓你加/v1或者/anthropic那是舊版寫法現在統(tǒng)一用這個根地址具體端點由 Claude Code 或你的腳本自己拼接。接下來配置 Claude Code 本身走 TaoToken 通道。在.claude/settings.json里加上env字段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的實際密鑰 } }這里有個細節(jié)Claude Code 讀的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY這兩個環(huán)境變量名不是TAOTOKEN_前綴。所以你在.env里定義自己的變量給 Hook 腳本用在settings.json里用 Anthropic 的標準變量名給 Claude Code 用兩者互不沖突。如果你用的是 Claude Code 的 Coding Plan 模式或者想統(tǒng)一管理多個項目的配額建議在 TaoToken 控制臺里給不同項目創(chuàng)建不同的 Key然后通過環(huán)境變量注入。這樣在 CI 里只需要替換一個 Secret所有 Hook 腳本自動生效。驗證通道是否打通最直接的方法是發(fā)一個最小請求。在終端里執(zhí)行curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的實際密鑰 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回復 OK 兩個字母}] }如果返回的 JSON 里content字段有內容說明 Key 和 Base URL 都正確。如果返回 401檢查 Key 是否復制完整、有沒有多余空格。如果返回 404檢查 Base URL 是不是寫成了https://taotoken.net/api/v1這種帶后綴的形式——根地址就是https://taotoken.net/api。這一步做完你的 Hooks 腳本就有了統(tǒng)一的憑證來源。后面所有腳本都從TAOTOKEN_API_KEY讀 Key從TAOTOKEN_BASE_URL拼請求地址不再出現“這個腳本用 OpenAI Key、那個腳本用 Anthropic Key”的混亂局面。3. 可復制配置PreToolUse 與 PostToolUse 的 settings.json 與腳本模板現在進入核心配置環(huán)節(jié)。Claude Code 的 Hooks 配置寫在.claude/settings.json里結構是hooks對象下面按事件名分組每個事件是一個數組數組里每個元素包含matcher和hooks列表。matcher決定這個 Hook 對哪些工具生效hooks列表里每個條目定義要執(zhí)行的命令、超時時間和類型。先給一個完整的settings.json模板包含 PreToolUse 和 PostToolUse 兩個事件你可以直接復制到項目里改{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的實際密鑰 }, hooks: { PreToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: python .claude/hooks/pre-protect.py, timeout: 10 } ] }, { matcher: Bash, hooks: [ { type: command, command: python .claude/hooks/pre-bash-guard.py, timeout: 10 } ] } ], PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: python .claude/hooks/post-format.py, timeout: 30 } ] } ] } }這個配置做了三件事寫文件前檢查是否碰了保護目錄執(zhí)行 Bash 前攔截危險命令寫文件后自動格式化。下面逐個給出腳本模板。PreToolUse 腳本模板保護 production 目錄創(chuàng)建.claude/hooks/pre-protect.py#!/usr/bin/env python3 import sys import json import os def main(): try: data json.loads(sys.stdin.read()) except json.JSONDecodeError: sys.exit(0) tool_name data.get(tool_name, ) tool_input data.get(tool_input, {}) file_path tool_input.get(file_path, ) if tool_name not in (Write, Edit): sys.exit(0) normalized file_path.replace(\\, /) protected [production/, prod/, .env, secrets/] for p in protected: if p in normalized: decision { hookSpecificOutput: { permissionDecision: deny }, message: f禁止修改受保護路徑: {file_path} (匹配規(guī)則: {p}) } print(json.dumps(decision, ensure_asciiFalse)) sys.exit(0) sys.exit(0) if __name__ __main__: main()這個腳本從 stdin 讀 JSON檢查tool_input.file_path是否包含保護目錄。如果命中輸出permissionDecision: denyClaude Code 會拒絕這次工具調用并把message反饋給模型。注意新版 API 用的是hookSpecificOutput.permissionDecision不是舊的decision字段兩者不要混用。PreToolUse 腳本模板Bash 危險命令攔截創(chuàng)建.claude/hooks/pre-bash-guard.py#!/usr/bin/env python3 import sys import json import re DANGEROUS [ rrm\s-rf\s/, rrm\s-rf\s~, rrm\s-rf\s\*, rmkfs\., rdd\sif.*of/dev/, r:\(\)\s*\{\s*:\|:\s*\};:, ] def main(): try: data json.loads(sys.stdin.read()) except json.JSONDecodeError: sys.exit(0) if data.get(tool_name) ! Bash: sys.exit(0) command data.get(tool_input, {}).get(command, ) for pattern in DANGEROUS: if re.search(pattern, command, re.IGNORECASE): decision { hookSpecificOutput: { permissionDecision: deny }, message: f危險命令已攔截: {command} } print(json.dumps(decision, ensure_asciiFalse)) sys.exit(0) sys.exit(0) if __name__ __main__: main()這個腳本只處理Bash工具用正則匹配常見危險模式。你可以按團隊規(guī)范往DANGEROUS列表里加規(guī)則比如禁止git push --force到主分支。PostToolUse 腳本模板自動格式化與日志創(chuàng)建.claude/hooks/post-format.py#!/usr/bin/env python3 import sys import json import subprocess import os from pathlib import Path from datetime import datetime def log(msg): log_dir Path.home() / .claude / hooks log_dir.mkdir(parentsTrue, exist_okTrue) log_file log_dir / post-format.log ts datetime.now().strftime(%Y-%m-%d %H:%M:%S) with open(log_file, a, encodingutf-8) as f: f.write(f[{ts}] {msg}\n) def main(): try: data json.loads(sys.stdin.read()) except json.JSONDecodeError: sys.exit(0) tool_name data.get(tool_name, ) file_path data.get(tool_input, {}).get(file_path, ) if tool_name not in (Write, Edit) or not file_path: sys.exit(0) if not os.path.exists(file_path): log(f文件不存在跳過: {file_path}) sys.exit(0) ext Path(file_path).suffix.lower() try: if ext in (.py,): subprocess.run( [python, -m, black, file_path], capture_outputTrue, timeout20 ) log(fblack 格式化完成: {file_path}) elif ext in (.js, .ts, .json, .md): subprocess.run( [npx, prettier, --write, file_path], capture_outputTrue, timeout20 ) log(fprettier 格式化完成: {file_path}) except subprocess.TimeoutExpired: log(f格式化超時: {file_path}) except FileNotFoundError: log(f格式化工具未安裝跳過: {file_path}) sys.exit(0) if __name__ __main__: main()這個腳本在文件寫入后根據擴展名調用對應格式化工具所有執(zhí)行結果寫到~/.claude/hooks/post-format.log。PostToolUse 的 stdout 不會直接顯示給用戶所以調試信息必須寫日志文件。配置和腳本都就位后記得給腳本加執(zhí)行權限chmod x .claude/hooks/*.py如果你在 CI 環(huán)境里跑把.claude/settings.json和.claude/hooks/一起提交到倉庫Key 通過 CI Secret 注入ANTHROPIC_API_KEY環(huán)境變量。這樣本地和 CI 用的是同一套 Hook 邏輯行為完全一致。4. 驗證請求與成功結果從日志回顯到鏈路核對配置寫完不代表生效必須驗證。驗證分三層腳本本身能跑、Hook 被觸發(fā)、API 通道正常。第一層手動喂數據測試腳本不用啟動 Claude Code直接給腳本喂 JSON看輸出是否符合預期。測試保護腳本echo {tool_name:Write,tool_input:{file_path:production/config.py}} | python .claude/hooks/pre-protect.py預期輸出是一段 JSON包含permissionDecision: deny和提示信息。如果沒有任何輸出說明腳本沒匹配到保護規(guī)則檢查protected列表里的字符串是否和路徑匹配。測試 Bash 攔截echo {tool_name:Bash,tool_input:{command:rm -rf /tmp/test}} | python .claude/hooks/pre-bash-guard.py預期輸出deny決策。換成echo hello應該無輸出表示放行。第二層在 Claude Code 里觸發(fā)真實 Hook啟動 Claude Code輸入一個會觸發(fā) Write 的指令比如“創(chuàng)建一個 test.txt 文件”。如果 PreToolUse 保護腳本配置正確寫普通文件應該正常通過然后手動讓它寫production/test.txt應該被拒絕并看到提示信息。PostToolUse 的驗證看日志文件tail -f ~/.claude/hooks/post-format.log讓 Claude 創(chuàng)建一個.py文件日志里應該出現black 格式化完成的記錄。如果日志文件根本沒生成說明 Hook 沒被觸發(fā)檢查settings.json的 JSON 格式是否正確python -c import json; json.load(open(.claude/settings.json)); print(JSON OK)第三層核對 API 通道回顯Hooks 腳本里如果調用了 TaoToken 的 API需要確認請求真的到達了正確端點。在腳本里加一行調試日志記錄實際請求的 URL 和響應狀態(tài)?；蛘哂胏url單獨驗證curl -s -o /dev/null -w %{http_code} \ -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:16,messages:[{role:user,content:hi}]}返回200說明通道正常。返回401檢查 Key返回404檢查 Base URL 是否多了/v1后綴。一個完整的成功鏈路應該是Claude Code 發(fā)起工具調用 → PreToolUse 腳本攔截并放行 → 工具執(zhí)行 → PostToolUse 腳本格式化并寫日志 → 日志文件出現對應記錄 → 如果腳本內調用了 TaoToken API請求返回 200。任何一環(huán)斷了按這個順序倒查。5. 常見報錯排查401、local proxy failed、reading choices 與 OAuth即使配置看起來沒問題實際跑起來還是會遇到各種報錯。下面按真實錯誤信息逐個拆解。報錯一401 Unauthorized這是最常見的。Claude Code 啟動后任何請求都返回 401說明ANTHROPIC_API_KEY無效或沒被讀到。排查順序先確認.claude/settings.json里env.ANTHROPIC_API_KEY的值沒有多余空格和換行再確認系統(tǒng)環(huán)境變量里沒有另一個沖突的ANTHROPIC_API_KEY覆蓋了配置最后用curl單獨測試 Key 是否有效。如果 Key 是從 TaoToken 控制臺復制的注意不要復制到前后空白字符。報錯二local proxy failed / connection refused這個錯誤通常出現在 Hook 腳本里調用了本地代理或錯誤的 Base URL。檢查腳本里拼接的 URL 是不是https://taotoken.net/api開頭有沒有誤寫成http://localhost:xxxx。如果你之前配置過其他代理工具確保環(huán)境變量HTTP_PROXY、HTTPS_PROXY沒有指向已關閉的本地端口。在 CI 環(huán)境里這個錯誤多半是因為 Secret 沒注入腳本讀到了空字符串然后拼出了一個無效地址。報錯三reading choices 相關錯誤這個報錯說明請求體格式和端點不匹配。常見原因是把 OpenAI 格式的請求發(fā)到了 Anthropic 端點或者反過來。Claude Code 走的是 Anthropic Messages API 格式請求體里應該是messages數組加model、max_tokens響應里是content數組。如果你在 Hook 腳本里自己構造請求確認content-type是application/jsonanthropic-version頭存在。TaoToken 的/api/v1/messages端點兼容 Anthropic 格式不要混用 OpenAI 的chat/completions路徑。報錯四OAuth 相關提示Claude Code 某些版本會嘗試 OAuth 流程如果你用的是 API Key 模式需要在配置里明確禁用 OAuth。檢查settings.json里有沒有forceLoginMethod之類的字段被設成了oauth。另外如果之前登錄過其他賬號~/.claude/目錄下可能殘留了舊的憑證文件刪掉~/.claude/auth.json或類似文件后重啟。報錯五Hook 執(zhí)行成功但沒效果PostToolUse 腳本跑了但格式化沒生效先看日志文件有沒有寫入。如果日志有記錄但文件沒變檢查格式化命令的路徑參數是不是相對路徑——Hook 執(zhí)行時的工作目錄可能不是項目根目錄。在腳本里用os.path.abspath(file_path)轉成絕對路徑再傳給格式化工具。PreToolUse 的deny沒生效檢查輸出 JSON 的字段名是不是hookSpecificOutput.permissionDecision舊版的decision字段在新版本里可能被忽略。報錯六timeout 頻繁觸發(fā)Hook 腳本超時被 kill日志里出現TimeoutExpired。把settings.json里的timeout值調大比如從 10 調到 30。如果腳本里有網絡請求給請求本身也設一個合理的超時避免整個腳本卡死。CI 環(huán)境里網絡延遲高timeout 建議設到 60。排查時記住一個原則先隔離再定位。把 Hook 腳本單獨拿出來用echo喂數據跑一遍能排除掉 Claude Code 配置層的干擾。確認腳本本身沒問題后再檢查settings.json的 JSON 結構和事件名拼寫。事件名是大小寫敏感的PreToolUse不能寫成preToolUse。6. 把自動化鏈路跑成可回滾的日常習慣配置 Hooks 最怕的不是寫錯而是寫完之后沒人知道它存在。團隊里新來的同學改了一個文件發(fā)現被莫名其妙拒絕了翻半天代碼才找到.claude/hooks/pre-protect.py里的規(guī)則。所以我在項目里養(yǎng)成了一個習慣所有 Hook 腳本頭部都寫清楚用途、觸發(fā)條件和維護人settings.json里的每個 Hook 條目旁邊用注釋說明JSON 不支持注釋就寫在 README 里?；貪L也很簡單。Hooks 的配置和腳本都在.claude/目錄下用 Git 管理起來任何改動都能追溯。如果某個 Hook 導致問題臨時把settings.json里對應的條目刪掉或者把matcher改成不匹配的值重啟 Claude Code 就恢復了。不需要卸載任何東西。API 通道這邊TaoToken 的 Key 可以在控制臺隨時禁用和重建。如果懷疑某個 Key 泄露直接禁用再創(chuàng)建一個新的更新環(huán)境變量即可所有 Hook 腳本自動用上新 Key。這種集中管理的方式比在每個腳本里改硬編碼的 Key 要省心得多。最后給一個實用建議從 PostToolUse 的日志 Hook 開始。它不會攔截任何操作只是默默記錄風險最低但能讓你清楚看到 Claude Code 到底在什么時候調用了什么工具。跑上一周你自然就知道哪些環(huán)節(jié)值得加 PreToolUse 攔截哪些文件需要保護。自動化不是一次配完就結束而是根據實際日志逐步收緊的過程。 Hooks系統(tǒng)完整指南：用TaoToken統(tǒng)一Key打通Claude Code自動化工作流
1. 為什么你的 Claude Code 自動化總在“最后一公里”掉鏈子很多人把 Claude Code 當成一個更聰明的代碼補全工具寫幾行提示詞讓它幫忙改改 bug、生成個函數用完就關。但真正讓團隊效率拉開差距的不是單次對話有多驚艷而是自動化工作流能不能穩(wěn)定跑起來。我見過太多項目提示詞里反復強調“每次改完代碼記得跑格式化”“提交前必須過 lint”結果 Claude 該忘還是忘該跳過還是跳過。這不是模型不聽話而是你用錯了機制——靠“記憶”驅動的約束天然就是概率性的。Hooks 系統(tǒng)就是來解決這個確定性問題的。它把“希望 AI 做的事”變成“事件觸發(fā)時必然執(zhí)行的腳本”。Claude Code 在工具調用前后、會話開始結束、任務創(chuàng)建完成等節(jié)點會拋出結構化事件你只要掛上自己的命令就能實現 100% 可靠的攔截、校驗、格式化和通知。而要把這套鏈路真正跑通繞不開一個現實問題API 通道的統(tǒng)一管理。本地開發(fā)、CI 流水線、多人協(xié)作如果每個環(huán)境都散落著不同的 Key 和 Base URLHooks 腳本里再硬編碼一堆敏感信息自動化越強風險越大。這篇指南聚焦 PreToolUse 和 PostToolUse 兩個最高頻的 Hook 事件從事件觸發(fā)到命令編排給出可直接復制的settings.json配置、Hook 腳本模板以及用 TaoToken 統(tǒng)一 Key/API 通道接入的完整驗證步驟。適合已經裝好 Claude Code、想把手動操作升級成可觀測、可回滾自動化鏈路的開發(fā)者。你不需要是 Shell 高手但得愿意動手改配置文件。我試過在三個不同項目里用同一套 Hook 模板最大的體會是配置的清晰度決定了排障的速度。下面從最核心的事件模型講起每一步都配上可運行的代碼和驗證方法。2. TaoToken 統(tǒng)一 Key 接入讓 Hooks 腳本不再散落敏感信息在寫第一個 Hook 之前先把 API 通道這件事理清楚。Claude Code 本身需要調用模型服務而你的 Hook 腳本里往往還要發(fā)通知、寫日志、調外部接口。如果每個腳本都從環(huán)境變量里讀不同的 Key或者更糟——直接硬編碼在.claude/hooks/目錄下那這套自動化鏈路就是個定時炸彈。團隊里任何人 clone 項目都可能因為缺 Key 跑不起來一旦 Key 泄露排查范圍又大得嚇人。TaoToken 在這里扮演的角色是統(tǒng)一的 API 通道和 Key 管理入口。你可以在控制臺創(chuàng)建項目級的 Key把模型對話、Coding Plan、API 調用都收斂到同一個 Base URL 下。對 Hooks 腳本來說這意味著你只需要維護一份環(huán)境變量所有腳本通過TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL來訪問不用關心底層是哪個模型供應商。具體操作上先到 TaoToken 控制臺創(chuàng)建一個 API Key。地址是https://taotoken.net/api-keys登錄后點“創(chuàng)建密鑰”給它起個能識別的名字比如claude-code-hooks-dev。創(chuàng)建完立刻復制頁面刷新后就看不到了。這個 Key 就是你后續(xù)所有配置里要用的憑證。拿到 Key 之后在項目根目錄創(chuàng)建.env文件記得加進.gitignore寫入兩行TAOTOKEN_API_KEYsk-你的實際密鑰 TAOTOKEN_BASE_URLhttps://taotoken.net/api注意 Base URL 這里不帶任何路徑后綴就是https://taotoken.net/api。有些教程會讓你加/v1或者/anthropic那是舊版寫法現在統(tǒng)一用這個根地址具體端點由 Claude Code 或你的腳本自己拼接。接下來配置 Claude Code 本身走 TaoToken 通道。在.claude/settings.json里加上env字段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的實際密鑰 } }這里有個細節(jié)Claude Code 讀的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY這兩個環(huán)境變量名不是TAOTOKEN_前綴。所以你在.env里定義自己的變量給 Hook 腳本用在settings.json里用 Anthropic 的標準變量名給 Claude Code 用兩者互不沖突。如果你用的是 Claude Code 的 Coding Plan 模式或者想統(tǒng)一管理多個項目的配額建議在 TaoToken 控制臺里給不同項目創(chuàng)建不同的 Key然后通過環(huán)境變量注入。這樣在 CI 里只需要替換一個 Secret所有 Hook 腳本自動生效。驗證通道是否打通最直接的方法是發(fā)一個最小請求。在終端里執(zhí)行curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的實際密鑰 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回復 OK 兩個字母}] }如果返回的 JSON 里content字段有內容說明 Key 和 Base URL 都正確。如果返回 401檢查 Key 是否復制完整、有沒有多余空格。如果返回 404檢查 Base URL 是不是寫成了https://taotoken.net/api/v1這種帶后綴的形式——根地址就是https://taotoken.net/api。這一步做完你的 Hooks 腳本就有了統(tǒng)一的憑證來源。后面所有腳本都從TAOTOKEN_API_KEY讀 Key從TAOTOKEN_BASE_URL拼請求地址不再出現“這個腳本用 OpenAI Key、那個腳本用 Anthropic Key”的混亂局面。3. 可復制配置PreToolUse 與 PostToolUse 的 settings.json 與腳本模板現在進入核心配置環(huán)節(jié)。Claude Code 的 Hooks 配置寫在.claude/settings.json里結構是hooks對象下面按事件名分組每個事件是一個數組數組里每個元素包含matcher和hooks列表。matcher決定這個 Hook 對哪些工具生效hooks列表里每個條目定義要執(zhí)行的命令、超時時間和類型。先給一個完整的settings.json模板包含 PreToolUse 和 PostToolUse 兩個事件你可以直接復制到項目里改{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的實際密鑰 }, hooks: { PreToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: python .claude/hooks/pre-protect.py, timeout: 10 } ] }, { matcher: Bash, hooks: [ { type: command, command: python .claude/hooks/pre-bash-guard.py, timeout: 10 } ] } ], PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: python .claude/hooks/post-format.py, timeout: 30 } ] } ] } }這個配置做了三件事寫文件前檢查是否碰了保護目錄執(zhí)行 Bash 前攔截危險命令寫文件后自動格式化。下面逐個給出腳本模板。PreToolUse 腳本模板保護 production 目錄創(chuàng)建.claude/hooks/pre-protect.py#!/usr/bin/env python3 import sys import json import os def main(): try: data json.loads(sys.stdin.read()) except json.JSONDecodeError: sys.exit(0) tool_name data.get(tool_name, ) tool_input data.get(tool_input, {}) file_path tool_input.get(file_path, ) if tool_name not in (Write, Edit): sys.exit(0) normalized file_path.replace(\\, /) protected [production/, prod/, .env, secrets/] for p in protected: if p in normalized: decision { hookSpecificOutput: { permissionDecision: deny }, message: f禁止修改受保護路徑: {file_path} (匹配規(guī)則: {p}) } print(json.dumps(decision, ensure_asciiFalse)) sys.exit(0) sys.exit(0) if __name__ __main__: main()這個腳本從 stdin 讀 JSON檢查tool_input.file_path是否包含保護目錄。如果命中輸出permissionDecision: denyClaude Code 會拒絕這次工具調用并把message反饋給模型。注意新版 API 用的是hookSpecificOutput.permissionDecision不是舊的decision字段兩者不要混用。PreToolUse 腳本模板Bash 危險命令攔截創(chuàng)建.claude/hooks/pre-bash-guard.py#!/usr/bin/env python3 import sys import json import re DANGEROUS [ rrm\s-rf\s/, rrm\s-rf\s~, rrm\s-rf\s\*, rmkfs\., rdd\sif.*of/dev/, r:\(\)\s*\{\s*:\|:\s*\};:, ] def main(): try: data json.loads(sys.stdin.read()) except json.JSONDecodeError: sys.exit(0) if data.get(tool_name) ! Bash: sys.exit(0) command data.get(tool_input, {}).get(command, ) for pattern in DANGEROUS: if re.search(pattern, command, re.IGNORECASE): decision { hookSpecificOutput: { permissionDecision: deny }, message: f危險命令已攔截: {command} } print(json.dumps(decision, ensure_asciiFalse)) sys.exit(0) sys.exit(0) if __name__ __main__: main()這個腳本只處理Bash工具用正則匹配常見危險模式。你可以按團隊規(guī)范往DANGEROUS列表里加規(guī)則比如禁止git push --force到主分支。PostToolUse 腳本模板自動格式化與日志創(chuàng)建.claude/hooks/post-format.py#!/usr/bin/env python3 import sys import json import subprocess import os from pathlib import Path from datetime import datetime def log(msg): log_dir Path.home() / .claude / hooks log_dir.mkdir(parentsTrue, exist_okTrue) log_file log_dir / post-format.log ts datetime.now().strftime(%Y-%m-%d %H:%M:%S) with open(log_file, a, encodingutf-8) as f: f.write(f[{ts}] {msg}\n) def main(): try: data json.loads(sys.stdin.read()) except json.JSONDecodeError: sys.exit(0) tool_name data.get(tool_name, ) file_path data.get(tool_input, {}).get(file_path, ) if tool_name not in (Write, Edit) or not file_path: sys.exit(0) if not os.path.exists(file_path): log(f文件不存在跳過: {file_path}) sys.exit(0) ext Path(file_path).suffix.lower() try: if ext in (.py,): subprocess.run( [python, -m, black, file_path], capture_outputTrue, timeout20 ) log(fblack 格式化完成: {file_path}) elif ext in (.js, .ts, .json, .md): subprocess.run( [npx, prettier, --write, file_path], capture_outputTrue, timeout20 ) log(fprettier 格式化完成: {file_path}) except subprocess.TimeoutExpired: log(f格式化超時: {file_path}) except FileNotFoundError: log(f格式化工具未安裝跳過: {file_path}) sys.exit(0) if __name__ __main__: main()這個腳本在文件寫入后根據擴展名調用對應格式化工具所有執(zhí)行結果寫到~/.claude/hooks/post-format.log。PostToolUse 的 stdout 不會直接顯示給用戶所以調試信息必須寫日志文件。配置和腳本都就位后記得給腳本加執(zhí)行權限chmod x .claude/hooks/*.py如果你在 CI 環(huán)境里跑把.claude/settings.json和.claude/hooks/一起提交到倉庫Key 通過 CI Secret 注入ANTHROPIC_API_KEY環(huán)境變量。這樣本地和 CI 用的是同一套 Hook 邏輯行為完全一致。4. 驗證請求與成功結果從日志回顯到鏈路核對配置寫完不代表生效必須驗證。驗證分三層腳本本身能跑、Hook 被觸發(fā)、API 通道正常。第一層手動喂數據測試腳本不用啟動 Claude Code直接給腳本喂 JSON看輸出是否符合預期。測試保護腳本echo {tool_name:Write,tool_input:{file_path:production/config.py}} | python .claude/hooks/pre-protect.py預期輸出是一段 JSON包含permissionDecision: deny和提示信息。如果沒有任何輸出說明腳本沒匹配到保護規(guī)則檢查protected列表里的字符串是否和路徑匹配。測試 Bash 攔截echo {tool_name:Bash,tool_input:{command:rm -rf /tmp/test}} | python .claude/hooks/pre-bash-guard.py預期輸出deny決策。換成echo hello應該無輸出表示放行。第二層在 Claude Code 里觸發(fā)真實 Hook啟動 Claude Code輸入一個會觸發(fā) Write 的指令比如“創(chuàng)建一個 test.txt 文件”。如果 PreToolUse 保護腳本配置正確寫普通文件應該正常通過然后手動讓它寫production/test.txt應該被拒絕并看到提示信息。PostToolUse 的驗證看日志文件tail -f ~/.claude/hooks/post-format.log讓 Claude 創(chuàng)建一個.py文件日志里應該出現black 格式化完成的記錄。如果日志文件根本沒生成說明 Hook 沒被觸發(fā)檢查settings.json的 JSON 格式是否正確python -c import json; json.load(open(.claude/settings.json)); print(JSON OK)第三層核對 API 通道回顯Hooks 腳本里如果調用了 TaoToken 的 API需要確認請求真的到達了正確端點。在腳本里加一行調試日志記錄實際請求的 URL 和響應狀態(tài)?；蛘哂胏url單獨驗證curl -s -o /dev/null -w %{http_code} \ -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:16,messages:[{role:user,content:hi}]}返回200說明通道正常。返回401檢查 Key返回404檢查 Base URL 是否多了/v1后綴。一個完整的成功鏈路應該是Claude Code 發(fā)起工具調用 → PreToolUse 腳本攔截并放行 → 工具執(zhí)行 → PostToolUse 腳本格式化并寫日志 → 日志文件出現對應記錄 → 如果腳本內調用了 TaoToken API請求返回 200。任何一環(huán)斷了按這個順序倒查。5. 常見報錯排查401、local proxy failed、reading choices 與 OAuth即使配置看起來沒問題實際跑起來還是會遇到各種報錯。下面按真實錯誤信息逐個拆解。報錯一401 Unauthorized這是最常見的。Claude Code 啟動后任何請求都返回 401說明ANTHROPIC_API_KEY無效或沒被讀到。排查順序先確認.claude/settings.json里env.ANTHROPIC_API_KEY的值沒有多余空格和換行再確認系統(tǒng)環(huán)境變量里沒有另一個沖突的ANTHROPIC_API_KEY覆蓋了配置最后用curl單獨測試 Key 是否有效。如果 Key 是從 TaoToken 控制臺復制的注意不要復制到前后空白字符。報錯二local proxy failed / connection refused這個錯誤通常出現在 Hook 腳本里調用了本地代理或錯誤的 Base URL。檢查腳本里拼接的 URL 是不是https://taotoken.net/api開頭有沒有誤寫成http://localhost:xxxx。如果你之前配置過其他代理工具確保環(huán)境變量HTTP_PROXY、HTTPS_PROXY沒有指向已關閉的本地端口。在 CI 環(huán)境里這個錯誤多半是因為 Secret 沒注入腳本讀到了空字符串然后拼出了一個無效地址。報錯三reading choices 相關錯誤這個報錯說明請求體格式和端點不匹配。常見原因是把 OpenAI 格式的請求發(fā)到了 Anthropic 端點或者反過來。Claude Code 走的是 Anthropic Messages API 格式請求體里應該是messages數組加model、max_tokens響應里是content數組。如果你在 Hook 腳本里自己構造請求確認content-type是application/jsonanthropic-version頭存在。TaoToken 的/api/v1/messages端點兼容 Anthropic 格式不要混用 OpenAI 的chat/completions路徑。報錯四OAuth 相關提示Claude Code 某些版本會嘗試 OAuth 流程如果你用的是 API Key 模式需要在配置里明確禁用 OAuth。檢查settings.json里有沒有forceLoginMethod之類的字段被設成了oauth。另外如果之前登錄過其他賬號~/.claude/目錄下可能殘留了舊的憑證文件刪掉~/.claude/auth.json或類似文件后重啟。報錯五Hook 執(zhí)行成功但沒效果PostToolUse 腳本跑了但格式化沒生效先看日志文件有沒有寫入。如果日志有記錄但文件沒變檢查格式化命令的路徑參數是不是相對路徑——Hook 執(zhí)行時的工作目錄可能不是項目根目錄。在腳本里用os.path.abspath(file_path)轉成絕對路徑再傳給格式化工具。PreToolUse 的deny沒生效檢查輸出 JSON 的字段名是不是hookSpecificOutput.permissionDecision舊版的decision字段在新版本里可能被忽略。報錯六timeout 頻繁觸發(fā)Hook 腳本超時被 kill日志里出現TimeoutExpired。把settings.json里的timeout值調大比如從 10 調到 30。如果腳本里有網絡請求給請求本身也設一個合理的超時避免整個腳本卡死。CI 環(huán)境里網絡延遲高timeout 建議設到 60。排查時記住一個原則先隔離再定位。把 Hook 腳本單獨拿出來用echo喂數據跑一遍能排除掉 Claude Code 配置層的干擾。確認腳本本身沒問題后再檢查settings.json的 JSON 結構和事件名拼寫。事件名是大小寫敏感的PreToolUse不能寫成preToolUse。6. 把自動化鏈路跑成可回滾的日常習慣配置 Hooks 最怕的不是寫錯而是寫完之后沒人知道它存在。團隊里新來的同學改了一個文件發(fā)現被莫名其妙拒絕了翻半天代碼才找到.claude/hooks/pre-protect.py里的規(guī)則。所以我在項目里養(yǎng)成了一個習慣所有 Hook 腳本頭部都寫清楚用途、觸發(fā)條件和維護人settings.json里的每個 Hook 條目旁邊用注釋說明JSON 不支持注釋就寫在 README 里?；貪L也很簡單。Hooks 的配置和腳本都在.claude/目錄下用 Git 管理起來任何改動都能追溯。如果某個 Hook 導致問題臨時把settings.json里對應的條目刪掉或者把matcher改成不匹配的值重啟 Claude Code 就恢復了。不需要卸載任何東西。API 通道這邊TaoToken 的 Key 可以在控制臺隨時禁用和重建。如果懷疑某個 Key 泄露直接禁用再創(chuàng)建一個新的更新環(huán)境變量即可所有 Hook 腳本自動用上新 Key。這種集中管理的方式比在每個腳本里改硬編碼的 Key 要省心得多。最后給一個實用建議從 PostToolUse 的日志 Hook 開始。它不會攔截任何操作只是默默記錄風險最低但能讓你清楚看到 Claude Code 到底在什么時候調用了什么工具。跑上一周你自然就知道哪些環(huán)節(jié)值得加 PreToolUse 攔截哪些文件需要保護。自動化不是一次配完就結束而是根據實際日志逐步收緊的過程。