OpenClaw Hooks : le guide complet du développeur (2026)

Comment fonctionne la découverte de crochets OpenClaw

La passerelle utilise analyse automatique des répertoires pour découvrir des hameçons. Au démarrage, il analyse les répertoires de hook configurés et charge tous les packages de hook valides qu'il trouve.

Deux conditions préalables importantes avant l’activation des hooks :

1. Les crochets doivent être explicitement activé — un répertoire hook seul ne suffit pas
2. Au moins une entrée de hook doit être configurée dans les paramètres de votre passerelle

Chaque package de hook nécessite exactement deux fichiers :

• HOOK.md — fichier de métadonnées déclarant le nom, la version, la description, les abonnements aux événements du cycle de vie et toutes les autorisations requises du hook
• handler.ts (ou handler.js) — le fichier d'implémentation contenant la logique réelle qui s'exécute lorsque l'événement se déclenche

Les quatre événements du cycle de vie que tout développeur devrait connaître

Utilisation du pré-outil est le plus puissant — c'est le seul événement qui peut avorter un appel d'outil avant son exécution. Si votre hook renvoie un signal de rejet pendant PreToolUse, l'agent n'appelle jamais l'outil.

Utilisation de l'outil de publication est le cheval de bataille de l’automatisation. Fichier écrit ? Exécutez votre linter. Test modifié ? Exécutez la suite. Code commis ? Déclenchez une build.

Étape par étape : écrire votre premier hook personnalisé à partir de zéro

La plupart de la documentation vous montre des commandes. Cela vous montre le chemin complet de rien à un hook fonctionnel.

Étape 1 — Créez le répertoire hook

mkdir -p .OpenClaw/hooks/auto-lint

Étape 2 — Écrivez les métadonnées HOOK.md

# auto-lint

**Version:** 1.0.0
**Event:** PostToolUse
**Description:** Runs ESLint on any file written by the agent
**Tools:** write_file, edit_file

Le champ Tools étend votre hook à des appels d'outils spécifiques. Sans cela, le crochet tire chaque Événement PostToolUse — généralement pas ce que vous voulez.

Étape 3 — Mettre en œuvre handler.ts

import { PostToolUseEvent } from "@OpenClaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const filePath = event.toolResult?.path;
  if (!filePath) return;

  try {
    execSync(`npx eslint --fix "${filePath}"`, { stdio: "inherit" });
  } catch (err) {
    console.error(`[auto-lint] ESLint failed on ${filePath}`);
  }
}

Étape 4 — Activer via CLI

OpenClaw hooks enable auto-lint

Étape 5 — Vérifiez qu'il est chargé

OpenClaw hooks list

Vous devriez voir auto-lint avec le statut enabled. Démarrez une session, écrivez un fichier et regardez le linter se déclencher.

JavaScript vs TypeScript pour les gestionnaires de hooks : que choisir en 2026

Le SDK est livré avec des saisies TypeScript complètes et, à partir des versions 2026 du SDK, TypeScript est la valeur par défaut recommandée pour les nouveaux crochets.

Si vous écrivez un hook que vous vous engagerez à contrôler la version ou à partager avec une équipe, utilisez TypeScript. Pour un garde-corps local jetable, du JavaScript simple convient : nommez-le simplement handler.js et ignorez l'étape de compilation.

Référence CLI d'OpenClaw Hooks

Gestion des packs de hooks : installation, mise à jour et flux de travail --dry-run

Les packs de crochets regroupent plusieurs crochets associés en une seule unité installable. Le workflow d'installation vérifie un hachage d'intégrité avant d'écrire quoi que ce soit sur le disque.

# Preview what would be installed without committing
OpenClaw hooks install productivity-pack --dry-run

# Install non-interactively (for CI environments)
OpenClaw hooks install productivity-pack --yes

# Update all installed packs
OpenClaw hooks update --all

Référence des hooks groupés : ce qui est livré avec OpenClaw

Exécutez OpenClaw hooks inspect session-memory pour voir ses options de configuration complètes. La plupart des hooks fournis sont livrés avec des valeurs par défaut raisonnables mais exposent des champs de configuration pour la personnalisation.

Cas d'utilisation de Hooks dans le monde réel (avec exemples pratiques)

1. Garde-corps de protection des fichiers (PreToolUse)

Empêchez l'agent de toucher à votre fichier .env :

import { PreToolUseEvent } from "@OpenClaw/sdk";

export default function handler(event: PreToolUseEvent) {
  const target = event.toolInput?.path ?? "";
  if (target.includes(".env")) {
    return { abort: true, reason: "Modification of .env files is blocked by policy." };
  }
}

Déposez ceci dans .OpenClaw/hooks/protect-env/ avec le HOOK.md correspondant abonné à PreToolUse étendu à write_file et edit_file. L'agent reçoit le motif du rejet dans son contexte et ne réessaiera pas.

2. Notification Slack à l'arrêt de la session

import { StopEvent } from "@OpenClaw/sdk";

export default async function handler(event: StopEvent) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `OpenClaw session ended. Files modified: ${event.session.filesModified ?? 0}`
    })
  });
}

Abonnez ce hook à l'événement Stop. Chaque fin de session déclenche un message Slack avec un résumé. Aucun serveur externe n'est nécessaire : le processus Gateway effectue directement la demande sortante.

3. Formatage automatique + Test sur PostToolUse

import { PostToolUseEvent } from "@OpenClaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const file = event.toolResult?.path;
  if (!file?.endsWith(".ts")) return;

  execSync(`prettier --write "${file}"`);
  execSync("npm test -- --passWithNoTests", { stdio: "inherit" });
}

Cela se déclenche après chaque écriture de fichier TypeScript, le formate, puis exécute votre suite de tests. Lent sur les grands projets : définissez-le étroitement à l'aide du champ Tools dans HOOK.md.

Hooks for Teams – Application de garde-fous dans un projet partagé

Validez votre répertoire .OpenClaw/hooks/ dans le contrôle de version. Chaque développeur qui clone le dépôt a automatiquement la même configuration de hook.

• Verrouillez les hooks critiques sur enabled dans la configuration du projet - empêche les coéquipiers de désactiver accidentellement les protections de fichiers
• Utilisez les descriptions HOOK.md pour documenter l'intention — traitez-les comme des commentaires de code, les coéquipiers les liront
• La portée s'accroche à la granularité au niveau de l'outil — les crochets larges ralentissent toutes les interactions des agents, créant des frictions qui amènent les coéquipiers à les désactiver
• Dans monorepos, les hooks d'un répertoire parent s'appliquent à tous les projets imbriqués, sauf s'ils sont remplacés au niveau du sous-répertoire.

Intégration CI/CD – Exécution de Hooks OpenClaw de manière non interactive

Dans GitHub Actions ou dans tout environnement sans tête, l'invite de confirmation interactive bloquera votre pipeline. Utilisez --yes pour l'ignorer :

- name: Install hooks non-interactively
  run: OpenClaw hooks install qa-pack --yes

- name: Run OpenClaw session
  env:
    OpenClaw_HOOKS_ENABLED: "true"
    SLACK_WEBHOOK_URL: secrets.SLACK_WEBHOOK_URL
  run: OpenClaw run --task "audit dependencies" --yes

Hook Security : ce qui fonctionne, à quoi il peut accéder et comment rester en sécurité

C'est la partie que la plupart de la documentation ignore entièrement - et c'est la section la plus importante si vous installez des packs de hooks communautaires.

À quels hooks peuvent accéder : Les scripts Hook héritent du autorisations complètes du processus Gateway. Si la passerelle s'exécute en tant que compte utilisateur, vos hooks peuvent lire n'importe quel fichier que le compte peut lire, effectuer des requêtes réseau, exécuter des sous-processus et accéder aux variables d'environnement, y compris les secrets.

Liste de contrôle d’audit du pack de crochets

Parcourez ceci avant d'installer un pack tiers :

La commande OpenClaw hooks inspect vous montre le chemin source complet d'un hook installé - utilisez-la pour réexaminer le code du gestionnaire après les mises à jour.

Dépannage des hooks OpenClaw - Lorsqu'ils ne se déclenchent pas

Foire aux questions

Réflexions finales – Choisir la bonne stratégie de hook pour votre flux de travail

Commencez avec un hook qui résout un vrai problème : un garde de fichiers ou un linter post-écriture. Faites-le fonctionner de bout en bout avant d’en superposer davantage. La puissance des hooks composés : une session avec trois hooks de bonne portée qui se déroulent sans problème est nettement plus fiable qu'une session avec dix hooks de mauvaise portée auxquels vous ne faites pas confiance.