Hooks
透過註冊 shell 命令來自訂和擴展 Claude Code 的行為
介紹
Claude Code hooks 是使用者定義的 shell 命令,在 Claude Code 生命週期的各個時點執行。Hooks 提供對 Claude Code 行為的確定性控制,確保某些動作總是會發生,而不是依賴 LLM 選擇執行它們。
範例使用案例包括:
- 通知:自訂當 Claude Code 等待您的輸入或執行權限時如何通知您。
- 自動格式化:在每次檔案編輯後對 .ts 檔案執行
prettier
,對 .go 檔案執行gofmt
等。 - 記錄:追蹤和計算所有執行的命令以符合合規性或除錯需求。
- 回饋:當 Claude Code 產生不符合您程式碼庫慣例的程式碼時提供自動回饋。
- 自訂權限:阻止對生產檔案或敏感目錄的修改。
透過將這些規則編碼為 hooks 而不是提示指令,您將建議轉換為應用程式層級的程式碼,每次預期執行時都會執行。
Hooks 會以您的完整使用者權限執行 shell 命令,無需確認。您有責任確保您的 hooks 是安全的。Anthropic 不對因使用 hook 而導致的任何資料遺失或系統損壞承擔責任。請檢閱安全考量。
快速開始
在此快速開始中,您將新增一個記錄 Claude Code 執行的 shell 命令的 hook。
快速開始先決條件:安裝 jq
以在命令列中進行 JSON 處理。
步驟 1:開啟 hooks 設定
執行 /hooks
斜線命令 並選擇 PreToolUse
hook 事件。
PreToolUse
hooks 在工具呼叫之前執行,可以阻止它們並向 Claude 提供關於如何做不同處理的回饋。
步驟 2:新增匹配器
選擇 + Add new matcher…
以僅在 Bash 工具呼叫上執行您的 hook。
為匹配器輸入 Bash
。
步驟 3:新增 hook
選擇 + Add new hook…
並輸入此命令:
步驟 4:儲存您的設定
對於儲存位置,選擇 User settings
,因為您要記錄到您的家目錄。此 hook 將適用於所有專案,而不僅僅是您目前的專案。
然後按 Esc 直到您回到 REPL。您的 hook 現在已註冊!
步驟 5:驗證您的 hook
再次執行 /hooks
或檢查 ~/.claude/settings.json
以查看您的設定:
設定
Claude Code hooks 在您的設定檔案中設定:
~/.claude/settings.json
- 使用者設定.claude/settings.json
- 專案設定.claude/settings.local.json
- 本地專案設定(不提交)- 企業管理政策設定
結構
Hooks 按匹配器組織,每個匹配器可以有多個 hooks:
- matcher:匹配工具名稱的模式(僅適用於
PreToolUse
和PostToolUse
)- 簡單字串精確匹配:
Write
僅匹配 Write 工具 - 支援正規表示式:
Edit|Write
或Notebook.*
- 如果省略或空字串,hooks 會對所有匹配事件執行
- 簡單字串精確匹配:
- hooks:當模式匹配時要執行的命令陣列
type
:目前僅支援"command"
command
:要執行的 bash 命令timeout
:(可選)命令應該執行多長時間(以秒為單位),超時後取消所有進行中的 hooks。
Hook 事件
PreToolUse
在 Claude 建立工具參數之後、處理工具呼叫之前執行。
常見匹配器:
Task
- 代理任務Bash
- Shell 命令Glob
- 檔案模式匹配Grep
- 內容搜尋Read
- 檔案讀取Edit
、MultiEdit
- 檔案編輯Write
- 檔案寫入WebFetch
、WebSearch
- 網路操作
PostToolUse
在工具成功完成後立即執行。
識別與 PreToolUse 相同的匹配器值。
Notification
當 Claude Code 發送通知時執行。
Stop
當主要 Claude Code 代理完成回應時執行。
SubagentStop
當 Claude Code 子代理(Task 工具呼叫)完成回應時執行。
Hook 輸入
Hooks 透過 stdin 接收包含會話資訊和事件特定資料的 JSON 資料:
PreToolUse 輸入
tool_input
的確切架構取決於工具。
PostToolUse 輸入
tool_input
和 tool_response
的確切架構取決於工具。
Notification 輸入
Stop 和 SubagentStop 輸入
當 Claude Code 已經因為 stop hook 而繼續時,stop_hook_active
為 true。檢查此值或處理記錄以防止 Claude Code 無限期執行。
Hook 輸出
有兩種方式讓 hooks 將輸出返回給 Claude Code。輸出傳達是否阻止以及應該向 Claude 和使用者顯示的任何回饋。
簡單:退出代碼
Hooks 透過退出代碼、stdout 和 stderr 傳達狀態:
- 退出代碼 0:成功。
stdout
在記錄模式(CTRL-R)中向使用者顯示。 - 退出代碼 2:阻止錯誤。
stderr
回饋給 Claude 自動處理。請參閱下面的每個 hook 事件行為。 - 其他退出代碼:非阻止錯誤。
stderr
向使用者顯示,執行繼續。
提醒:如果退出代碼為 0,Claude Code 不會看到 stdout。
退出代碼 2 行為
Hook 事件 | 行為 |
---|---|
PreToolUse | 阻止工具呼叫,向 Claude 顯示錯誤 |
PostToolUse | 向 Claude 顯示錯誤(工具已執行) |
Notification | N/A,僅向使用者顯示 stderr |
Stop | 阻止停止,向 Claude 顯示錯誤 |
SubagentStop | 阻止停止,向 Claude 子代理顯示錯誤 |
進階:JSON 輸出
Hooks 可以在 stdout
中返回結構化 JSON 以進行更複雜的控制:
通用 JSON 欄位
所有 hook 類型都可以包含這些可選欄位:
如果 continue
為 false,Claude 在 hooks 執行後停止處理。
- 對於
PreToolUse
,這與"decision": "block"
不同,後者僅阻止特定工具呼叫並向 Claude 提供自動回饋。 - 對於
PostToolUse
,這與"decision": "block"
不同,後者向 Claude 提供自動回饋。 - 對於
Stop
和SubagentStop
,這優先於任何"decision": "block"
輸出。 - 在所有情況下,
"continue" = false
優先於任何"decision": "block"
輸出。
stopReason
伴隨 continue
提供向使用者顯示的原因,不向 Claude 顯示。
PreToolUse
決策控制
PreToolUse
hooks 可以控制工具呼叫是否進行。
- “approve” 繞過權限系統。
reason
向使用者顯示但不向 Claude 顯示。 - “block” 防止工具呼叫執行。
reason
向 Claude 顯示。 undefined
導致現有權限流程。reason
被忽略。
PostToolUse
決策控制
PostToolUse
hooks 可以控制工具呼叫是否進行。
- “block” 自動用
reason
提示 Claude。 undefined
什麼都不做。reason
被忽略。
Stop
/SubagentStop
決策控制
Stop
和 SubagentStop
hooks 可以控制 Claude 是否必須繼續。
- “block” 防止 Claude 停止。您必須填入
reason
讓 Claude 知道如何進行。 undefined
允許 Claude 停止。reason
被忽略。
JSON 輸出範例:Bash 命令編輯
使用 MCP 工具
Claude Code hooks 與模型上下文協定(MCP)工具無縫協作。當 MCP 伺服器提供工具時,它們會以特殊的命名模式出現,您可以在 hooks 中匹配。
MCP 工具命名
MCP 工具遵循模式 mcp__<server>__<tool>
,例如:
mcp__memory__create_entities
- Memory 伺服器的建立實體工具mcp__filesystem__read_file
- Filesystem 伺服器的讀取檔案工具mcp__github__search_repositories
- GitHub 伺服器的搜尋工具
為 MCP 工具設定 Hooks
您可以針對特定 MCP 工具或整個 MCP 伺服器:
範例
程式碼格式化
在檔案修改後自動格式化程式碼:
通知
自訂當 Claude Code 請求權限或提示輸入變為閒置時發送的通知。
安全考量
免責聲明
使用風險自負:Claude Code hooks 會在您的系統上自動執行任意 shell 命令。透過使用 hooks,您確認:
- 您對您設定的命令負全責
- Hooks 可以修改、刪除或存取您的使用者帳戶可以存取的任何檔案
- 惡意或編寫不當的 hooks 可能導致資料遺失或系統損壞
- Anthropic 不提供保證且不對因使用 hook 而導致的任何損壞承擔責任
- 您應該在生產使用前在安全環境中徹底測試 hooks
在將任何 hook 命令新增到您的設定之前,請務必檢閱並理解它們。
安全最佳實務
以下是編寫更安全 hooks 的一些關鍵實務:
- 驗證和清理輸入 - 永遠不要盲目信任輸入資料
- 總是引用 shell 變數 - 使用
"$VAR"
而不是$VAR
- 阻止路徑遍歷 - 檢查檔案路徑中的
..
- 使用絕對路徑 - 為腳本指定完整路徑
- 跳過敏感檔案 - 避免
.env
、.git/
、金鑰等
設定安全
直接編輯設定檔案中的 hooks 不會立即生效。Claude Code:
- 在啟動時擷取 hooks 的快照
- 在整個會話中使用此快照
- 如果 hooks 被外部修改則警告
- 需要在
/hooks
選單中檢閱才能應用變更
這防止惡意 hook 修改影響您目前的會話。
Hook 執行詳細資訊
- 逾時:預設 60 秒執行限制,每個命令可設定。
- 如果任何個別命令逾時,所有進行中的 hooks 都會被取消。
- 平行化:所有匹配的 hooks 平行執行
- 環境:在目前目錄中以 Claude Code 的環境執行
- 輸入:透過 stdin 的 JSON
- 輸出:
- PreToolUse/PostToolUse/Stop:進度在記錄中顯示(Ctrl-R)
- Notification:僅記錄到除錯(
--debug
)
除錯
要排除 hooks 故障:
- 檢查
/hooks
選單是否顯示您的設定 - 驗證您的設定檔案是有效的 JSON
- 手動測試命令
- 檢查退出代碼
- 檢閱 stdout 和 stderr 格式期望
- 確保適當的引號轉義
- 使用
claude --debug
來除錯您的 hooks。成功 hook 的輸出如下所示。
進度訊息出現在記錄模式(Ctrl-R)中,顯示:
- 哪個 hook 正在執行
- 正在執行的命令
- 成功/失敗狀態
- 輸出或錯誤訊息