結論先說
- Hooks 不只有本地 Shell 腳本:在
settings.json中,鉤子處理器除了傳統的"type": "command",還原生支持"type": "http"與"type": "prompt"(需要讀倉庫文件核實時還有多輪"type": "agent")。 - 語義把關選
Prompt Hooks:由快速模型對工具入參或結束狀態做單輪判斷,返回{"ok": true}放行、返回{"ok": false, "reason": "..."}則攔截並把原因喂回主模型重做。 - 集中審計選
HTTP Hooks:無需本地裝腳本依賴,直接向指定 URL 發送 JSONPOST請求;請求頭裏的鑑權變量必須列入allowedEnvVars才會展開。 - 每次觸發
prompt鉤子都會產生一次輕量模型調用:務必配好matcher(如只盯Bash或Stop),不要無差別掛載到每次讀文件事件上。 - 開通與配額升級入口:開啟模型判定鉤子會增加高頻交互的額度消耗;國內用戶可通過本站 Claude Code 訂閱專頁 或免密兌換的 Claude Pro iOS 卡密 開通,重度防禦配置建議選 5 倍額度的 Claude Max 升級服務。

圖:本站根據 Claude Code 官方文檔:Automate workflows with hooks 整理的示意圖
本文根據 Claude Code 官方文檔《Automate workflows with hooks》與《Claude Code settings》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。
適用於誰
- 寫過本地 Shell 鉤子,但發現正則很難兜住花式變形的高危命令或半途而廢的敷衍收尾,想引入語義判斷的人;
- 團隊跨 Windows 與 macOS 辦公,不想在每個人電腦裝一套 Python 與
jq腳本,希望統一連內網審計網關的負責人; - 想理清
command、http、prompt三類鉤子配置字段與成本邊界的開發者。
一、command、http 與 prompt 三種鉤子怎麼選
如果你還沒配過基礎 Shell 鉤子,可先看 Claude Code Hooks 基礎入門示例。當規則變複雜後,三種類型的優劣分工非常清晰:
| 鉤子類型 | 執行方式 | 延遲與額度消耗 | 最適合攔截或處理的場景 |
|---|---|---|---|
command | 本機跑 Shell 腳本看退出碼 | 毫秒級,零模型消耗 | 固定格式化、提交前跑測試(退出碼 2 攔截) |
http | 向遠程或本地服務發 HTTP POST | 取決於接口延遲,零模型消耗 | 團隊統一安全網關審批、集中寫審計日誌 |
prompt | 調用輕量模型做單輪語義判斷 | 秒級,每次觸發耗少量配額 | 識別變形危險命令、在 Stop 檢查是否真做完任務 |
確定性規則(比如提交前必須跑過單測)永遠優先用零成本的 command,具體寫法見 PreToolUse 提交前自動跑測試實戰;只有正則寫不出來的模糊語義邊界,才交給 prompt。
二、Prompt Hooks 配置實戰:攔截變相刪庫與敷衍收尾
type: "prompt" 會把當前事件上下文傳給判定模型,模型只需按官方內置約定返回 ok 布爾值與攔截理由。下面是在 .claude/settings.json 中同時防範高危 Shell 命令與提前收工的配置模板:
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "審查即將執行的命令參數:$ARGUMENTS。若涉及刪除生產目錄、導出環境變量密鑰或強推主分支則判定不安全並說明原因,常規開發測試命令放行。",
"timeout": 30
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "檢查 Claude 是否已完成用戶要求的全部修改並運行了驗證命令,若只給口頭建議未落地驗證則返回不通過。"
}
]
}
]
}
}
當 Stop 事件裏的 prompt 鉤子判定未完成時,主會話不會停下,而是收到 reason 提示自動補齊遺漏步驟。關於配置文件的作用域層級見 Claude Code settings.json 詳解。
Prompt Hooks 額外模型消耗提示:掛載在PreToolUse上的prompt鉤子會在每次匹配工具執行前發起一次模型判定請求,長鏈路任務下累計消耗明顯高於純腳本模式。日常開啟語義守衛的開發者,建議通過 Claude Pro 會員自助充值 保持訂閱,或直接升級 Claude Max 會員服務 留足安全餘量。
三、HTTP Hooks 配置實戰:統一網關鑑權與返回格式
跨平台團隊如果把 .claude/settings.json 提交進 Git,Windows 成員跑 .sh 腳本常報錯。改用 type: "http" 把事件發往團隊內網服務即可跨系統統一:

圖:本站根據 Claude Code 官方文檔:Automate workflows with hooks 整理的示意圖
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Write|Edit",
"hooks": [
{
"type": "http",
"url": "https://audit.internal.example.com/claude-hook",
"headers": {
"Authorization": "Bearer $AUDIT_HOOK_TOKEN"
},
"allowedEnvVars": ["AUDIT_HOOK_TOKEN"],
"timeout": 15
}
]
}
]
}
}
配置 HTTP 鉤子要注意兩點:
- 必須配
allowedEnvVars:為了防止惡意倉庫借請求頭偷發你本機的環境變量,未列進allowedEnvVars數組的$變量名會按空串處理; - 用 JSON 正文而不是 HTTP 500 表達攔截:服務端要拒絕本次工具執行時,應正常返回
200 OK並在響應 JSON 裏帶上permissionDecision: "deny"(或頂層"decision": "block"與"reason"),日常靜態權限白名單則可配合 Claude Code 權限模式配置。
常見問題
問:type: "prompt" 鉤子裏模型能自己去讀項目裏的其他文件嗎?
答:不能。prompt 鉤子是無工具的單輪快速判定,只能看到傳入的事件 JSON;如果必須先去翻源碼核實才能下結論,官方文檔提供了支持多輪讀文件的 "type": "agent" 鉤子。
問:HTTP 鉤子接口超時或掛掉會把開發者的終端卡死嗎?
答:按官方說明,網絡超時或非 2xx 狀態碼預設按非阻斷警告處理並允許繼續工作,但建議設短 timeout(如 10 至 15 秒)減少等待。
問:拉取別人的開源倉庫,裏面的惡意 HTTP 鉤子會自動執行嗎?
答:Claude Code 對項目級配置文件中的鉤子有信任確認與安全審查機制,首次打開陌生倉庫切勿盲目點信任,也可在交互中輸 /hooks 檢查當前生效列表。
問:國內團隊沒有外幣信用卡,怎麼開通訂閱並開報銷發票?
答:可通過本站 Claude Code 訂閱專頁 或 AI 會員充值總覽 辦理,支持支付寶、微信支付與 AlipayHK,提供免交密碼的卡密自助兌換,企業採購可開具國內增值稅發票。實時價格與售後細則以頁面為準:訂閱期內非違規掉訂閱按剩餘天數折退,風控封號不在質保範圍。
相關教學
- Claude Code Hooks 怎麼用:通知、格式化與攔截示例
- Claude Code Hooks 實戰:提交前自動跑測試
- Claude Code settings.json 配置文件詳解
- Claude Code 權限模式詳解:auto、plan 與規則配置
參考資料
- Claude Code 官方文檔:Automate workflows with hooks — https://code.claude.com/docs/en/hooks
- Claude Code 官方文檔:Claude Code settings — https://code.claude.com/docs/en/settings
0 條評論
還沒有評論,來搶沙發~