Hooks de Claude Code
Les hooks de Claude Code sont descommandes Shell définies par l'utilisateurqui s'exécutent automatiquement à des points spécifiques du cycle de vie de Claude Code.
Avec les hooks, vous pouvez obtenir un contrôle précis sur le comportement de Claude Code, en garantissant que certaines opérations (telles que le formatage du code, la journalisation)sont absolument déclenchées, plutôt que de compter sur le grand modèle pour décider de manière autonome s'il doit les exécuter.
Scénarios d'application typiques des hooks
Les hooks peuvent vous aider à implémenter de nombreuses fonctionnalités pratiques. Les scénarios courants incluent :
- Notification par message: Envoyer automatiquement des rappels sur le bureau/par e-mail lorsque Claude Code attend une entrée ou a besoin d'autorisations
- Formatage automatique: Après modification
.tsfichiers, exécution automatiqueprettier, après modification.gofichiers, exécutergofmt - Journaux d'opérations: Enregistrer toutes les commandes exécutées par Claude à des fins d'audit de conformité ou de débogage/dépannage
- Validation des normes de code: Si le code généré par Claude ne respecte pas les normes du projet (telles que les règles de nommage), fournir automatiquement un retour
- Contrôle des permissions de fichiers: Empêcher Claude de modifier les fichiers de configuration de l'environnement de production ou les répertoires sensibles (tels que
.env、.git)
Par rapport à la contrainte du comportement de Claude via des prompts, les hooks sontdes règles strictes au niveau de l'applicationqui sont appliquées de force dès que l'événement correspondant est déclenché, offrant une stabilité et une fiabilité supérieures.
Rappel important de sécurité
Lorsque les hooks s'exécutent, ilsutilisent directement les identifiants de l'environnement système actuel(tels que les variables d'environnement, les permissions utilisateur), ce qui présente certains risques de sécurité :
- Le code de hook malveillant peut divulguer vos données sensibles (telles que les clés API, le code source du projet)
- Des commandes de hook incorrectes peuvent entraîner une suppression accidentelle de fichiers ou des anomalies système
Actions de sécurité requises:
- Avant d'enregistrer des hooks, assurez-vous de vérifier la logique et les autorisations des commandes ligne par ligne
- Évitez d'exécuter des scripts d'origine inconnue dans les hooks
- Pour les meilleures pratiques de sécurité détaillées, reportez-vous auxPrécautions de sécurité de la documentation officielle
Description du type d'événement de hook
Claude Code dispose de plusieurs événements de cycle de vie intégrés. Vous pouvez lier des commandes de hook à différents événements. Chaque événement transmet des données de contexte différentes et affecte le comportement de Claude de différentes manières.
| Nom de l'événement | Moment du déclenchement | Fonction principale |
|---|---|---|
PreToolUse |
Appel d'outilAvant | Peut intercepter l'exécution d'outils (par exemple, empêcher la modification de fichiers sensibles) et fournir des suggestions de retour à Claude |
PermissionRequest |
Lorsqu'une boîte de dialogue de demande d'autorisation apparaît | Approuver ou refuser automatiquement les demandes d'autorisation |
PostToolUse |
Appel d'outilAprès achèvement | Effectuer des post-opérations (p. ex., formater le code, journaliser les enregistrements) |
UserPromptSubmit |
Après que l'utilisateur a soumis un prompt, avant que Claude ne le traite | Prétraiter l'entrée utilisateur (p. ex., compléter les informations de contexte) |
Notification |
Lorsque Claude envoie des notifications | Personnaliser les méthodes de notification (p. ex., pop-ups de bureau, alertes SMS) |
Stop |
Lorsque Claude termine une réponse | Effectuer le travail de finition (p. ex., nettoyer les fichiers temporaires) |
SubagentStop |
Lorsqu'une tâche d'un sous-agent se termine | Traiter les résultats d'exécution du sous-agent |
PreCompact |
Lorsqu'il est sur le point d'effectuer un compactage du contexte | Personnaliser les règles de compactage |
SessionStart |
Lors du démarrage d'une nouvelle session ou de la reprise d'une ancienne session | Initialiser l'environnement de session (par ex., charger la configuration du projet) |
SessionEnd |
Lorsque la session se termine | Enregistrer les données de session, nettoyer l'environnement |
Démarrage rapide : implémenter la journalisation des commandes
Ci-dessous, en utilisantl'enregistrement de toutes les commandes Bash exécutées par Claudecomme exemple, nous allons vous guider pas à pas dans la configuration et l'utilisation des hooks.
Prérequis
Installerjqoutil (pour analyser les données JSON depuis la ligne de commande) :
- macOS:
brew install jq - Linux:
sudo apt install jq/sudo yum install jq - Windows: Téléchargezle paquet d'installation officiel de jq, ou installez via WSL
Étape 1 : Ouvrir l'interface de configuration des hooks
Dans l'interface interactive de Claude Code, saisissez la commande slash/hooks, appuyez sur Entrée, puis sélectionnez l'événement à associer — ici nous choisissonsPreToolUse(déclenché avant les appels d'outils, adapté pour journaliser les commandes).
Étape 2 : Ajouter un matcher d'événement
Le rôle du matcher est delimiter les conditions de déclenchement du hook, en n'exécutant la commande du hook que lorsque l'outil spécifié est appelé.
- Sélection
+ Add new matcher… - Saisissez un mot-clé correspondant
Bash, ce qui signifie que le hook ne se déclenche que lorsque Claude appelle l'outil Bash.Astuce : Saisissez
*peut correspondre àtous les outils, ce qui active un hook global.
Étape 3 : Ajouter une commande de hook
Sélection+ Add new hook…, saisissez la commande suivante (fonction : extraire le contenu et la description de la commande, écrire dans un fichier journal) :
jq -r '"\(.tool_input.command) - \(.tool_input.description // "无描述信息")"' >> ~/.claude/bash-command-log.txt
Description de la commande :
jq -r ...: Extraire la commande depuis JSON (command) et la description (description), afficher "aucune information de description" lorsqu'il n'y a pas de description.>> ~/.claude/...: Ajouter le contenu au fichier journal dans le répertoire personnel de l'utilisateur.
Étape 4 : Choisir l'emplacement de stockage de la configuration
L'emplacement de sauvegarde de la configuration détermine la portée du hook :
- Paramètres utilisateur: Enregistrer dans la configuration au niveau utilisateur (
~/.claude/settings.json),valable pour tous les projets - Paramètres du projet: Enregistrer dans la configuration du projet actuel (
.claude/settings.local.json),valable uniquement pour le projet actuel
Ici, nous choisissonsUser settings, pour activer la journalisation globale des commandes. Après avoir sélectionné, appuyez sur laEscpour quitter l'interface de configuration, et le hook est enregistré.
Étape 5 : Vérifier la configuration du hook
- Saisissez à nouveau
/hookscommande pour afficher la liste des hooks configurés - ou ouvrez directement le fichier de configuration
~/.claude/settings.json, et vous verrez la configuration suivante :{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"无描述信息\")\"' >> ~/.claude/bash-command-log.txt" } ] } ] } }
Étape 6 : Tester l'effet du hook
- Saisissez une commande dans Claude Code :
帮我执行 ls 命令 - Après l'exécution, consultez le fichier journal dans le terminal :
cat ~/.claude/bash-command-log.txt
- Si le contenu suivant apparaît dans le journal, le hook est configuré avec succès :
ls - Lists files and directories
Exemples pratiques de hooks
Voici plusieurs configurations de hooks couramment utilisées. Vous pouvez les copier directement ou les modifier selon vos besoins.
📌 Pour obtenir l'exemple de code complet, consultez le dépôt officiel :exemple de validateur de commandes bash
Exemple 1 : Formater automatiquement les fichiers TypeScript
Fonction : Après édition/écriture.tsde fichiers, utiliser automatiquementprettierpour formater le code
{
"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; }"
}
]
}
]
}
}
Exemple 2 : corriger automatiquement le formatage des fichiers Markdown
Fonction : ajouter automatiquement des balises de langage aux blocs de code qui n'en ont pas et supprimer les lignes vides superflues
Étape 1 : ajouter la configuration du hook
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
}
]
}
]
}
}
Deuxième étape : créer le script de formatage
Dans le répertoire du projet, créez un nouveau fichier.claude/hooks/markdown_formatter.py, puis collez le code suivant :
Exemples
"""
Outil de formatage Markdown : ajouter automatiquement des balises de langage aux blocs de code, nettoyer les lignes vides superflues
"""
import json
import sys
import re
import os
def detect_language(code):
"""Détecter automatiquement le langage de programmation en fonction du contenu du code"""
code = code.strip()
# Détecter JSON
if re.search(r'^\s*[{\[]', code):
try:
json.loads(code)
return 'json'
except:
pass
# Détecter Python
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'
# Détecter JavaScript/TypeScript
if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', code) or re.search(r'=>|console\.(log|error)', code):
return 'javascript'
# Détecter Bash
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'
# Format de texte par défaut
return 'text'
def format_markdown(content):
"""Formate le contenu Markdown"""
# Ajouter un langage aux blocs de code non étiquetés
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)
# Nettoyer les lignes vides supplémentaires (uniquement le contenu en dehors des blocs de code)
content = re.sub(r'\n{3,}', '\n\n', content)
return content.rstrip() + '\n'
if __name__ == "__main__":
try:
# Lire les données JSON transmises par Claude
input_data = json.load(sys.stdin)
file_path = input_data.get('tool_input', {}).get('file_path', '')
# Traiter uniquement les fichiers .md/.mdx
if not file_path.endswith(('.md', '.mdx')):
sys.exit(0)
# Lire et formater le fichier
if os.path.exists(file_path):
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
formatted_content = format_markdown(content)
# Écrire uniquement lorsque le contenu change
if formatted_content != content:
with open(file_path, 'w', encoding='utf-8') as f:
f.write(formatted_content)
print(f"Fichier Markdown formaté : {file_path}")
except Exception as e:
print(f"Échec du formatage : {e}", file=sys.stderr)
sys.exit(1)
Troisième étape : Accorder la permission d'exécution au script
chmod +x .claude/hooks/markdown_formatter.py
Exemple 3 : Envoyer des notifications de bureau lorsque Claude attend une entrée
Fonctionnalité : Lorsque Claude a besoin d'une saisie utilisateur, afficher automatiquement un rappel de bureau (fonctionne sous Linux/macOS)
{
"hooks": {
"Notification": [
{
"matcher": "", // 匹配所有通知事件
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code 提示' '请你输入指令或确认权限'"
}
]
}
]
}
}
Exemple 4 : Empêcher la modification de fichiers sensibles
Fonctionnalité : Empêcher Claude de modifier.env、package-lock.jsonet d'autres fichiers sensibles
{
"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)\""
}
]
}
]
}
}
Remarque : Lorsque le script renvoie un code de statut2, Claude Code interceptera cet appel d'outil, empêchant ainsi la modification de fichier.
Manuel de référence des hooks de Claude Code
Chemin du fichier de configuration
| Niveau de configuration | Chemin du fichier | Portée |
|---|---|---|
| Niveau utilisateur | ~/.claude/settings.json |
Tous les projets |
| Niveau projet | .claude/settings.json |
Projet actuel |
| Niveau projet local (non commité) | .claude/settings.local.json |
Projet actuel, non inclus dans le contrôle de version |
| Niveau de politique gérée | Chemin spécifié par l'administrateur | Contrôle unifié entreprise/équipe |
Structure de configuration principale
Les hooks sont organisés parévénement + matcher, prenant en chargecommand(exécuter des commandes Shell) etprompt(appeler le LLM pour les décisions), deux types.
{
"hooks": {
"【钩子事件名】": [
{
"matcher": "【工具匹配规则】", // 部分事件可省略
"hooks": [
{
"type": "command/prompt",
"command": "【Shell 命令】", // type=command 时必填
"prompt": "【LLM 提示词】", // type=prompt 时必填
"timeout": 30 // 可选,超时时间(秒)
}
]
}
]
}
}
Règles de correspondance (applicables uniquement aux événements d’outils)
| Règle de correspondance | Exemple | Description |
|---|---|---|
| Correspondance exacte | Write |
Correspond uniquement àWritetool |
| Correspondance multi-outils | Edit | Write | CorrespondanceEditouWritetools |
| Correspondance de préfixe | Notebook.* |
Correspond à tous les outils commençant parNotebookle préfixe |
| Correspondance complète | */ chaîne vide |
Correspondre à tous les outils |
Conseils de configuration spéciaux
| Scénario | Méthode de configuration | Exemple |
|---|---|---|
| Référencer un script dans le projet | Utiliser des variables d'environnement$CLAUDE_PROJECT_DIR |
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh" |
| Hooks de plugin | Configuré à l'intérieur du pluginhooks/hooks.json, en utilisant${CLAUDE_PLUGIN_ROOT}pour référencer des fichiers de plugin |
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh" |
| Hooks au niveau du composant (Skill/Agent) | Défini dans le frontmatter du composant, portée limitée au cycle de vie du composant | Voir ci-dessousConfiguration de l'extensionTableau |
Configuration étendue (Skill/Agent/Commandes slash)
La configuration d'extension permet d'intégrer directement des Hooks dans la définition d'un Skill, d'un Agent ou d'une commande slash personnalisée. Ces Hooks ne prennent effet que lorsque le composant correspondant est activé et en cours d'exécution, et sont automatiquement nettoyés après la fin de l'exécution du composant, sans affecter la session globale.
Événements de hook pris en charge
Prend uniquement en chargePreToolUse、PostToolUse、Stoptrois types d'événements, avec les mêmes fonctionnalités que les Hooks globaux, mais la portée est limitée au cycle de vie du Skill ou de la commande slash en cours.
Option de configuration exclusive
once: true(facultatif) : lorsqu'elle est définie surtrue, ce Hook ne s'exécute qu'une seule fois dans toute la session, et est automatiquement supprimé après la première exécution réussie afin d'éviter un déclenchement répété.
Exemple complet de configuration
---
# Skill/斜杠命令的基础信息
name: secure-operations
description: 执行Shell命令前先做安全校验的工具
# Hooks 配置段
hooks:
PreToolUse:
# 匹配器:仅拦截Bash工具调用
- matcher: "Bash"
hooks:
- type: "command"
# 要执行的安全校验脚本
command: "./scripts/security-check.sh"
# 会话内仅执行一次
once: true
# 超时时间(秒),避免脚本卡死
timeout: 15
---
Configuration des Hooks dans l'Agent
Événements de hook pris en charge
Prend également uniquement en chargePreToolUse、PostToolUse、StopTrois types d'événements, limités uniquement au cycle de vie d'exécution des tâches de ce sous-Agent.
Éléments de configuration spécifiques
Aucun élément de configuration exclusif supplémentaire, non pris en chargeonce: true(Les Hooks sont déclenchés chaque fois que l'Agent exécute une tâche).
Exemple complet de configuration
---
# Agent 的基础信息
name: code-reviewer
description: 自动审查代码修改并运行代码检查的子代理
# Hooks 配置段
hooks:
PostToolUse:
# 匹配器:拦截Edit(编辑)或Write(写入)工具
- matcher: "Edit|Write"
hooks:
- type: "command"
# 代码检查脚本,执行lint校验
command: "./scripts/run-linter.sh"
# 超时时间(秒)
timeout: 30
---
Notes :
- Les règles de correspondance pour les Hooks au niveau des composants sont exactement les mêmes que pour les Hooks globaux : la correspondance exacte est prise en charge (par ex.,
"Write"), la correspondance multi-outils (par ex.,"Edit|Write"), la correspondance avec caractères génériques ("*"), et la correspondance est sensible à la casse ; - Les Hooks au niveau des composants et les Hooks globaux s'exécutent en parallèle : si des Hooks globaux et des Hooks au niveau des composants sont configurés pour le même événement, les deux types de Hooks s'exécuteront ensemble lorsqu'ils sont déclenchés, sans entrer en conflit l'un avec l'autre ;
- Exigences de format de configuration : les Hooks au niveau des composants doivent être écrits dans le frontmatter (
---région délimitée), en respectant la syntaxe YAML ; les erreurs d'indentation invalideront la configuration ; - Recommandations pour les chemins de scripts : privilégier les chemins relatifs (par ex.,
./scripts/xxx.sh), ou utilisez le$CLAUDE_PROJECT_DIRvariable d’environnement pour spécifier un chemin absolu, garantissant que le composant peut trouver le script dans n’importe quel répertoire.
Événements de hook -- Événements d’outil (Matcher pris en charge)
| Nom de l'événement | Moment du déclenchement | Matchers courants | Objectif principal |
|---|---|---|---|
PreToolUse |
Appel d’outilavant | Bash/Edit/Write/Read |
Intercepter l’exécution de l’outil, modifier les paramètres d’entrée, approuver/refuser automatiquement les permissions |
PermissionRequest |
Lorsqu'une boîte de dialogue de demande d'autorisation apparaît | identiquePreToolUse |
Gérer automatiquement les demandes de permission sans confirmation manuelle de l’utilisateur |
PostToolUse |
Appel d’outilAprès succès | identiquePreToolUse |
Exécuter des opérations postérieures (par ex., formatage du code, journalisation) |
Notification |
Lorsque Claude envoie une notification | permission_prompt/idle_prompt/auth_success |
Personnaliser les méthodes de notification (par ex., popups de bureau, alertes e-mail) |
PreCompact |
Avant d'effectuer la compression du contexte | manual(Déclenchement manuel) /auto(Déclenchement automatique) |
Personnaliser les règles de compression, sauvegarder le contexte important |
Événements de hook -- Événements de session/tâche (Sans Matcher)
| Nom de l'événement | Moment du déclenchement | Objectif principal |
|---|---|---|
UserPromptSubmit |
Après que l'utilisateur a soumis un prompt, avant que Claude ne le traite | Valider la légitimité de l'invite, compléter les informations de contexte |
Stop |
Lorsque l'Agent principal termine sa réponse (non déclenché par une interruption de l'utilisateur) | Déterminer intelligemment s'il faut continuer à exécuter la tâche |
SubagentStop |
Lorsque la tâche du sous-Agent se termine | Évaluer les résultats de la sous-tâche, décider s'il faut terminer |
SessionStart |
Lors du démarrage/de la reprise d'une session | Initialiser l'environnement, charger la configuration du projet, définir les variables d'environnement persistantes |
SessionEnd |
Lorsque la session se termine | Nettoyer les fichiers temporaires, enregistrer les journaux de session, sauvegarder l'état de travail |
Comparaison des types de hooks
Claude Code prend en charge deux types de hooks pour répondre aux besoins de différents scénarios.
| Fonctionnalité | commandType (hook de commande) |
promptType (hook de prompt) |
|---|---|---|
| Méthode d'exécution | Exécuter des commandes/scripts Shell | Appeler LLM (modèle Haiku par défaut) pour une prise de décision intelligente |
| Logique de décision | Basé sur la logique du code,jugement déterministe | Basé sur le contexte,jugement sémantique flexible |
| Difficulté de configuration | Nécessite d'écrire des scripts, barrière d'entrée élevée | Il suffit d'écrire des prompts, simple et facile à utiliser |
| Vitesse de réponse | Rapide (exécution locale) | Plus lent (nécessite des appels API) |
| Scénarios applicables | Règles fixes telles que le formatage du code, la journalisation, l'interception des permissions | Scénarios flexibles tels que l'évaluation de l'achèvement des tâches, le jugement d'intentions complexes |
| Configuration principale | command + timeout |
prompt + timeout(Peut référencer$ARGUMENTSespaces réservés) |
Entrée et sortie -- Entrée de hook (JSON transmis via stdin)
Tous les hooks reçoivent des champs communs, et certains événements incluent des champs spécifiques.
| Type de champ | Champ commun | Description |
|---|---|---|
| Informations de base | session_id |
Identifiant unique de session |
transcript_path |
Chemin du fichier d'historique de conversation | |
cwd |
Répertoire de travail actuel lors de l'exécution du hook | |
permission_mode |
Mode d'autorisation actuel (default/plan/acceptEdits, etc.) | |
hook_event_name |
Nom de l'événement de hook actuellement déclenché |
Exemples de champs spécifiques à chaque événement
| Nom de l'événement | Champs spécifiques | Exemple |
|---|---|---|
PreToolUse |
tool_name/tool_input |
{"tool_name":"Write","tool_input":{"file_path":"/test.txt"}} |
UserPromptSubmit |
prompt |
{"prompt":"帮我写一个排序函数"} |
SessionEnd |
reason |
{"reason":"clear/logout/other"} |
Sortie du hook (deux méthodes)
Méthode 1 : code de sortie (scénarios simples)
Transmettre l'état d'exécution via le code de sortie,stdout/stderrUtilisé pour fournir des informations de retour.
| Code de sortie | Signification | Description du comportement |
|---|---|---|
0 |
Exécution réussie | stdoutPeut renvoyer du JSON pour un contrôle avancé ; certains événements (par ex.,UserPromptSubmit) ajouterontstdoutau contexte |
2 |
Bloquer l'opération | Utiliser uniquementstderrcomme message d'erreur renvoyé à Claude,empêchant l'événement actuel de continuer son exécution |
| Autres valeurs non nulles | Erreur non bloquante | stderrAffiché uniquement en mode verbeux (ctrl+o), n'affecte pas l'exécution de l'événement |
Comportement du code de sortie 2 dans chaque événement
| Nom de l'événement | Comportement déclenché |
|---|---|
PreToolUse |
Bloquer l'appel d'outil et l'afficher à Claudestderr |
UserPromptSubmit |
Bloquer le traitement de l'invite, effacer la saisie utilisateur |
Stop |
Empêcher Claude de s'arrêter, forcer la poursuite du travail |
PostToolUse/Notification |
Afficher uniquementstderr, n'affecte pas les opérations terminées |
Méthode 2 : sortie JSON (scénarios avancés)
Lorsque le code de sortie est0, vous pouvezstdoutrenvoyer du JSON pour obtenir un contrôle précis. Les champs principaux sont les suivants :
| Champs JSON courants | Objectif |
|---|---|
continue: true/false |
S'il faut autoriser l'événement à continuer à s'exécuter (falsea priorité sur les autres règles) |
stopReason |
continue=falseRaison affichée à l'utilisateur lorsque |
systemMessage |
Message d'avertissement affiché à l'utilisateur |
Exemples de champs JSON spécifiques à l'événement
| Nom de l'événement | Champs spécifiques | Exemple |
|---|---|---|
PreToolUse |
permissionDecision(allow/deny/ask) |
{"hookSpecificOutput":{"permissionDecision":"allow","updatedInput":{"file_path":"/new.txt"}}} |
UserPromptSubmit |
decision: block/undefined |
{"decision":"block","reason":"提示包含敏感信息"} |
PostToolUse |
additionalContext |
{"hookSpecificOutput":{"additionalContext":"文件已格式化完成"}} |
Configuration des Hooks pour les outils MCP
Les outils MCP peuvent être intégrés de manière transparente aux Hooks et mis en correspondance via des règles de nommage spécifiques.
Règles de nommage des outils MCP
mcp__<服务器名>__<工具名>
Exemple :mcp__github__search_repositories、mcp__filesystem__read_file
Exemples de correspondance
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__memory__.*", // 匹配 memory 服务器的所有工具
"hooks": [{"type": "command", "command": "echo '内存操作日志' >> log.txt"}]
},
{
"matcher": "mcp__.*__write.*", // 匹配所有服务器的写操作工具
"hooks": [{"type": "command", "command": "./validate-write.py"}]
}
]
}
}Sécurité et débogage
Bonnes pratiques de sécurité
| Points clés de sécurité | Actions concrètes |
|---|---|
| Validation des entrées | Valider strictementtool_inputles chemins de fichiers et les paramètres de commande dans, pour prévenir la traversée de chemin (par ex.,../) |
| références de variables | Utilisation dans les commandes Shell"$VAR"au lieu de$VAR, pour éviter l’injection de paramètres |
| Moindre privilège | Les scripts de hook ne doivent se voir accorder que les permissions nécessaires ; évitez d’utilisersudoet d’autres commandes à haut risque |
| Exclure les fichiers sensibles | Intercepter les opérations sur.env、.gitet les opérations sur les fichiers clés |
| Examen des commandes | Avant d'enregistrer un hook, exécutez manuellement la commande pour vérifier la logique et confirmer l'absence de comportement malveillant. |
Conseils de débogage
| Type de problème | Étapes de dépannage |
|---|---|
| Le hook ne prend pas effet | 1. Exécutez/hookscommande pour vérifier si la configuration est enregistrée<br>2. Vérifiez que la syntaxe JSON est correcte<br>3. Vérifiez si la règle du matcher correspond au nom de l'outil (sensible à la casse) |
| Échec de l'exécution de la commande | 1. Exécutez manuellement la commande du hook pour confirmer qu'elle s'exécute correctement<br>2. Vérifiez si le script dispose des permissions d'exécution (chmod +x script.sh)<br>3. Utilisez un chemin absolu pour appeler le script afin d'éviter les problèmes de variables d'environnement |
| Afficher les journaux détaillés | Ajouter lors du démarrage de Claude Code--debugparamètre pour afficher l'intégralité du processus d'exécution du hook |
Autres extensionsDocumentation de référence : pour obtenir une description complète de la fonctionnalité hook, reportez-vous à la documentation de référence officielleHooks。