Claude Code 每次調(diào)用工具、等待輸入、結(jié)束會(huì)話，都會(huì)觸發(fā)對(duì)應(yīng)的生命周期事件。你可以在這些事件上掛腳本，拿到上下文 JSON，決定 Claude 要不要繼續(xù)執(zhí)行。

Hooks 是什么

Claude 要調(diào)用工具時(shí)，Claude Code 把當(dāng)時(shí)的狀態(tài)打包成 JSON，通過(guò) stdin 傳給你配置的腳本，等腳本退出再繼續(xù)。

整個(gè)流程：

有哪些 Hook 事件

七個(gè)事件覆蓋一次完整會(huì)話的全過(guò)程：

PreToolUse 是最關(guān)鍵的事件。退出碼決定行為：0 繼續(xù)執(zhí)行，2 阻斷工具調(diào)用，其他非 0 記錄錯(cuò)誤但不阻斷。

怎么配置

打開(kāi) ~/.claude/settings.json，加入 hooks 字段：

{
??"hooks": {
? ??"PreToolUse": [
? ? ? {
? ? ? ??"hooks": [
? ? ? ? ? {
? ? ? ? ? ??"type":?"command",
? ? ? ? ? ??"command":?"python3 /path/to/my_hook.py"
? ? ? ? ? }
? ? ? ? ]
? ? ? }
? ? ],
? ??"Notification": [
? ? ? {
? ? ? ??"hooks": [
? ? ? ? ? {
? ? ? ? ? ??"type":?"command",
? ? ? ? ? ??"command":?"python3 /path/to/notify.py"
? ? ? ? ? }
? ? ? ? ]
? ? ? }
? ? ]
? }
}

每個(gè)事件可以配多個(gè)腳本，按順序執(zhí)行。腳本可以是任何可執(zhí)行文件，Python、Shell、Node 都行。

腳本收到什么數(shù)據(jù)

Claude Code 把 JSON 寫(xiě)入腳本的 stdin，不同事件的字段不同。

PreToolUse 示例：

{
??"session_id":?"abc-123",
"hook_event_name":?"PreToolUse",
"tool_name":?"Bash",
"tool_input": {
? ??"command":?"rm -rf /tmp/test"
? },
"cwd":?"/Users/you/myproject",
"tty":?"/dev/ttys001"
}

Notification 示例：

{
??"session_id":?"abc-123",
??"hook_event_name":?"Notification",
??"message":?"任務(wù)完成，等待你的下一步指令",
??"cwd":?"/Users/you/myproject"
}

Stop 示例：

{
??"session_id":?"abc-123",
??"hook_event_name":?"Stop",
??"cwd":?"/Users/you/myproject"
}

腳本還能通過(guò) stdout 影響 Claude

stdin 是 Claude Code 傳給腳本的數(shù)據(jù)，stdout 方向相反：腳本輸出 JSON 到 stdout，Claude Code 讀取并按內(nèi)容決策。

PreToolUse：用 stdout 阻斷或放行

腳本可以在 stdout 輸出一個(gè) JSON 對(duì)象，decision 字段控制行為：

import?json, sys

data = json.load(sys.stdin)

if?data.get("tool_name") ==?"Bash":
? ? command = data.get("tool_input", {}).get("command",?"")
? ??if"rm -rf"in?command:
? ? ? ??# 通過(guò) stdout JSON 阻斷
? ? ? ? print(json.dumps({
? ? ? ? ? ??"decision":?"block",
? ? ? ? ? ??"reason":?"禁止執(zhí)行 rm -rf"
? ? ? ? }))
? ? ? ? sys.exit(0) ?# stdout 已表達(dá)意圖，退出碼可以是 0

sys.exit(0)

decision 值為 "block" 時(shí)阻斷，"approve" 時(shí)強(qiáng)制放行（跳過(guò)權(quán)限提示）。

向 Claude 注入上下文

stdout JSON 還支持 additionalContext 字段，內(nèi)容會(huì)直接注入到 Claude 的上下文里，Claude 讀完再?zèng)Q定下一步。適合在工具調(diào)用前后補(bǔ)充環(huán)境信息：

print(json.dumps({
? ??"additionalContext":?"當(dāng)前磁盤(pán)剩余空間 2GB，請(qǐng)謹(jǐn)慎執(zhí)行大文件操作"
}))
sys.exit(0)

動(dòng)手寫(xiě)第一個(gè) Hook

示例 1：記錄 Claude 調(diào)用過(guò)的所有命令

#!/usr/bin/env python3
import?json
import?sys
from?datetime?import?datetime

data = json.load(sys.stdin)

if?data.get("tool_name") ==?"Bash":
? ? command = data.get("tool_input", {}).get("command",?"")
? ??with?open("/tmp/claude_commands.log",?"a")?as?f:
? ? ? ? f.write(f"{datetime.now()}?|?{command}\n")

sys.exit(0) ?# 退出碼 0，Claude 繼續(xù)執(zhí)行

掛在 PostToolUse 上，Claude 每跑完一條 Bash 命令，日志文件就多一行。

示例 2：阻止刪除操作

#!/usr/bin/env python3
import?json
import?sys

data = json.load(sys.stdin)

if?data.get("tool_name") ==?"Bash":
? ? command = data.get("tool_input", {}).get("command",?"")
? ??if?"rm -rf"?in?command:
? ? ? ? print("攔截：禁止執(zhí)行 rm -rf", file=sys.stderr)
? ? ? ? sys.exit(2) ?# 退出碼 2，Claude 放棄這次工具調(diào)用

sys.exit(0)

退出碼 2 是 PreToolUse 的阻斷信號(hào)。Claude 讀到 stderr，把它當(dāng)作拒絕原因展示給用戶，然后停止這次工具調(diào)用。退出碼 1 或其他非 0 值只會(huì)記錄錯(cuò)誤，Claude 仍會(huì)繼續(xù)執(zhí)行。

示例 3：任務(wù)完成時(shí)發(fā)系統(tǒng)通知

#!/usr/bin/env python3
import?json
import?sys
import?subprocess

data = json.load(sys.stdin)

subprocess.run([
? ??"osascript",?"-e",
? ??f'display notification "Claude 完成了，去看看吧" with title "Claude Code"'
])

sys.exit(0)

把這個(gè)腳本掛在 Stop 或 Notification 上。Claude 停下來(lái)等你回復(fù)時(shí)，Mac 右上角就會(huì)彈出通知。

示例 4：針對(duì)特定工具設(shè)置 matcher

如果只想監(jiān)聽(tīng)某類工具，加 matcher 字段：

{
??"hooks": {
? ??"PreToolUse": [
? ? ? {
? ? ? ??"matcher":?"Bash",
? ? ? ??"hooks": [
? ? ? ? ? {
? ? ? ? ? ??"type":?"command",
? ? ? ? ? ??"command":?"python3 /path/to/bash_guard.py"
? ? ? ? ? }
? ? ? ? ]
? ? ? }
? ? ]
? }
}

加了 matcher，只有 Bash 工具觸發(fā)時(shí)腳本才跑，Edit、Read 等其他工具不走這里。

腳本拿到數(shù)據(jù)后能做什么

寫(xiě)日志：把 Claude 的所有工具調(diào)用記下來(lái)，方便復(fù)盤(pán)

發(fā)通知：Claude 等待輸入時(shí)，通過(guò)系統(tǒng)通知或微信、釘釘提醒你

阻斷危險(xiǎn)操作：檢測(cè)到高風(fēng)險(xiǎn)命令，退出碼 2 阻止執(zhí)行

轉(zhuǎn)發(fā)事件：把 JSON 發(fā)到本地 socket，驅(qū)動(dòng)自定義 UI 或狀態(tài)面板

記錄耗時(shí)：PreToolUse 記開(kāi)始時(shí)間，PostToolUse 記結(jié)束時(shí)間，統(tǒng)計(jì)每類工具的耗時(shí)分布

進(jìn)階：用 Hooks 驅(qū)動(dòng)自定義 UI

Hook 腳本除了做判斷和記錄，還可以把事件轉(zhuǎn)發(fā)到本地 socket，讓一個(gè)常駐進(jìn)程處理所有狀態(tài)變化。

轉(zhuǎn)發(fā)腳本只需幾行：

#!/usr/bin/env python3
import?json, socket, sys
data = sys.stdin.read()
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect("/tmp/my_app.sock")
sock.sendall((data +?"\n").encode())
response = sock.recv(1024).decode().strip()
sock.close()
# 常駐進(jìn)程返回 "block" 時(shí)阻斷工具調(diào)用（必須用退出碼 2）
sys.exit(2if?response ==?"block"else0)

常駐進(jìn)程在 socket 上監(jiān)聽(tīng)，收到 PreToolUse 彈出確認(rèn)窗口，用戶點(diǎn)通過(guò)就回 ok，點(diǎn)拒絕就回 block，hook 腳本根據(jù)返回值決定退出碼。這樣就能在 Claude 執(zhí)行過(guò)程中插入任意交互界面，不限于終端。

上手步驟

1. 創(chuàng)建你的腳本文件，給執(zhí)行權(quán)限：chmod +x my_hook.py
2. 編輯 ~/.claude/settings.json，加入 hooks 配置
3. 啟動(dòng)一個(gè)新的 Claude Code 會(huì)話（已有會(huì)話需要重啟才能加載新配置）
4. 觸發(fā)相關(guān)操作，看腳本是否被調(diào)用

調(diào)試時(shí)在腳本里加 print(json.dumps(data, indent=2), file=sys.stderr) 把收到的完整數(shù)據(jù)打出來(lái)，Claude Code 會(huì)把 stderr 輸出顯示在終端。

一個(gè)腳本、一個(gè)退出碼，就能接入 Claude Code 的整個(gè)執(zhí)行流程。你的腳本負(fù)責(zé)判斷邏輯，Claude Code 負(fù)責(zé)觸發(fā)和等待，各管各的。

到此這篇關(guān)于一文詳解Claude Code中Hooks的使用的文章就介紹到這了,更多相關(guān)Claude Code Hooks使用內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論