Hooks 參考文件
本頁面提供在 Claude Code 中實作 hooks 的參考文件。
如需包含範例的快速入門指南,請參閱 Claude Code hooks 入門。
配置
Claude Code hooks 在您的設定檔案中配置:
~/.claude/settings.json
- 使用者設定.claude/settings.json
- 專案設定.claude/settings.local.json
- 本地專案設定(不提交)- 企業管理政策設定
結構
Hooks 按匹配器組織,每個匹配器可以有多個 hooks:
- matcher:匹配工具名稱的模式,區分大小寫(僅適用於
PreToolUse
和PostToolUse
)- 簡單字串完全匹配:
Write
僅匹配 Write 工具 - 支援正規表示式:
Edit|Write
或Notebook.*
- 使用
*
匹配所有工具。您也可以使用空字串(""
)或將matcher
留空。
- 簡單字串完全匹配:
- hooks:當模式匹配時要執行的命令陣列
type
:目前僅支援"command"
command
:要執行的 bash 命令(可以使用$CLAUDE_PROJECT_DIR
環境變數)timeout
:(可選)命令應該執行多長時間(以秒為單位),超過時間後取消該特定命令。
對於像 UserPromptSubmit
、Notification
、Stop
和 SubagentStop
這樣不使用匹配器的事件,您可以省略匹配器欄位:
專案特定的 Hook 腳本
您可以使用環境變數 CLAUDE_PROJECT_DIR
(僅在 Claude Code 產生 hook 命令時可用)來引用儲存在專案中的腳本,確保無論 Claude 的當前目錄如何,它們都能正常工作:
Hook 事件
PreToolUse
在 Claude 建立工具參數之後、處理工具呼叫之前執行。
常見匹配器:
Task
- 子代理任務(參見子代理文件)Bash
- Shell 命令Glob
- 檔案模式匹配Grep
- 內容搜尋Read
- 檔案讀取Edit
、MultiEdit
- 檔案編輯Write
- 檔案寫入WebFetch
、WebSearch
- 網路操作
PostToolUse
在工具成功完成後立即執行。
識別與 PreToolUse 相同的匹配器值。
Notification
當 Claude Code 發送通知時執行。通知在以下情況下發送:
- Claude 需要您的許可才能使用工具。例如:“Claude needs your permission to use Bash”
- 提示輸入已閒置至少 60 秒。“Claude is waiting for your input”
UserPromptSubmit
當使用者提交提示時、Claude 處理之前執行。這允許您根據提示/對話添加額外的上下文、驗證提示或阻止某些類型的提示。
Stop
當主要的 Claude Code 代理完成回應時執行。如果停止是由於使用者中斷而發生的,則不會執行。
SubagentStop
當 Claude Code 子代理(Task 工具呼叫)完成回應時執行。
SessionEnd
當 Claude Code 會話結束時執行。對於清理任務、記錄會話統計或保存會話狀態很有用。
hook 輸入中的 reason
欄位將是以下之一:
clear
- 使用 /clear 命令清除會話logout
- 使用者登出prompt_input_exit
- 使用者在提示輸入可見時退出other
- 其他退出原因
PreCompact
在 Claude Code 即將執行壓縮操作之前執行。
匹配器:
manual
- 從/compact
調用auto
- 從自動壓縮調用(由於上下文視窗已滿)
SessionStart
當 Claude Code 開始新會話或恢復現有會話時執行(目前確實會在底層開始新會話)。對於載入開發上下文(如現有問題或程式碼庫的最近更改)很有用。
匹配器:
startup
- 從啟動調用resume
- 從--resume
、--continue
或/resume
調用clear
- 從/clear
調用
Hook 輸入
Hooks 透過 stdin 接收包含會話資訊和事件特定資料的 JSON 資料:
PreToolUse 輸入
tool_input
的確切架構取決於工具。
PostToolUse 輸入
tool_input
和 tool_response
的確切架構取決於工具。
Notification 輸入
UserPromptSubmit 輸入
Stop 和 SubagentStop 輸入
當 Claude Code 已經因為 stop hook 而繼續時,stop_hook_active
為 true。檢查此值或處理記錄以防止 Claude Code 無限期執行。
PreCompact 輸入
對於 manual
,custom_instructions
來自使用者傳遞給 /compact
的內容。對於 auto
,custom_instructions
為空。
SessionStart 輸入
SessionEnd 輸入
Hook 輸出
有兩種方式讓 hooks 將輸出返回給 Claude Code。輸出傳達是否要阻止以及應該向 Claude 和使用者顯示的任何回饋。
簡單:退出代碼
Hooks 透過退出代碼、stdout 和 stderr 傳達狀態:
- 退出代碼 0:成功。
stdout
在記錄模式(CTRL-R)中向使用者顯示,除了UserPromptSubmit
和SessionStart
,其中 stdout 被添加到上下文中。 - 退出代碼 2:阻止錯誤。
stderr
被回饋給 Claude 自動處理。請參閱下面的每個 hook 事件行為。 - 其他退出代碼:非阻止錯誤。
stderr
向使用者顯示,執行繼續。
提醒:如果退出代碼為 0,Claude Code 不會看到 stdout,除了 UserPromptSubmit
hook,其中 stdout 被注入為上下文。
退出代碼 2 行為
Hook 事件 | 行為 |
---|---|
PreToolUse | 阻止工具呼叫,向 Claude 顯示 stderr |
PostToolUse | 向 Claude 顯示 stderr(工具已經執行) |
Notification | N/A,僅向使用者顯示 stderr |
UserPromptSubmit | 阻止提示處理,清除提示,僅向使用者顯示 stderr |
Stop | 阻止停止,向 Claude 顯示 stderr |
SubagentStop | 阻止停止,向 Claude 子代理顯示 stderr |
PreCompact | N/A,僅向使用者顯示 stderr |
SessionStart | N/A,僅向使用者顯示 stderr |
SessionEnd | N/A,僅向使用者顯示 stderr |
進階:JSON 輸出
Hooks 可以在 stdout
中返回結構化 JSON 以進行更複雜的控制:
通用 JSON 欄位
所有 hook 類型都可以包含這些可選欄位:
如果 continue
為 false,Claude 在 hooks 執行後停止處理。
- 對於
PreToolUse
,這與"permissionDecision": "deny"
不同,後者僅阻止特定的工具呼叫並向 Claude 提供自動回饋。 - 對於
PostToolUse
,這與"decision": "block"
不同,後者向 Claude 提供自動回饋。 - 對於
UserPromptSubmit
,這防止提示被處理。 - 對於
Stop
和SubagentStop
,這優先於任何"decision": "block"
輸出。 - 在所有情況下,
"continue" = false
優先於任何"decision": "block"
輸出。
stopReason
伴隨 continue
提供向使用者顯示的原因,不向 Claude 顯示。
PreToolUse
決策控制
PreToolUse
hooks 可以控制工具呼叫是否繼續。
"allow"
繞過許可系統。permissionDecisionReason
向使用者顯示但不向 Claude 顯示。"deny"
防止工具呼叫執行。permissionDecisionReason
向 Claude 顯示。"ask"
要求使用者在 UI 中確認工具呼叫。permissionDecisionReason
向使用者顯示但不向 Claude 顯示。
decision
和 reason
欄位對於 PreToolUse hooks 已棄用。
請改用 hookSpecificOutput.permissionDecision
和
hookSpecificOutput.permissionDecisionReason
。已棄用的欄位
"approve"
和 "block"
分別對應到 "allow"
和 "deny"
。
PostToolUse
決策控制
PostToolUse
hooks 可以在工具執行後向 Claude 提供回饋。
"block"
自動向 Claude 提示reason
。undefined
什麼都不做。reason
被忽略。"hookSpecificOutput.additionalContext"
添加 Claude 要考慮的上下文。
UserPromptSubmit
決策控制
UserPromptSubmit
hooks 可以控制是否處理使用者提示。
"block"
防止提示被處理。提交的提示從上下文中清除。"reason"
向使用者顯示但不添加到上下文中。undefined
允許提示正常進行。"reason"
被忽略。"hookSpecificOutput.additionalContext"
如果未被阻止,將字串添加到上下文中。
Stop
/SubagentStop
決策控制
Stop
和 SubagentStop
hooks 可以控制 Claude 是否必須繼續。
"block"
防止 Claude 停止。您必須填充reason
讓 Claude 知道如何繼續。undefined
允許 Claude 停止。reason
被忽略。
SessionStart
決策控制
SessionStart
hooks 允許您在會話開始時載入上下文。
"hookSpecificOutput.additionalContext"
將字串添加到上下文中。- 多個 hooks 的
additionalContext
值會被串聯。
SessionEnd
決策控制
SessionEnd
hooks 在會話結束時執行。它們無法阻止會話終止,但可以執行清理任務。
退出代碼範例:Bash 命令驗證
JSON 輸出範例:UserPromptSubmit 添加上下文和驗證
對於 UserPromptSubmit
hooks,您可以使用任一方法注入上下文:
- 退出代碼 0 與 stdout:Claude 看到上下文(
UserPromptSubmit
的特殊情況) - JSON 輸出:提供對行為的更多控制
JSON 輸出範例:PreToolUse 與批准
使用 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 hooks 會在您的系統上自動執行任意 shell 命令。使用 hooks 即表示您承認:
- 您對配置的命令負全部責任
- Hooks 可以修改、刪除或存取您的使用者帳戶可以存取的任何檔案
- 惡意或編寫不當的 hooks 可能導致資料遺失或系統損壞
- Anthropic 不提供保證,對於因使用 hook 而導致的任何損害不承擔責任
- 您應該在生產使用之前在安全環境中徹底測試 hooks
在將任何 hook 命令添加到您的配置之前,請務必檢查並理解它們。
安全最佳實踐
以下是編寫更安全 hooks 的一些關鍵實踐:
- 驗證和清理輸入 - 永遠不要盲目信任輸入資料
- 總是引用 shell 變數 - 使用
"$VAR"
而不是$VAR
- 阻止路徑遍歷 - 檢查檔案路徑中的
..
- 使用絕對路徑 - 為腳本指定完整路徑(使用
$CLAUDE_PROJECT_DIR
作為專案路徑) - 跳過敏感檔案 - 避免
.env
、.git/
、金鑰等
配置安全
直接編輯設定檔案中的 hooks 不會立即生效。Claude Code:
- 在啟動時擷取 hooks 的快照
- 在整個會話中使用此快照
- 如果 hooks 被外部修改則發出警告
- 需要在
/hooks
選單中檢查更改才能應用
這防止惡意 hook 修改影響您當前的會話。
Hook 執行詳情
- 超時:預設 60 秒執行限制,每個命令可配置。
- 個別命令的超時不會影響其他命令。
- 並行化:所有匹配的 hooks 並行執行
- 去重:多個相同的 hook 命令會自動去重
- 環境:在當前目錄中使用 Claude Code 的環境執行
CLAUDE_PROJECT_DIR
環境變數可用,包含專案根目錄的絕對路徑(Claude Code 啟動的地方)
- 輸入:透過 stdin 的 JSON
- 輸出:
- PreToolUse/PostToolUse/Stop/SubagentStop:進度在記錄中顯示(Ctrl-R)
- Notification/SessionEnd:僅記錄到除錯(
--debug
) - UserPromptSubmit/SessionStart:stdout 作為 Claude 的上下文添加
除錯
基本故障排除
如果您的 hooks 不工作:
- 檢查配置 - 執行
/hooks
查看您的 hook 是否已註冊 - 驗證語法 - 確保您的 JSON 設定有效
- 測試命令 - 首先手動執行 hook 命令
- 檢查權限 - 確保腳本可執行
- 檢查日誌 - 使用
claude --debug
查看 hook 執行詳情
常見問題:
- 引號未轉義 - 在 JSON 字串中使用
\"
- 錯誤的匹配器 - 檢查工具名稱完全匹配(區分大小寫)
- 找不到命令 - 為腳本使用完整路徑
進階除錯
對於複雜的 hook 問題:
- 檢查 hook 執行 - 使用
claude --debug
查看詳細的 hook 執行 - 驗證 JSON 架構 - 使用外部工具測試 hook 輸入/輸出
- 檢查環境變數 - 驗證 Claude Code 的環境是否正確
- 測試邊緣情況 - 嘗試使用不尋常的檔案路徑或輸入的 hooks
- 監控系統資源 - 檢查 hook 執行期間的資源耗盡
- 使用結構化記錄 - 在您的 hook 腳本中實作記錄
除錯輸出範例
使用 claude --debug
查看 hook 執行詳情:
進度訊息出現在記錄模式(Ctrl-R)中,顯示:
- 哪個 hook 正在執行
- 正在執行的命令
- 成功/失敗狀態
- 輸出或錯誤訊息