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:
- Bevor du Hooks registrierst, stelle sicher, dass du die Logik und Berechtigungen der Befehle Zeile für Zeile überprüfst
- Vermeide die Ausführung von Skripten unbekannter Herkunft in Hooks
- 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):
- macOS:
brew install jq - Linux:
sudo apt install jq/sudo yum install jq - Windows: Laden Siedas offizielle jq-Installationspaket herunter, oder installieren Sie es über WSL
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.
- Auswählen
+ Add new matcher… - Geben Sie ein passendes Schlüsselwort ein
Bash, 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
- Erneut eingeben
/hooksBefehl, um die konfigurierte Hook-Liste anzuzeigen - 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
- Geben Sie einen Befehl in Claude Code ein:
帮我执行 ls 命令 - Zeigen Sie nach der Ausführung die Protokolldatei im Terminal an:
cat ~/.claude/bash-command-log.txt
- 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
"""
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:
- 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; - 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;
- 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; - 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 |
Weitere ErweiterungenReferenzdokumentation: Für die vollständige Beschreibung der Hook-Funktion lesen Sie die offizielleHooks-Referenzdokumentation。