Claude Code Hooks

Claude Code Hooks sindbenutzerdefinierte Shell-Befehle, die automatisch an bestimmten Knotenpunkten im Lebenszyklus von Claude Code ausgeführt werden.

Mit Hooks können Sie eine präzise Kontrolle über das Verhalten von Claude Code erreichen und sicherstellen, dass bestimmte Vorgänge (wie Codeformatierung, Protokollierung)definitiv ausgelöst werden, anstatt sich darauf zu verlassen, dass das große Modell autonom entscheidet, ob es sie ausführt.

Typische Anwendungsszenarien von Hooks

Hooks können Ihnen helfen, viele praktische Funktionen umzusetzen. Häufige Szenarien sind:

  • Nachrichtenbenachrichtigung: Automatisch Desktop-/E-Mail-Erinnerungen senden, wenn Claude Code auf Eingaben wartet oder Berechtigungen benötigt
  • Auto-Formatierung: Nach der Bearbeitung.tsDateien, automatisch ausgeführtprettier, nach dem Ändern.goDateien, ausführengofmt
  • Betriebsprotokolle: Alle von Claude ausgeführten Befehle für Compliance-Audits oder Debugging/Fehlerbehebung aufzeichnen
  • Validierung der Codestandards: Wenn der von Claude generierte Code nicht den Projektstandards entspricht (z. B. Namensregeln), automatisch Feedback geben
  • Dateiberechtigungskontrolle: Verhindern, dass Claude Produktionsumgebungs-Konfigurationsdateien oder sensible Verzeichnisse ändert (wie z. B..env、.git)

Im Vergleich zur Einschränkung von Claudes Verhalten durch Prompts sind Hooksharte Regeln auf Anwendungsebene, die zwangsweise durchgesetzt werden, solange das entsprechende Ereignis ausgelöst wird, und bieten höhere Stabilität und Zuverlässigkeit.

Wichtiger Sicherheitshinweis

Wenn Hooks ausgeführt werden, verwenden siedirekt die Anmeldeinformationen der aktuellen Systemumgebung(wie Umgebungsvariablen, Benutzerberechtigungen), was bestimmte Sicherheitsrisiken birgt:

  • Bösartiger Hook-Code kann Ihre sensiblen Daten preisgeben (wie API-Schlüssel, Projektquellcode)
  • Fehlerhafte Hook-Befehle können versehentliches Löschen von Dateien oder Systemanomalien verursachen

Erforderliche Sicherheitsmaßnahmen:

  1. Bevor du Hooks registrierst, stelle sicher, dass du die Logik und Berechtigungen der Befehle Zeile für Zeile überprüfst
  2. Vermeide die Ausführung von Skripten unbekannter Herkunft in Hooks
  3. Für detaillierte Sicherheits-Best-Practices siehe die offizielle Dokumentation, AbschnittSicherheitsvorkehrungen

Beschreibung der Hook-Ereignistypen

Claude Code verfügt über mehrere integrierte Lebenszyklusereignisse. Du kannst Hook-Befehle an verschiedene Ereignisse binden. Jedes Ereignis übergibt andere Kontextdaten und beeinflusst Claudes Verhalten auf unterschiedliche Weise.

Ereignisname Auslösezeitpunkt Kernfunktion
PreToolUse Tool-AufrufVor Kann die Tool-Ausführung abfangen (z. B. die Änderung sensibler Dateien verhindern) und Claude Feedback-Vorschläge geben
PermissionRequest Wenn ein Dialog für eine Berechtigungsanfrage erscheint Berechtigungsanfragen automatisch genehmigen oder ablehnen
PostToolUse Tool-AufrufNach Abschluss Nachgelagerte Operationen ausführen (z. B. Code formatieren, Protokolleinträge aufzeichnen)
UserPromptSubmit Nachdem der Benutzer einen Prompt übermittelt hat, bevor Claude ihn verarbeitet Benutzereingaben vorverarbeiten (z. B. Kontextinformationen ergänzen)
Notification Wenn Claude Benachrichtigungen sendet Benachrichtigungsmethoden anpassen (z. B. Desktop-Pop-ups, SMS-Benachrichtigungen)
Stop Wenn Claude eine Antwort abgeschlossen hat Abschlussarbeiten ausführen (z. B. temporäre Dateien bereinigen)
SubagentStop Wenn eine Subagent-Aufgabe abgeschlossen ist Die Ausführungsergebnisse des Subagenten verarbeiten
PreCompact Wenn eine Kontextkomprimierung kurz bevorsteht Komprimierungsregeln anpassen
SessionStart Beim Starten einer neuen Sitzung oder Fortsetzen einer alten Sitzung Sitzungsumgebung initialisieren (z. B. Projektkonfiguration laden)
SessionEnd Wenn die Sitzung endet Sitzungsdaten speichern, Umgebung bereinigen

Schnellstart: Befehlsprotokollierung implementieren

Im Folgenden führen wir Sie Schritt für Schritt durch die Konfiguration und Verwendung von Hooks, wobei wirdas Aufzeichnen aller von Claude ausgeführten Bash-Befehleals Beispiel verwenden.

Voraussetzungen

InstallationjqTool (zum Parsen von JSON-Daten über die Befehlszeile):

Schritt 1: Die Hook-Konfigurationsoberfläche öffnen

Geben Sie in der interaktiven Oberfläche von Claude Code den Slash-Befehl ein/hooks, drücken Sie die Eingabetaste und wählen Sie dann das zu bindende Ereignis aus – hier wählen wirPreToolUse(wird vor Tool-Aufrufen ausgelöst, geeignet zum Protokollieren von Befehlen).

Schritt 2: Einen Ereignis-Matcher hinzufügen

Die Rolle des Matchers besteht darin,die Auslösebedingungen des Hooks einzuschränken, sodass der Hook-Befehl nur ausgeführt wird, wenn das angegebene Tool aufgerufen wird.

  1. Auswählen+ Add new matcher…
  2. Geben Sie ein passendes Schlüsselwort einBash, was bedeutet, dass der Hook nur ausgelöst wird, wenn Claude das Bash-Tool aufruft.

    Tipp: Eingeben*kannalle Toolsabgleichen, wodurch ein globaler Hook ermöglicht wird.

Schritt 3: Einen Hook-Befehl hinzufügen

Auswählen+ Add new hook…, geben Sie den folgenden Befehl ein (Funktion: Befehlsinhalt und Beschreibung extrahieren, in eine Protokolldatei schreiben):

jq -r '"\(.tool_input.command) - \(.tool_input.description // "无描述信息")"' >> ~/.claude/bash-command-log.txt

Befehlsbeschreibung:

  • jq -r ...: Den Befehl aus JSON extrahieren (command) und die Beschreibung (description), "keine Beschreibungsinformationen" anzeigen, wenn keine Beschreibung vorhanden ist.
  • >> ~/.claude/...: Den Inhalt an die Protokolldatei im Home-Verzeichnis des Benutzers anhängen.

Schritt 4: Konfigurationsspeicherort auswählen

Der Konfigurationsspeicherort bestimmt den Geltungsbereich des Hooks:

  • Benutzereinstellungen: In benutzerspezifischer Konfiguration speichern (~/.claude/settings.json),für alle Projekte wirksam
  • Projekteinstellungen: In der Konfiguration des aktuellen Projekts speichern (.claude/settings.local.json),nur für das aktuelle Projekt wirksam

Hier wählen wirUser settings, um die globale Befehlsprotokollierung zu aktivieren. Nach der Auswahl drückenEscTaste, um die Konfigurationsoberfläche zu verlassen, und der Hook ist registriert.

Schritt 5: Hook-Konfiguration überprüfen

  1. Erneut eingeben/hooksBefehl, um die konfigurierte Hook-Liste anzuzeigen
  2. oder öffnen Sie direkt die Konfigurationsdatei~/.claude/settings.json, und Sie sehen die folgende Konfiguration:
    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"无描述信息\")\"' >> ~/.claude/bash-command-log.txt"
              }
            ]
          }
        ]
      }
    }

Schritt 6: Hook-Effekt testen

  1. Geben Sie einen Befehl in Claude Code ein:帮我执行 ls 命令
  2. Zeigen Sie nach der Ausführung die Protokolldatei im Terminal an:
    cat ~/.claude/bash-command-log.txt
  3. Wenn der folgende Inhalt im Protokoll erscheint, wurde der Hook erfolgreich konfiguriert:
    ls - Lists files and directories

Praktische Hook-Beispiele

Im Folgenden finden Sie mehrere häufig verwendete Hook-Konfigurationen. Sie können sie direkt kopieren oder nach Bedarf ändern.

📌 Vollständigen Beispielcode finden Sie im offiziellen Repository:bash-Befehl-Validator-Beispiel

Beispiel 1: TypeScript-Dateien automatisch formatieren

Funktion: Nach dem Bearbeiten/Schreiben.tsvon Dateien, automatisch verwendenprettierum den Code zu formatieren

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|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; }"
          }
        ]
      }
    ]
  }
}

Beispiel 2: Markdown-Dateiformatierung automatisch korrigieren

Funktion: automatisch Sprach-Tags zu Codeblöcken ohne solche hinzufügen und überflüssige Leerzeilen bereinigen

Schritt 1: Hook-Konfiguration hinzufügen

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
          }
        ]
      }
    ]
  }
}

Zweiter Schritt: Das Formatierungsskript erstellen

Im Projektverzeichnis eine neue Datei erstellen.claude/hooks/markdown_formatter.py, dann den folgenden Code einfügen:

Beispiele

#!/usr/bin/env python3
"""
Markdown-Formatierungswerkzeug: automatisch Sprach-Tags zu Codeblöcken hinzufügen, überflüssige Leerzeilen bereinigen
"""

import json
import sys
import re
import os

def detect_language(code):
    """Programmiersprache automatisch anhand des Codeinhalts erkennen"""
    code = code.strip()
    # JSON erkennen
    if re.search(r'^\s*[{\[]', code):
        try:
            json.loads(code)
            return 'json'
        except:
            pass
    # Python erkennen
    if re.search(r'^\s*def\s+\w+\s*\(', code, re.M) or re.search(r'^\s*(import|from)\s+\w+', code, re.M):
        return 'python'
    # JavaScript/TypeScript erkennen
    if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', code) or re.search(r'=>|console\.(log|error)', code):
        return 'javascript'
    # Bash erkennen
    if re.search(r'^#!.*\b(bash|sh)\b', code, re.M) or re.search(r'\b(if|then|fi|for|in|do|done)\b', code):
        return 'bash'
    # Standard-Textformat
    return 'text'

def format_markdown(content):
    """Markdown-Inhalt formatieren"""
    # Sprache zu nicht getaggten Codeblöcken hinzufügen
    fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
    def add_lang(match):
        indent, info, body, closing = match.groups()
        if not info.strip():
            lang = detect_language(body)
            return f"{indent}```{lang}\n{body}{closing}\n"
        return match.group(0)
    content = re.sub(fence_pattern, add_lang, content)
    # Überflüssige Leerzeilen entfernen (nur Inhalt außerhalb von Codeblöcken)
    content = re.sub(r'\n{3,}', '\n\n', content)
    return content.rstrip() + '\n'

if __name__ == "__main__":
    try:
        # Von Claude übergebene JSON-Daten lesen
        input_data = json.load(sys.stdin)
        file_path = input_data.get('tool_input', {}).get('file_path', '')
        # Nur .md/.mdx-Dateien verarbeiten
        if not file_path.endswith(('.md', '.mdx')):
            sys.exit(0)
        # Datei lesen und formatieren
        if os.path.exists(file_path):
            with open(file_path, 'r', encoding='utf-8') as f:
                content = f.read()
            formatted_content = format_markdown(content)
            # Nur schreiben, wenn sich content ändert
            if formatted_content != content:
                with open(file_path, 'w', encoding='utf-8') as f:
                    f.write(formatted_content)
                print(f"Formatierte Markdown-Datei: {file_path}")
    except Exception as e:
        print(f"Formatierung fehlgeschlagen: {e}", file=sys.stderr)
        sys.exit(1)

Dritter Schritt: Dem Skript Ausführungsberechtigung erteilen

chmod +x .claude/hooks/markdown_formatter.py

Beispiel 3: Desktop-Benachrichtigungen senden, wenn Claude auf Eingabe wartet

Funktion: Wenn Claude Benutzereingaben benötigt, automatisch eine Desktop-Erinnerung anzeigen (funktioniert unter Linux/macOS)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "", // 匹配所有通知事件
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code 提示' '请你输入指令或确认权限'"
          }
        ]
      }
    ]
  }
}

Beispiel 4: Änderung sensibler Dateien verhindern

Funktion: Claude am Bearbeiten hindern.env、package-lock.jsonund andere sensible Dateien

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|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)\""
          }
        ]
      }
    ]
  }
}

Hinweis: Wenn das Skript einen Statuscode zurückgibt2, Claude Code fängt diesen Tool-Aufruf ab und verhindert dadurch die Dateiänderung.


Claude Code Hooks Referenzhandbuch

Pfad der Konfigurationsdatei

Konfigurationsebene Dateipfad Geltungsbereich
Benutzerebene ~/.claude/settings.json Alle Projekte
Projektebene .claude/settings.json Aktuelles Projekt
Lokale Projektebene (nicht committet) .claude/settings.local.json Aktuelles Projekt, nicht in der Versionskontrolle enthalten
Verwaltete Richtlinienebene Vom Administrator angegebener Pfad Einheitliche Unternehmens-/Team-Steuerung

Kernstruktur der Konfiguration

Hooks sind nachevent + matcherorganisiert und unterstützencommand(Shell-Befehle ausführen) undprompt(LLM für Entscheidungen aufrufen), zwei Typen.

{
  "hooks": {
    "【钩子事件名】": [
      {
        "matcher": "【工具匹配规则】", // 部分事件可省略
        "hooks": [
          {
            "type": "command/prompt",
            "command": "【Shell 命令】", // type=command 时必填
            "prompt": "【LLM 提示词】",  // type=prompt 时必填
            "timeout": 30 // 可选,超时时间(秒)
          }
        ]
      }
    ]
  }
}

Matcher-Regeln (Nur auf Tool-Events anwendbar)

Matcher-Regeln Beispiel Beschreibung
Exakte Übereinstimmung Write Nur dieWritetool
Multi-Tool-Übereinstimmung Edit | Write ÜbereinstimmungEditoderWritetools
Präfix-Übereinstimmung Notebook.* Alle Tools abgleichen, die beginnen mitNotebookdem Präfix
Vollständig */ leerer String Alle Tools abgleichen

Spezielle Konfigurationstipps

Szenario Konfigurationsmethode Beispiel
Projektinternes Skript referenzieren Umgebungsvariablen verwenden$CLAUDE_PROJECT_DIR "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
Plugin-Hooks Im Plugin konfigurierthooks/hooks.json, mit${CLAUDE_PLUGIN_ROOT}um auf Plugin-Dateien zu verweisen "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
Hooks auf Komponentenebene (Skill/Agent) Im Frontmatter der Komponente definiert, Geltungsbereich auf den Lebenszyklus der Komponente beschränkt Siehe untenErweiterungskonfigurationTabelle

Erweiterte Konfiguration (Skill/Agent/Slash-Befehle)

Die Erweiterungskonfiguration ermöglicht es, Hooks direkt in die Definition eines Skills, Agents oder benutzerdefinierten Slash-Befehls einzubetten. Diese Hooks werden nur wirksam, wenn die entsprechende Komponente aktiviert und ausgeführt wird, und werden nach Abschluss der Ausführung der Komponente automatisch bereinigt, ohne die globale Sitzung zu beeinträchtigen.

Unterstützte Hook-Ereignisse

Unterstützt nurPreToolUse、PostToolUse、Stopdrei Ereignistypen, mit derselben Funktionalität wie globale Hooks, aber der Geltungsbereich ist auf den Lebenszyklus des aktuellen Skills/Slash-Befehls beschränkt.

Exklusive Konfigurationsoption

  • once: true(optional): wenn gesetzt auftrue, läuft dieser Hook nur einmal in der gesamten Sitzung und wird nach der ersten erfolgreichen Ausführung automatisch entfernt, um eine wiederholte Auslösung zu vermeiden.

Vollständiges Konfigurationsbeispiel

---
# Skill/斜杠命令的基础信息
name: secure-operations
description: 执行Shell命令前先做安全校验的工具
# Hooks 配置段
hooks:
  PreToolUse:
    # 匹配器:仅拦截Bash工具调用
    - matcher: "Bash"
      hooks:
        - type: "command"
          # 要执行的安全校验脚本
          command: "./scripts/security-check.sh"
          # 会话内仅执行一次
          once: true
          # 超时时间(秒),避免脚本卡死
          timeout: 15
---

Hooks-Konfiguration im Agent

Unterstützte Hook-Ereignisse

Unterstützt ebenfalls nurPreToolUse、PostToolUse、StopDrei Ereignistypen, die nur auf den Lebenszyklus der Aufgabenausführung dieses Sub-Agenten beschränkt sind.

Spezifische Konfigurationselemente

Keine zusätzlichen exklusiven Konfigurationselemente, nicht unterstütztonce: true(Hooks werden jedes Mal ausgelöst, wenn der Agent eine Aufgabe ausführt).

Vollständiges Konfigurationsbeispiel

---
# Agent 的基础信息
name: code-reviewer
description: 自动审查代码修改并运行代码检查的子代理
# Hooks 配置段
hooks:
  PostToolUse:
    # 匹配器:拦截Edit(编辑)或Write(写入)工具
    - matcher: "Edit|Write"
      hooks:
        - type: "command"
          # 代码检查脚本,执行lint校验
          command: "./scripts/run-linter.sh"
          # 超时时间(秒)
          timeout: 30
---

Notizen:

  1. Die Matcher-Regeln für Hooks auf Komponentenebene sind genau dieselben wie für globale Hooks: exakte Übereinstimmung wird unterstützt (z. B.,"Write"), Multi-Tool-Übereinstimmung (z. B.,"Edit|Write"), Wildcard-Übereinstimmung ("*"), und die Übereinstimmung ist case-sensitive;
  2. Hooks auf Komponentenebene und globale Hooks werden parallel ausgeführt: Wenn sowohl globale als auch Hooks auf Komponentenebene für dasselbe Ereignis konfiguriert sind, werden beide Hook-Typen beim Auslösen zusammen ausgeführt, ohne miteinander in Konflikt zu geraten;
  3. Anforderungen an das Konfigurationsformat: Hooks auf Komponentenebene müssen im Frontmatter (---umschlossenen Bereich) geschrieben werden, unter Befolgung der YAML-Syntax; Einrückungsfehler machen die Konfiguration ungültig;
  4. Empfehlungen für Skriptpfade: relative Pfade bevorzugen (z. B.,./scripts/xxx.sh), oder verwenden Sie den$CLAUDE_PROJECT_DIRUmgebungsvariable zur Angabe eines absoluten Pfads, damit die Komponente das Skript in jedem Verzeichnis finden kann.

Hook-Ereignisse -- Tool-Ereignisse (Matcher unterstützt)

Ereignisname Auslösezeitpunkt Gängige Matcher Kernzweck
PreToolUse Tool-Aufrufvor Bash/Edit/Write/Read Tool-Ausführung abfangen, Eingabeparameter ändern, Berechtigungen automatisch genehmigen/ablehnen
PermissionRequest Wenn ein Dialog für eine Berechtigungsanfrage erscheint gleichPreToolUse Berechtigungsanfragen automatisch bearbeiten, ohne manuelle Benutzerbestätigung
PostToolUse Tool-AufrufNach Erfolg gleichPreToolUse Nachgelagerte Operationen ausführen (z. B. Codeformatierung, Protokollierung)
Notification Wenn Claude eine Benachrichtigung sendet permission_prompt/idle_prompt/auth_success Benachrichtigungsmethoden anpassen (z. B. Desktop-Popups, E-Mail-Benachrichtigungen)
PreCompact Vor der Durchführung der Kontextkomprimierung manual(Manueller Auslöser) /auto(Automatischer Auslöser) Komprimierungsregeln anpassen, wichtigen Kontext sichern

Hook-Ereignisse – Sitzungs-/Aufgabenereignisse (Kein Matcher)

Ereignisname Auslösezeitpunkt Kernzweck
UserPromptSubmit Nachdem der Benutzer einen Prompt übermittelt hat, bevor Claude ihn verarbeitet Prompt-Gültigkeit validieren, Kontextinformationen ergänzen
Stop Wenn der Haupt-Agent seine Antwort abschließt (nicht durch Benutzerunterbrechung ausgelöst) Intelligent bestimmen, ob die Aufgabenausführung fortgesetzt werden soll
SubagentStop Wenn die Aufgabe des Sub-Agenten abgeschlossen ist Teilaufgabenergebnisse bewerten, entscheiden, ob beendet werden soll
SessionStart Beim Starten/Fortsetzen einer Sitzung Umgebung initialisieren, Projektkonfiguration laden, persistente Umgebungsvariablen setzen
SessionEnd Wenn die Sitzung endet Temporäre Dateien bereinigen, Sitzungsprotokolle aufzeichnen, Arbeitszustand speichern

Hook-Typ-Vergleich

Claude Code unterstützt zwei Hook-Typen, um die Anforderungen verschiedener Szenarien zu erfüllen.

Merkmal commandTyp (Command-Hook) promptTyp (Prompt-Hook)
Ausführungsmethode Shell-Befehle/Skripte ausführen LLM aufrufen (Standardmodell Haiku) für intelligente Entscheidungsfindung
Entscheidungslogik Basierend auf Codelogik,deterministische Beurteilung Basierend auf Kontext,flexible semantische Beurteilung
Konfigurationsschwierigkeit Erfordert das Schreiben von Skripten, hohe Einstiegshürde Man muss nur Prompts schreiben, einfach und benutzerfreundlich
Antwortgeschwindigkeit Schnell (lokale Ausführung) Langsamer (erfordert API-Aufrufe)
Anwendbare Szenarien Feste Regeln wie Codeformatierung, Protokollierung, Abfangen von Berechtigungen Flexible Szenarien wie Bewertung der Aufgabenerfüllung, komplexe Intent-Beurteilung
Kernkonfiguration command + timeout prompt + timeout(Kann referenzieren$ARGUMENTSPlatzhalter)

Eingabe und Ausgabe -- Hook-Eingabe (JSON über stdin übergeben)

Alle Hooks erhalten gemeinsame Felder, und einige Ereignisse enthalten spezifische Felder.

Feldtyp Gemeinsames Feld Beschreibung
Basisinformationen session_id Eindeutige Sitzungskennung
transcript_path Dateipfad des Gesprächsverlaufs
cwd Aktuelles Arbeitsverzeichnis, wenn der Hook ausgeführt wird
permission_mode Aktueller Berechtigungsmodus (default/plan/acceptEdits usw.)
hook_event_name Name des aktuell ausgelösten Hook-Ereignisses

Beispiele für ereignisspezifische Felder für jedes Ereignis

Ereignisname Spezifische Felder Beispiel
PreToolUse tool_name/tool_input {"tool_name":"Write","tool_input":{"file_path":"/test.txt"}}
UserPromptSubmit prompt {"prompt":"帮我写一个排序函数"}
SessionEnd reason {"reason":"clear/logout/other"}

Hook-Ausgabe (Zwei Methoden)

Methode 1: Exit-Code (einfache Szenarien)

Ausführungsstatus über den Exit-Code übergeben,stdout/stderrWird verwendet, um Feedback-Informationen bereitzustellen.

Exit-Code Bedeutung Verhaltensbeschreibung
0 Ausführung erfolgreich stdoutKann JSON für erweiterte Steuerung zurückgeben; einige Ereignisse (z. B.,UserPromptSubmit) werden hinzufügenstdoutzum Kontext
2 Die Operation blockieren Nur verwendenstderrals die Fehlermeldung, die an Claude zurückgemeldet wird,wodurch das aktuelle Ereignis an der weiteren Ausführung gehindert wird
Andere Werte ungleich null Nicht blockierender Fehler stderrWird nur im ausführlichen Modus angezeigt (ctrl+o), wirkt sich nicht auf die Event-Ausführung aus

Verhalten von Exit-Code 2 in jedem Event

Ereignisname Verhalten bei Auslösung
PreToolUse Den Tool-Aufruf blockieren und an Claude ausgebenstderr
UserPromptSubmit Prompt-Verarbeitung blockieren, Benutzereingabe löschen
Stop Claude am Stoppen hindern, die Fortsetzung der Arbeit erzwingen
PostToolUse/Notification Nur anzeigenstderr, wirkt sich nicht auf abgeschlossene Vorgänge aus

Methode 2: JSON-Ausgabe (erweiterte Szenarien)

Wenn der Exit-Code0, können SiestdoutJSON zurückgeben, um eine feingranulare Steuerung zu erreichen. Die Kernfelder sind wie folgt:

Allgemeine JSON-Felder Zweck
continue: true/false Ob das Ereignis weiter ausgeführt werden darf (falsehat Vorrang vor anderen Regeln)
stopReason continue=falseGrund, der dem Benutzer angezeigt wird, wenn
systemMessage Warnmeldung, die dem Benutzer angezeigt wird

Beispiele für ereignisspezifische JSON-Felder

Ereignisname Spezifische Felder Beispiel
PreToolUse permissionDecision(allow/deny/ask) {"hookSpecificOutput":{"permissionDecision":"allow","updatedInput":{"file_path":"/new.txt"}}}
UserPromptSubmit decision: block/undefined {"decision":"block","reason":"提示包含敏感信息"}
PostToolUse additionalContext {"hookSpecificOutput":{"additionalContext":"文件已格式化完成"}}

Hooks-Konfiguration für MCP-Tools

MCP-Tools können nahtlos in Hooks integriert und über spezifische Namensregeln abgeglichen werden.

Benennungsregeln für MCP-Tools

mcp__<服务器名>__<工具名>

Beispiel:mcp__github__search_repositories、mcp__filesystem__read_file

Beispiele für Übereinstimmungen

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*", // 匹配 memory 服务器的所有工具
        "hooks": [{"type": "command", "command": "echo '内存操作日志' >> log.txt"}]
      },
      {
        "matcher": "mcp__.*__write.*", // 匹配所有服务器的写操作工具
        "hooks": [{"type": "command", "command": "./validate-write.py"}]
      }
    ]
  }
}

Sicherheit und Debugging

Sicherheits-Best-Practices

Wichtige Sicherheitspunkte Konkrete Maßnahmen
Eingabevalidierung Streng validierentool_inputDateipfade und Befehlsparameter in, um Path Traversal zu verhindern (z. B.,../)
Variablenreferenzen Verwendung in Shell-Befehlen"$VAR"anstelle von$VAR, um Parameter-Injection zu vermeiden
Minimale Rechte Hook-Skripten sollten nur die notwendigen Berechtigungen gewährt werden; vermeiden Sie die Verwendung vonsudound andere risikoreiche Befehle
Sensible Dateien ausschließen Abfangen von Operationen auf.env、.gitund Operationen an Schlüsseldateien
Befehlsüberprüfung Bevor Sie einen Hook registrieren, führen Sie den Befehl manuell aus, um die Logik zu überprüfen und sicherzustellen, dass kein bösartiges Verhalten vorliegt.

Debugging-Tipps

Problemtyp Schritte zur Fehlerbehebung
Hook wird nicht wirksam 1. Führen Sie/hooksden Befehl aus, um zu prüfen, ob die Konfiguration registriert ist<br>2. Überprüfen Sie, ob die JSON-Syntax korrekt ist<br>3. Prüfen Sie, ob die Matcher-Regel mit dem Toolnamen übereinstimmt (Groß-/Kleinschreibung beachten)
Befehlsausführung fehlgeschlagen 1. Führen Sie den Hook-Befehl manuell aus, um zu bestätigen, dass er ordnungsgemäß ausgeführt wird<br>2. Prüfen Sie, ob das Skript über Ausführungsberechtigungen verfügt (chmod +x script.sh)<br>3. Verwenden Sie einen absoluten Pfad zum Aufrufen des Skripts, um Probleme mit Umgebungsvariablen zu vermeiden
Detaillierte Logs anzeigen Beim Starten von Claude Code hinzufügen--debugParameter zur Anzeige des gesamten Hook-Ausführungsprozesses

Referenzdokumentation: Für die vollständige Beschreibung der Hook-Funktion lesen Sie die offizielleHooks-Referenzdokumentation。

Weitere Erweiterungen