OpenClaw Hooks: Das komplette Entwicklerhandbuch (2026)

So funktioniert OpenClaw Hook Discovery

Das Gateway verwendet automatische Verzeichnissuche Haken entdecken. Beim Start durchsucht es konfigurierte Hook-Verzeichnisse und lädt alle gefundenen gültigen Hook-Pakete.

Zwei wichtige Voraussetzungen vor der Aktivierung von Hooks:

1. Haken müssen sein explizit aktiviert — Ein Hook-Verzeichnis allein reicht nicht aus
2. Mindestens Es muss ein Hook-Eintrag konfiguriert werden in Ihren Gateway-Einstellungen

Jedes Hook-Paket erfordert genau zwei Dateien:

• HOOK.md – Metadatendatei, die den Namen, die Version, die Beschreibung, die Abonnements für Lebenszyklusereignisse und alle erforderlichen Berechtigungen des Hooks angibt
• handler.ts (oder handler.js) – die Implementierungsdatei, die die eigentliche Logik enthält, die ausgeführt wird, wenn das Ereignis ausgelöst wird

Die vier Lebenszyklusereignisse, die jeder Entwickler kennen sollte

PreToolUse ist das mächtigste – es ist das einzige Ereignis, das das kann abbrechen einen Tool-Aufruf, bevor er ausgeführt wird. Wenn Ihr Hook während PreToolUse ein Ablehnungssignal zurückgibt, ruft der Agent das Tool nie auf.

PostToolUse ist das Arbeitspferd für die Automatisierung. Datei geschrieben? Lassen Sie Ihren Linter laufen. Test geändert? Führen Sie die Suite aus. Code festgeschrieben? Einen Build auslösen.

Schritt-für-Schritt: Schreiben Sie Ihren ersten benutzerdefinierten Hook von Grund auf

Die meisten Dokumentationen zeigen Ihnen Befehle. Dies zeigt Ihnen den vollständigen Weg vom Nichts zum funktionierenden Haken.

Schritt 1 – Erstellen Sie das Hook-Verzeichnis

mkdir -p .OpenClaw/hooks/auto-lint

Schritt 2 – Schreiben Sie die HOOK.md-Metadaten

# auto-lint

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

Das Feld Tools begrenzt Ihren Hook auf bestimmte Toolaufrufe. Ohne sie feuert der Haken weiter jeder PostToolUse-Ereignis – normalerweise nicht das, was Sie wollen.

Schritt 3 – Implementieren Sie 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}`);
  }
}

Schritt 4 – Aktivierung über CLI

OpenClaw hooks enable auto-lint

Schritt 5 – Überprüfen Sie, ob es geladen ist

OpenClaw hooks list

Sie sollten auto-lint mit dem Status enabled sehen. Starten Sie eine Sitzung, schreiben Sie eine Datei und beobachten Sie, wie der Linter feuert.

JavaScript vs. TypeScript für Hook-Handler – Was Sie im Jahr 2026 wählen sollten

Das SDK wird mit vollständigen TypeScript-Typisierungen ausgeliefert und ab den SDK-Versionen 2026 TypeScript ist die empfohlene Standardeinstellung für neue Haken.

Wenn Sie einen Hook schreiben, den Sie zur Versionskontrolle verpflichten oder mit einem Team teilen möchten, verwenden Sie TypeScript. Für eine wegwerfbare lokale Leitplanke ist einfaches JavaScript in Ordnung – nennen Sie es einfach handler.js und überspringen Sie den Kompilierungsschritt.

OpenClaw Hooks CLI-Referenz

Verwalten von Hook-Packs – Installation, Update und der --dry-run-Workflow

Hakenpakete bündeln mehrere zusammengehörige Haken als eine einzige installierbare Einheit. Der Installationsworkflow überprüft eine Integritäts-Hash bevor Sie etwas auf die Festplatte schreiben.

# 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

Referenz zu gebündelten Haken: Was im Lieferumfang von OpenClaw enthalten ist

Führen Sie OpenClaw hooks inspect session-memory aus, um die vollständigen Konfigurationsoptionen anzuzeigen. Die meisten gebündelten Hooks werden mit sinnvollen Standardeinstellungen ausgeliefert, stellen aber Konfigurationsfelder zur Anpassung bereit.

Reale Hook-Anwendungsfälle (mit Arbeitsbeispielen)

1. Dateischutzleitplanke (PreToolUse)

Verhindern Sie, dass der Agent jemals Ihre Datei .env berührt:

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." };
  }
}

Legen Sie dies in .OpenClaw/hooks/protect-env/ ab, wobei der entsprechende HOOK.md PreToolUse abonniert und auf write_file und edit_file beschränkt ist. Der Agent erhält den Ablehnungsgrund in seinem Kontext und wird es nicht erneut versuchen.

2. Slack-Benachrichtigung bei Sitzungsstopp

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}`
    })
  });
}

Abonnieren Sie diesen Hook für das Ereignis Stop. Bei jedem Sitzungsende wird eine Slack-Nachricht mit einer Zusammenfassung ausgelöst. Kein externer Server erforderlich – der Gateway-Prozess stellt die ausgehende Anfrage direkt.

3. Automatische Formatierung + Test auf 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" });
}

Dies wird nach jedem Schreibvorgang einer TypeScript-Datei ausgelöst, formatiert sie und führt dann Ihre Testsuite aus. Langsam bei großen Projekten – schränken Sie es eng ein, indem Sie das Feld Tools in HOOK.md verwenden.

Hooks für Teams – Durchsetzung von Leitplanken in einem gemeinsamen Projekt

Übergeben Sie Ihr Verzeichnis .OpenClaw/hooks/ der Versionskontrolle. Jeder Entwickler, der das Repo klont, hat automatisch die gleiche Hook-Konfiguration.

• Sperren Sie kritische Hooks in der Projektkonfiguration auf enabled – verhindert, dass Teamkollegen versehentlich Dateiwächter deaktivieren
• Verwenden Sie HOOK.md-Beschreibungen, um die Absicht zu dokumentieren – Behandeln Sie sie wie Codekommentare, Teamkollegen werden sie lesen
• Der Bereich hängt von der Granularität auf Werkzeugebene ab – Breite Haken verlangsamen alle Agenteninteraktionen und erzeugen Reibung, die dazu führt, dass Teamkollegen sie deaktivieren
• In Monorepos gelten Hooks in einem übergeordneten Verzeichnis für alle verschachtelten Projekte, sofern sie nicht auf Unterverzeichnisebene überschrieben werden

CI/CD-Integration – Nicht-interaktives Ausführen von OpenClaw-Hooks

In GitHub Actions oder einer anderen Headless-Umgebung führt die interaktive Bestätigungsaufforderung dazu, dass Ihre Pipeline hängen bleibt. Verwenden Sie --yes, um es zu überspringen:

- 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-Sicherheit: Was ausgeführt wird, worauf es zugreifen kann und wie Sie sicher bleiben

Dies ist der Teil, den die meisten Dokumentationen vollständig überspringen – und es ist der wichtigste Abschnitt, wenn Sie Community-Hook-Packs installieren.

Auf welche Hooks kann zugegriffen werden: Hook-Skripte erben die volle Berechtigungen des Gateway-Prozesses. Wenn das Gateway unter Ihrem Benutzerkonto ausgeführt wird, können Ihre Hooks jede Datei lesen, die dieses Konto lesen kann, Netzwerkanfragen stellen, Unterprozesse ausführen und auf Umgebungsvariablen einschließlich Geheimnissen zugreifen.

Checkliste für das Hook Pack-Audit

Führen Sie dies durch, bevor Sie ein Paket eines Drittanbieters installieren:

Der Befehl OpenClaw hooks inspect zeigt Ihnen den vollständigen Quellpfad eines installierten Hooks – verwenden Sie ihn, um den Handler-Code nach Aktualisierungen erneut zu überprüfen.

Fehlerbehebung bei OpenClaw-Haken – wenn sie nicht ausgelöst werden

Häufig gestellte Fragen

Abschließende Gedanken – Auswahl der richtigen Hook-Strategie für Ihren Workflow

Beginnen Sie mit einem Haken, der ein echtes Problem löst – einem Dateiwächter oder einem Post-Write-Linter. Lassen Sie es durchgehend arbeiten, bevor Sie weitere Schichten auftragen. Die Kraft von Hooks-Verbindungen: Eine Sitzung mit drei Hooks mit gutem Scope, die reibungslos ablaufen, ist deutlich zuverlässiger als eine mit zehn Hooks mit schlechtem Scope, denen Sie nicht vertrauen.