用法

Claude Code Hooks 教程：怎麼配置 hooks、選事件、套用現成示例

釋出於 2026 年 10 月 30 日 · 最後核對 2026 年 10 月 30 日

Hooks 是使用者自定義的 shell 命令，Claude Code 在生命週期的特定時刻執行它們。執行的是 hook 而不是模型，所以這個動作一定會發生。這一頁是操作步驟：hook 放在哪裡、一條 hook 長什麼樣、哪些事件最常用、四個可以直接貼上的示例、退出碼怎麼攔截操作、hook 沒反應時看什麼。內容按 Anthropic 的 Automate actions with hooks 和 Hooks reference 中文整理，2026 年 10 月 30 日對照原文核對。

Hooks 是什麼，什麼時候該用

Hooks 是使用者自定義的 shell 命令。Claude Code 在生命週期的特定時刻執行它們，讓你獲得確定性的控制：某些動作一定會發生，而不是依賴 LLM 自己決定要不要執行。可以用 hooks 來落實專案規則、自動化重複任務，以及把 Claude Code 接進你已有的工具。

Anthropic 給出的用法包括：編輯後格式化檔案、在命令執行前攔截命令、Claude 需要輸入時發通知、工作階段開始時注入上下文。需要判斷而不是確定性規則的決定，指南指向 prompt hook 和 agent hook，它們用 Claude 模型來評估條件。想在每次工作階段開始時注入上下文，指南建議改用 CLAUDE.md。想給 Claude 額外的指令和可執行命令，見技能（skills）。

安全提醒：command hook 以你的完整使用者權限執行 shell 命令，可以修改、刪除或訪問你的使用者賬號能訪問的任何檔案。新增到配置之前，先審查並測試所有 hook 命令。

Hooks 配置在哪裡

Hooks 定義在 JSON 設定檔案裡。hook 加在哪裡，決定了它的作用範圍：

在 Claude Code 裡輸入 /hooks，會開啟一個只讀的 hooks 瀏覽器，列出已配置的 hooks，並標明每個 hook 的來源，例如使用者設定、專案設定、本地設定、某個外掛或當前工作階段。想停用 hooks，在設定檔案裡寫 "disableAllHooks": true。Claude Code 執行時直接編輯設定檔案，檔案監視器通常會自動讀取 hook 的改動。

在互動工作階段裡，Claude Code 會先扣住所有設定檔案裡的 hooks，包括你自己的 ~/.claude/settings.json，直到你接受該資料夾的工作區信任對話框，或者接受某個信任範圍覆蓋到它的上級目錄。

一條 hook 的結構

配置分三層巢狀：選一個要響應的 hook 事件，比如 PreToolUse 或 Stop；加一個 matcher 組來過濾觸發時機，比如“只對 Bash 工具”；再定義匹配時要執行的一個或多個 hook handler。每個事件名都是同一個 hooks 物件裡的鍵。下面是 Anthropic 指南里的第一個 hook，macOS 上的桌面通知：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

如果你的設定檔案裡已經有 hooks 鍵，把新事件作為已有事件鍵的同級項加進去，不要替換整個物件。

內層 hooks 陣列裡的每個物件是一個 hook handler。大多數 hook 用 "type": "command"，執行一條 shell 命令。另外還有四種型別："type": "http"、"type": "mcp_tool"、"type": "prompt" 和 "type": "agent"。Agent hook 是實驗性的，可能會變。handler 的常用欄位：

Matcher 怎麼寫

沒有 matcher 時，hook 在對應事件每次發生時都會觸發。matcher 欄位用來過濾觸發時機，怎麼求值取決於它包含哪些字元：

每種事件匹配的欄位不同：PreToolUse 和 PostToolUse 匹配工具名，SessionStart 匹配工作階段的啟動方式（startup、resume、clear、compact、fork），Notification 匹配通知型別。Matcher 區分大小寫。UserPromptSubmit、Stop 等少數事件不支援 matcher，每次發生都會觸發。

if 欄位比 matcher 更細，matcher 只在組的層面按工具名過濾。下面這個配置只在 Claude 用 git 命令時執行 hook，而不是所有 Bash 命令：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

這個過濾是盡力而為的，所以指南說，要強制執行硬性的允許或拒絕，請用權限系統，不要用 hook。

最常用的事件

事件觸發時，Claude Code 會並行執行匹配的 hooks。指南列出的事件遠不止這些；下表是本頁示例用到的，加上幾個常見的。

四個可以直接貼上的示例

每個都是 Anthropic 指南里現成可用的配置塊。Bash 示例用 jq 解析 JSON：macOS 上用 brew install jq 安裝，Debian 和 Ubuntu 上用 apt-get install jq，也可以看 jq 的下載頁。

Claude 需要輸入時收到通知

這個 hook 用 Notification 事件，Claude Code 在 Claude 等待輸入或權限時觸發它。macOS 的寫法在上一節裡；下面是 Linux 的，用 notify-send。加到 ~/.claude/settings.json：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

空的 matcher 對所有通知型別都觸發。只想在特定情況觸發，把它設成某個通知型別，例如 permission_prompt（Claude 需要你批准一次工具使用）或 idle_prompt（Claude 大約 60 秒前回答完，之後你一直沒有輸入）。macOS 上沒有通知時：osascript 透過內建的“指令碼編輯器”（Script Editor）應用發通知，如果指令碼編輯器沒有通知權限，命令會靜默失敗。Linux 上，notify-send 需要桌面通知常駐程式，無頭伺服器、SSH 工作階段和大多數容器都沒有。

編輯後自動格式化程式碼

這個 hook 用 PostToolUse 事件加 Edit|Write matcher，所以只在檔案編輯類工具之後執行。命令用 jq 取出被編輯的檔案路徑，再交給 Prettier。加到專案根目錄的 .claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

測試方法：讓 Claude 往一個 JavaScript 檔案里加一行帶單引號字串的程式碼，然後開啟檔案：用 Prettier 的預設設定，hook 會把它們改成雙引號。hook 成功時，Claude Code 不會在對話裡顯示任何東西，所以要看被編輯的檔案有沒有被重新格式化。Bash 命令也可能改寫檔案；想讓某個特定檔案不管怎麼變化都被重新格式化，改用 FileChanged hook。

攔截對受保護檔案的編輯

這個示例阻止 Claude 修改敏感檔案，比如 .env、package-lock.json，或者 .git/ 裡的任何東西。Claude 會收到說明編輯為什麼被攔截的反饋，從而調整做法。hook 呼叫一個指令碼，指令碼拿目標檔案路徑和一組受保護的模式比對，並用退出碼 2 攔截編輯。把指令碼存成 .claude/hooks/protect-files.sh：

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

hook 指令碼必須可執行，Claude Code 才能執行它。在 macOS 和 Linux 上：

chmod +x .claude/hooks/protect-files.sh

然後在 .claude/settings.json 里加一個 PreToolUse hook，在任何 Edit 或 Write 工具呼叫之前執行這個指令碼：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

測試方法：讓 Claude 往你的 .env 檔案里加一行註釋。Claude Code 會在編輯執行之前攔截它，並把指令碼的 Blocked: 訊息作為反饋交給 Claude。

壓縮之後重新注入上下文

Claude 的上下文視窗滿了以後，壓縮（compaction）會把對話總結一遍來騰出空間，這可能丟掉重要細節。用帶 compact matcher 的 SessionStart hook，在每次壓縮之後重新注入關鍵上下文。你的命令寫到 stdout 的純文字，Claude Code 會加進 Claude 的上下文。加到專案根目錄的 .claude/settings.json：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

可以把 echo 換成任何會產生動態輸出的命令，比如用 git log --oneline -5 顯示最近的提交。

退出碼，以及攔截是怎麼生效的

Hooks 透過 stdin、stdout、stderr 和退出碼與 Claude Code 通訊。事件觸發時，Claude Code 把和事件相關的資料以 JSON 傳給你指令碼的 stdin。對一條 Bash 命令，PreToolUse hook 收到的欄位包括 session_id、cwd、hook_event_name、tool_name 和 tool_input，其中 tool_input.command 是那條 shell 命令。下面這個指令碼攔截一條命令：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2                                               # exit 2 = block the action
fi

exit 0  # exit 0 = no decision; the normal permission flow applies

• 退出碼 0 表示成功。PreToolUse hook 退出碼 0 時，這次工具呼叫仍然走正常的權限流程，因為退出碼 0 並不等於批准。對 UserPromptSubmit、UserPromptExpansion、SessionStart 和 PostModelSwitch hooks，Claude Code 會把純文字 stdout 加進 Claude 的上下文。對其他大多數事件，stdout 寫進除錯日誌，不會顯示在對話記錄裡。
• 退出碼 2 在可以攔截的事件上阻止操作。把原因寫到 stderr：隨攔截一起給出的訊息就是 hook 的 stderr。取決於事件，Claude 會把它當作反饋來調整，或者使用者能看到它，或者根本不顯示訊息。有些事件不能攔截：對 SessionStart 等，退出碼 2 只把 stderr 顯示給使用者，執行繼續。
• 其他任何退出碼是非阻塞錯誤：操作照常進行，但失敗即攔截的 hook 除外，例如把 onFailure 設為 "block" 的 hook。在 PreToolUse 等事件上，你會在對話記錄裡看到一條 <hook name> hook error 提示。

退出碼為 0 的 hook，Claude 永遠看不到它的 stderr。想從 PostToolUse hook 向 Claude 傳一條警告，改用退出碼 2，這樣即使工具已經執行過，Claude 也能看到 stderr。PostToolUse hook 無法撤銷已經發生的動作，因為工具已經執行了。

退出碼只能讓你攔截或保持沉默。想要更細的控制，退出碼用 0，並往 stdout 列印一個 JSON 物件。每個 hook 只選一種方式：退出碼 2 加 stderr 訊息來攔截，或者退出碼 0 加 JSON 來做結構化控制。例如，PreToolUse hook 可以拒絕一次工具呼叫並告訴 Claude 原因：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

返回 "deny" 時，Claude Code 取消這次工具呼叫，並把 permissionDecisionReason 反饋給 Claude。返回 permissionDecision: "deny" 的 hook，即使在 bypassPermissions 模式下或帶 --dangerously-skip-permissions 時，也會攔截工具。多個 hook 匹配同一個事件時，每個 hook 的命令都會執行完，Claude Code 才合併結果，所以某個 hook 返回 deny 並不會阻止同級的其他 hook 執行。

怎麼除錯 hook

• 執行 /hooks，確認 hook 出現在正確的事件下面。
• 把一段示例 JSON 透過管道餵給指令碼來測試，再檢查退出碼（命令見下方）。
• 按 Ctrl+O 開啟對話記錄檢視，找 hook 的結果。成功時什麼都看不到，除非 hook 的 JSON 帶出了什麼內容。阻塞錯誤會顯示隨攔截給出的訊息。非阻塞錯誤會顯示一條 <hook name> hook error 提示和一句簡短說明。
• 要看完整的執行細節，包括 hook 的退出碼、stdout 和 stderr，讀除錯日誌。用 claude --debug-file /tmp/claude.log 啟動 Claude Code，把日誌寫到一個已知路徑，再在另一個終端裡 tail -f /tmp/claude.log。如果啟動時沒加這個引數，在工作階段中執行 /debug 開啟日誌並找到日誌路徑。

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?  # Check the exit code

claude --debug-file /tmp/claude.log
tail -f /tmp/claude.log

常見問題排查

stop_hook_active 的檢查寫法如下：

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

常見問題

來源

• Claude Code：Automate actions with hooks（第一個 hook、示例、matcher、排錯，2026 年 10 月 30 日核對）
• Claude Code：Hooks reference（hook 位置、handler 欄位、退出碼、除錯、安全注意事項，2026 年 10 月 30 日核對）