Claude Code hooks 是使用者定義的 shell 命令，在 Claude Code 生命週期的各個階段執行。Hooks 提供對 Claude Code 行為的確定性控制，確保某些動作總是會發生，而不是依賴 LLM 選擇執行它們。

有關 hooks 的參考文件，請參閱 Hooks 參考。

hooks 的範例使用案例包括：

  • 通知：自訂當 Claude Code 等待您的輸入或執行權限時如何通知您。
  • 自動格式化：在每次檔案編輯後對 .ts 檔案執行 prettier，對 .go 檔案執行 gofmt 等。
  • 記錄：追蹤和計算所有執行的命令，用於合規性或除錯。
  • 回饋：當 Claude Code 產生不符合您程式碼庫慣例的程式碼時提供自動回饋。
  • 自訂權限：阻止對生產檔案或敏感目錄的修改。

透過將這些規則編碼為 hooks 而不是提示指令，您將建議轉換為應用程式層級的程式碼，每次預期執行時都會執行。

您必須考慮新增 hooks 時的安全影響，因為 hooks 會在代理迴圈期間使用您當前環境的憑證自動執行。 例如，惡意的 hooks 程式碼可能會洩露您的資料。在註冊 hooks 之前，請務必檢查您的 hooks 實作。

有關完整的安全最佳實務，請參閱 hooks 參考文件中的安全考量。

​
Hook 事件概覽

Claude Code 提供幾個在工作流程不同階段執行的 hook 事件：

  • PreToolUse：在工具呼叫之前執行（可以阻止它們）
  • PostToolUse：在工具呼叫完成後執行
  • Notification：當 Claude Code 發送通知時執行
  • Stop：當 Claude Code 完成回應時執行
  • Subagent Stop：當子代理任務完成時執行

每個事件接收不同的資料，並可以以不同的方式控制 Claude 的行為。

​
快速開始

在這個快速開始中，您將新增一個記錄 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… 並輸入此命令：

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​
步驟 4：儲存您的設定

對於儲存位置，選擇 User settings，因為您要記錄到您的主目錄。這個 hook 將適用於所有專案，而不僅僅是您當前的專案。

然後按 Esc 直到您返回到 REPL。您的 hook 現在已註冊！

​
步驟 5：驗證您的 hook

再次執行 /hooks 或檢查 ~/.claude/settings.json 來查看您的設定：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​
步驟 6：測試您的 hook

要求 Claude 執行一個簡單的命令，如 ls，並檢查您的記錄檔案：

cat ~/.claude/bash-command-log.txt

您應該看到類似以下的條目：

ls - Lists files and directories

​
更多範例

有關完整的範例實作，請參閱我們公開程式碼庫中的 bash 命令驗證器範例。

​
程式碼格式化 Hook

在編輯後自動格式化 TypeScript 檔案：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

​
自訂通知 Hook

當 Claude 需要輸入時獲得桌面通知：

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

​
檔案保護 Hook

阻止對敏感檔案的編輯：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

​
了解更多

  • 有關 hooks 的參考文件，請參閱 Hooks 參考。
  • 有關全面的安全最佳實務和安全指南，請參閱 hooks 參考文件中的安全考量。
  • 有關疑難排解步驟和除錯技術，請參閱 hooks 參考文件中的除錯。