OpenClaw Hooks – Leitfaden

Wenn Unternehmen ernsthaft erwägen, KI-Agenten in Produktionsumgebungen einzusetzen, stellt sich eine zentrale Frage: Wie lässt sich der Agent wirklich in die bestehende Engineering-Kultur und das Betriebssystem integrieren? Die Antwort von OpenClaw sind Hooks – ein ereignisgesteuertes Automatisierungs-Framework.^[1]

Dieser Artikel ist der dritte Teil der „OpenClaw-Serie". Aufbauend auf den vorherigen Beiträgen zur Architekturübersicht und zum Deployment in der Praxis analysieren wir hier die Designphilosophie, die technischen Details sowie sechs vollständige Praxisbeispiele auf Enterprise-Niveau des Hooks-Systems. Ob Sie bestehende CI/CD-Prozesse optimieren, ein Echtzeit-Alarmsystem aufbauen oder eine vollautomatisierte Reporting-Pipeline erstellen möchten – dieser Artikel liefert Ihnen direkt umsetzbare Anleitungen.

Eins: Vom Polling zur Ereignissteuerung – ein Paradigmenwechsel in der KI-Agenten-Automatisierung

1.1 Grundlegende Schwächen des Polling-Modells

Vor der Einführung des Hooks-Systems verwendeten die meisten KI-Agenten-Frameworks ein Polling-Modell: Das Agentenprogramm sendet in festen Intervallen (z. B. jede Sekunde, alle fünf Sekunden) Abfragen an die verschiedenen Nachrichtenkanäle, um zu prüfen, ob neue Ereignisse verarbeitet werden müssen. Dieses Design ist zwar einfach und intuitiv, weist jedoch drei grundlegende Schwächen auf.

Erstens: Ressourcenverschwendung. Unabhängig davon, ob neue Ereignisse vorliegen, verbrauchen Polling-Anfragen CPU-Zyklen und Netzwerkbandbreite. In einer Multi-Agenten-Umgebung mit 10 Agenten, die jeweils im 1-Sekunden-Takt 5 Kanäle abfragen, entstehen pro Minute 3.000 Leeranfragen – die überwiegende Mehrheit davon völlig sinnlos.

Zweitens: Unkontrollierbare Latenz. Das Polling-Intervall bestimmt die maximale Reaktionslatenz des Systems. Bei einer Abfrage alle 5 Sekunden kann im ungünstigsten Fall ein dringender Alarm fast 5 Sekunden auf seine Bearbeitung warten. In zeitkritischen Szenarien wie Finanztransaktionen oder KI-Cybersecurity-Alarmen ist dies völlig inakzeptabel.

Drittens: Skalierbarkeitsengpass. Mit zunehmender Anzahl von Agenten und überwachten Kanälen wachsen Polling-Anfragen linear oder sogar exponentiell und überlasten schließlich die Backend-Dienste.^[5]

1.2 Vorteile des ereignisgesteuerten Paradigmas

Ereignisgesteuerte Architektur (Event-Driven Architecture, EDA) kehrt diese Logik um: Anstatt aktiv zu fragen „Gibt es ein neues Ereignis?", benachrichtigt das System alle Abonnenten proaktiv, wenn ein Ereignis tatsächlich eintritt. Martin Fowler bezeichnet dies als den Wandel vom „imperativen" zum „reaktiven" Denken.^[5]

Das AWS-Architektur-Whitepaper betont, dass ereignisgesteuerte Architektur drei zentrale Ziele erreicht: Entkopplung (Produzenten und Konsumenten müssen nicht direkt voneinander abhängen), Elastizität (Konsumenten können unabhängig skaliert werden) und Echtzeit (Ereignisse werden innerhalb von Millisekunden an alle Abonnenten übermittelt).^[6]

Das Hooks-System von OpenClaw überträgt genau dieses bewährte Unternehmensarchitektur-Konzept in den Bereich der KI-Agenten. Wie der CNBC-Bericht zeigt, war das Hooks-System bei der Evolution von OpenClaw seit der Clawdbot-Ära der entscheidende technologische Sprung vom „Gesprächswerkzeug" zur „Enterprise-Automatisierungsplattform".^[4]

1.3 Quantitativer Vergleich: Polling vs. Ereignissteuerung

Die folgenden Daten stammen aus einem typischen Unternehmens-Deployment-Szenario (10 Agenten, Überwachung von 8 Kanälen, ca. 2.000 Ereignisse pro Tag):

(n = Anzahl der Agenten, m = Anzahl der überwachten Kanäle)

Zwei: Tiefgehende Analyse der OpenClaw Hooks-Architektur

2.1 Architekturübersicht

Das OpenClaw Hooks-System besteht aus drei Kernkomponenten: Event Producers (Ereigniserzeuger), Gateway Event-Bus und Hook Executor (Hook-Ausführungsengine).^[2]

Ereigniserzeuger sind über die verschiedenen Subsysteme von OpenClaw verteilt – wenn ein Benutzer eine Nachricht sendet, ein Agent eine Aufgabe abschließt, ein Skill aufgerufen wird oder ein geplanter Zeitpunkt erreicht ist, erzeugt das entsprechende Subsystem ein standardisiertes Ereignisobjekt und überträgt es an das Gateway.

Das Gateway läuft auf dem lokalen WebSocket-Endpunkt ws://127.0.0.1:18789 und fungiert als Event-Bus. Es ist verantwortlich für den Empfang aller Ereignisse, das Routing nach Ereignistyp und die Verteilung an alle abonnierten Hooks. Das Gateway verwendet ein nicht-blockierendes asynchrones Modell, das sicherstellt, dass hochfrequente Ereignisse keinen Queue-Stau verursachen.

Die Hook-Ausführungsengine empfängt Ereignisse vom Gateway und führt das entsprechende Hook-Skript in einer Sandbox-Umgebung aus, wobei Ausführungsergebnisse und Fehler erfasst werden. Der gesamte Ausführungszyklus wird vollständig im Audit-Log protokolliert.

2.2 Hook-Lebenszyklus

Jeder Hook durchläuft von der Ereignisauslösung bis zur Fertigstellung den folgenden standardisierten Lebenszyklus:

1. Ereigniserzeugung: Das Subsystem serialisiert das Ereignis als JSON-Objekt, einschließlich Ereignistyp, Zeitstempel, Quell-Agenten-ID und ereignisspezifischem Payload.
2. Gateway-Routing: Nach Empfang des Ereignisses durchsucht das Gateway die Routing-Tabelle und findet alle Hooks, die diesen Ereignistyp abonniert haben.
3. Filterbewertung: Falls der Hook Filterbedingungen definiert hat, bewertet die Engine zunächst die Filterregeln. Ereignisse, die die Bedingungen nicht erfüllen, werden direkt verworfen und gelangen nicht in die Ausführungsphase.
4. Sandbox-Initialisierung: Dem Hook wird ein isolierter Sandbox-Prozess zugewiesen, in den die erforderlichen Umgebungsvariablen und Berechtigungstoken injiziert werden.
5. Hook-Ausführung: Die handler-Funktion des Hook-Skripts wird in der Sandbox ausgeführt, wobei das standardisierte Ereignisobjekt übergeben wird.
6. Ergebnisrückgabe: Das Ausführungsergebnis des Hooks (Erfolg/Fehler/Rückgabewert) wird erfasst und im Audit-Log protokolliert.
7. Sandbox-Bereinigung: Die Sandbox-Ressourcen werden freigegeben, um eine vollständige Isolation zwischen Hooks zu gewährleisten.

2.3 Grundlegende Unterschiede zu Cron und traditionellen Webhooks

Viele Ingenieure neigen dazu, OpenClaw Hooks mit Cron-Jobs oder traditionellen Webhooks gleichzusetzen, doch es bestehen wesentliche Unterschiede:

Unterschied zu Cron: Cron-Jobs werden zeitbasiert ausgelöst und laufen unabhängig davon, ob Ereignisse verarbeitet werden müssen. OpenClaw Hooks kann über den Webhook-Endpunkt (/hooks/wake) in Kombination mit externen Scheduling-Tools (wie System-Cron) eine zeitbasierte Auslösung realisieren, und sein Ausführungskontext ist die Agentenumgebung von OpenClaw – es kann direkt auf den Agentenkontext zugreifen und mit anderen Ereignissen interagieren.

Unterschied zu traditionellen Webhooks: Traditionelle Webhooks erfordern einen öffentlich erreichbaren HTTP-Endpunkt, was Entwickler dazu zwingt, Server zu verwalten, TLS zu handhaben und die Herkunft zu verifizieren. OpenClaw Hooks laufen auf dem lokalen Gateway, benötigen keinen öffentlichen Endpunkt und sind nativ in das Authentifizierungssystem des Agenten integriert.

Drei: Aktivierung und Grundkonfiguration

3.1 Voraussetzungen prüfen

Bevor Sie OpenClaw Hooks aktivieren, stellen Sie sicher, dass die folgenden Bedingungen erfüllt sind:^[10]

• OpenClaw Version ≥ 2026.1.0 (das Hooks-System wird ab dieser Version stabil unterstützt, datumsbasierte Versionierung)
• Node.js ≥ 22 (Ausführungsumgebung für Hook-Skripte)
• Lokales Gateway läuft (openclaw gateway start)
• Mindestens ein Agent-Profil ist konfiguriert

Gateway-Status prüfen:

openclaw gateway status
# Erwartete Ausgabe:
# Gateway Status: Running
# WebSocket: ws://127.0.0.1:18789
# Connected Agents: 2
# Active Hooks: 0

3.2 Hooks-System aktivieren

OpenClaw bietet zwei Aktivierungsmethoden:

Methode 1: Globale Aktivierung (empfohlen)

openclaw hooks enable

Dieser Befehl ändert die globale Konfiguration ~/.openclaw/openclaw.json (JSON5-Format), setzt hooks.internal.enabled auf true und startet das Hook-Routing-Modul im Gateway. Nach der Aktivierung ist kein Gateway-Neustart erforderlich – die Änderung wird sofort wirksam.

Methode 2: Aktivierung für einen bestimmten Hook

openclaw hooks enable my-custom-hook

In diesem Modus wird nur der Hook mit dem angegebenen Namen aktiviert – geeignet für die präzise Steuerung einzelner Hooks. Mit openclaw hooks list können Sie alle verfügbaren Hooks anzeigen.

3.3 Konfigurationsdateiformat

OpenClaw verwendet einen verzeichnisbasierten automatischen Erkennungs-Mechanismus. Jeder Hook ist ein eigenständiges Verzeichnis mit HOOK.md (Metadaten) und handler.ts (Verarbeitungslogik):

# Workspace hooks (höchste Priorität)
project/hooks/
├── task-notifier/
│   ├── HOOK.md            # Metadaten + Dokumentation
│   └── handler.ts         # Ereignisverarbeitungsfunktion
├── error-alert/
│   ├── HOOK.md
│   └── handler.ts
└── deploy-hook/
    ├── HOOK.md
    └── handler.ts

# Benutzerglobale hooks
~/.openclaw/hooks/
└── shared-logger/
    ├── HOOK.md
    └── handler.ts

# Globale Konfiguration
~/.openclaw/openclaw.json    # JSON5-Format

Die Grundstruktur von HOOK.md (YAML-Front-Matter + Markdown-Dokumentation):

---
name: task-notifier
description: "Sendet eine Slack-Benachrichtigung wenn ein Befehl abgeschlossen wird"
metadata:
  openclaw:
    events: ["command:new", "command:stop"]
    export: "default"
    requires:
      bins: ["node"]
      env: ["SLACK_WEBHOOK_URL"]
    always: false
---

# Task Notifier Hook

Dieser Hook sendet bei Befehlsabschluss oder -stopp Benachrichtigungen über den Slack-Webhook.

Die zugehörige handler.ts:

// hooks/task-notifier/handler.ts
export default async function handler(event) {
  // event.type: 'command' | 'message' | 'agent' | 'gateway'
  // event.action: 'new' | 'reset' | 'stop' | 'received' | 'sent' usw.
  if (event.action !== "stop") return;

  const webhookUrl = process.env.SLACK_WEBHOOK_URL;
  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `Befehl abgeschlossen — Session: ${event.sessionKey}`
    })
  });
}

3.4 Globale Konfigurationsoptionen

Vollständige Hooks-bezogene Konfigurationsoptionen in ~/.openclaw/openclaw.json (JSON5-Format):

// ~/.openclaw/openclaw.json (JSON5, unterstützt Kommentare und Trailing-Kommas)
{
  "hooks": {
    // Interne Hooks (ereignisgesteuert)
    "internal": {
      "enabled": true,
      "entries": {
        "task-notifier": { "enabled": true },
        "error-alert": {
          "enabled": true,
          "env": { "ALERT_LEVEL": "high" }
        }
      },
      "load": {
        "extraDirs": ["/shared/hooks"]  // Zusätzliche Hook-Suchverzeichnisse
      }
    },
    // Webhook-Endpunkt (HTTP-Auslösung)
    "enabled": true,
    "token": "your-secret-token",       // Webhook-Verifizierungstoken
    "path": "/hooks",                   // Webhook-Basispfad
    "maxBodyBytes": 262144,             // Max. Request-Payload-Größe
    "defaultSessionKey": "hook:ingress",
    "allowedAgentIds": ["hooks", "main"]
  }
}

Vier: Übersicht der integrierten Hook-Ereignisse

4.1 Befehlsereignisse

Befehlsereignisse werden ausgelöst, wenn der Agent Benutzerbefehle verarbeitet (Ereignisnamen verwenden Doppelpunkt-Trennung):^[1]

4.2 Agenten- und Gateway-Ereignisse

4.3 Nachrichtenereignisse

4.4 Tool-Ergebnis-Ereignisse

Hinweis: Alle Ereignisnamen verwenden Doppelpunkt-Trennung (z. B. command:new), nicht Punktnotation. Bei der Deklaration der von einem Hook abonnierten Ereignisse in HOOK.md kann auch ein Wildcard-Typ ohne Action verwendet werden (z. B. command matcht alle command:*-Ereignisse).

Fünf: Leitfaden zur Erstellung benutzerdefinierter Hooks

5.1 Grundstruktur eines Hook-Skripts

Jeder Hook existiert als Verzeichnis mit HOOK.md (Metadaten) und handler.ts (Verarbeitungslogik). Der Handler muss als export default eine asynchrone Funktion exportieren:

// hooks/my-custom-hook/HOOK.md
---
name: my-custom-hook
description: "Beispiel eines benutzerdefinierten Hooks"
metadata:
  openclaw:
    events: ["command:new", "command:stop"]
    export: "default"
    requires:
      bins: ["node"]
---
# My Custom Hook
Dieser Hook wird bei Befehlserstellung oder -stopp ausgelöst und dient zur Protokollierung und Benachrichtigung.

// hooks/my-custom-hook/handler.ts

/**
 * Haupt-Handler-Funktion des Hooks (export default)
 * @param event.type - Ereigniskategorie ('command' | 'message' | 'agent' | 'gateway')
 * @param event.action - Konkrete Aktion ('new' | 'reset' | 'stop' | 'received' usw.)
 * @param event.sessionKey - Sitzungskennung
 * @param event.timestamp - ISO-Zeitstempel
 * @param event.messages - String-Array, um Nachrichten an den Agenten zu senden
 * @param event.context - Ereigniskontext (enthält sessionId, workspaceDir, cfg usw.)
 */
export default async function handler(event) {
  const { type, action, context, messages } = event;

  console.log(`Hook ausgelöst: ${type}:${action}`, {
    sessionKey: event.sessionKey,
    workspace: context.workspaceDir
  });

  // Hier Ihre Automatisierungslogik implementieren
  if (action === "stop") {
    // Nachrichten an das messages-Array pushen, um den Agenten zu weiteren Aktionen anzuweisen
    messages.push("Bitte die Sitzungszusammenfassung im memory/-Verzeichnis speichern");
  }
}

5.2 Syntax der Ereignisfilter

Die Ereignisfilterung von OpenClaw Hooks erfolgt über zwei Ebenen: Die HOOK.md-Deklaration legt die abonnierten Ereignistypen fest, und die handler-interne Logik führt feingranulare Bedingungsprüfungen durch. Die offizielle Dokumentation empfiehlt: „Am Anfang des Handlers ein Early Return verwenden, um irrelevante Ereignisse zu ignorieren."

// hooks/filtered-hook/HOOK.md
---
name: filtered-hook
description: "Verarbeitet nur Nachrichten aus bestimmten Kanälen"
metadata:
  openclaw:
    events: ["message:received"]   # Ebene 1: Nur message:received abonnieren
    export: "default"
---

// hooks/filtered-hook/handler.ts
export default async function handler(event) {
  // Ebene 2: Feingranulare Filterung innerhalb des Handlers
  if (event.action !== "received") return;

  const { channelId, from, content } = event.context;

  // Nur Nachrichten aus dem Slack-Kanal verarbeiten
  if (channelId !== "slack-prod") return;

  // Eigene Bot-Nachrichten ignorieren
  if (from === "openclaw-bot") return;

  // Alle Filterbedingungen bestanden, Geschäftslogik ausführen
  console.log("Slack-Nachricht wird verarbeitet", { from, channelId });
  await processSlackMessage(content);
}

5.3 Interaktionsmuster mit dem Agenten

Hooks interagieren mit dem Agenten hauptsächlich auf zwei Arten: Nachrichten pushen (event.messages.push()), damit der Agent nach Empfang des Ereignisses weitere Aktionen ausführt, und direkte Seiteneffekte (wie HTTP-Anfragen, Dateioperationen) zur Verarbeitung der Automatisierungslogik.

// hooks/smart-responder/handler.ts
export default async function handler(event) {
  const { type, action, context, messages } = event;

  if (type !== "message" || action !== "received") return;

  const { content, channelId, from } = context;

  // Methode 1: Nachrichten an den Agenten pushen, damit der Agent die Weiterverarbeitung übernimmt
  if (content.includes("urgent")) {
    messages.push(
      `Dringende Nachricht von ${from} empfangen, bitte analysieren und antworten: ${content}`
    );
  }

  // Methode 2: Direkte Seiteneffekte (HTTP-Anfragen, externe API-Aufrufe usw.)
  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `[${channelId}] Nachricht empfangen von ${from}: ${content.substring(0, 100)}`
    })
  });

  // Methode 3: Bei agent:bootstrap zusätzliche Dateien injizieren
  if (type === "agent" && action === "bootstrap") {
    context.bootstrapFiles?.push({
      path: "extra-context.md",
      content: "# Zusätzlicher Kontext\nAutomatisch injizierte Startdatei"
    });
  }
}

5.4 Fehlerbehandlung und Wiederholungsversuche

Eine robuste Fehlerbehandlung ist ein Muss für Hooks in Produktionsumgebungen. Nicht abgefangene Ausnahmen im Handler werden von der Hook-Ausführungsengine protokolliert und beeinträchtigen den Gateway-Hauptprozess nicht:

// hooks/resilient-hook/handler.ts
export default async function handler(event) {
  try {
    const result = await riskyOperation(event.context);
    console.log("Hook erfolgreich ausgeführt", { sessionKey: event.sessionKey });

  } catch (error) {
    // Fehler protokollieren und elegant behandeln
    console.error("Hook-Ausführung fehlgeschlagen", {
      error: error.message,
      type: `${event.type}:${event.action}`
    });

    // Optional: Alarm über externen Dienst senden
    if (error.code === "NETWORK_TIMEOUT") {
      await sendAlert(`Hook-Timeout: ${error.message}`);
    }

    // Nicht erneut werfen = stille Behandlung
    // Erneut werfen = Engine protokolliert nicht abgefangene Ausnahme
  }
}

async function riskyOperation(context) {
  const response = await fetch("https://api.example.com/data", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ session: context.sessionId }),
    signal: AbortSignal.timeout(5000)  // 5-Sekunden-Timeout
  });

  if (!response.ok) {
    const err = new Error(`HTTP ${response.status}`);
    err.code = response.status === 429 ? "RATE_LIMITED" : "HTTP_ERROR";
    throw err;
  }

  return response.json();
}

async function sendAlert(message) {
  const webhook = process.env.ALERT_WEBHOOK_URL;
  if (!webhook) return;
  await fetch(webhook, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text: message })
  });
}

Sechs: Praxisbeispiel 1 – CI/CD-Pipeline-Automatisierung

6.1 Szenariobeschreibung

Das Engineering-Team eines mittelständischen Softwareunternehmens möchte nach jedem Merge eines GitHub Pull Requests automatisch Test-, Build- und Deployment-Prozesse auslösen und an jedem kritischen Knotenpunkt den Slack-Kanal benachrichtigen. Die traditionelle Lösung erfordert die Pflege komplexer GitHub-Actions-Workflows, während der gesamte Prozess mit OpenClaw Hooks flexibler durch einen KI-Agenten koordiniert werden kann.^[9]

6.2 Architekturentwurf

Gesamter Datenfluss: GitHub Webhook → /hooks/github-Endpunkt → message:received-Ereignis → Hook pusht Nachricht → Agent führt Deployment-Aufgabe aus → command:stop-Ereignis → Benachrichtigungs-Hook

6.3 Vollständige Implementierung

Schritt 1: Webhook-Endpunkt konfigurieren

In ~/.openclaw/openclaw.json das GitHub-Webhook-Mapping konfigurieren:

// ~/.openclaw/openclaw.json (JSON5)
{
  "hooks": {
    "enabled": true,
    "token": "${GITHUB_WEBHOOK_SECRET}",
    "mappings": [
      {
        "match": { "path": "github" },
        "action": "agent",
        "agentId": "main",
        "wakeMode": "now",
        "sessionKey": "hook:github:{{body.pull_request.number}}",
        "messageTemplate": "GitHub PR #{{body.pull_request.number}} ({{body.action}}): {{body.pull_request.title}}"
      }
    ]
  }
}

Schritt 2: Hook-Verzeichnis und HOOK.md erstellen

// hooks/github-pr-deploy/HOOK.md
---
name: github-pr-deploy
description: "Löst CI/CD-Deployment-Prozess nach PR-Merge aus"
metadata:
  openclaw:
    events: ["message:received"]
    export: "default"
    requires:
      env: ["SLACK_WEBHOOK_URL"]
---

Schritt 3: Hook-Skript deployen

// hooks/github-pr-deploy/handler.ts
export default async function handler(event) {
  if (event.action !== "received") return;

  const { content, channelId } = event.context;
  // Filter: Nur Nachrichten aus dem GitHub-Webhook-Kanal verarbeiten
  if (!channelId?.startsWith("hook:github")) return;

  // PR-Informationen parsen (content ist der von messageTemplate gerenderte Text)
  console.log("PR-Ereignis ausgelöst", { channelId, content });

  // Nachricht an den Agenten pushen, damit dieser den CI/CD-Prozess ausführt
  event.messages.push(`
GitHub-PR-Merge-Benachrichtigung empfangen. Bitte folgenden CI/CD-Prozess ausführen:
1. Neuesten Code abrufen: git pull origin main
2. Abhängigkeiten installieren: npm ci
3. Test-Suite ausführen: npm test
4. Bei bestandenen Tests Produktions-Build erstellen: npm run build
5. In die Produktionsumgebung deployen
6. Health-Check durchführen, um erfolgreiches Deployment zu bestätigen
7. Deployment-Ergebnis an den Slack-Kanal #deployments melden
  `.trim());
}

// hooks/deploy-notifier/handler.ts
// In Kombination mit dem command:stop-Ereignis nach Befehlsabschluss Slack-Benachrichtigung senden
export default async function handler(event) {
  if (event.type !== "command" || event.action !== "stop") return;

  // Direkt über Webhook Slack benachrichtigen
  const webhookUrl = process.env.SLACK_WEBHOOK_URL;
  if (!webhookUrl) return;

  const message = `✅ *Deployment-Prozess abgeschlossen*\nSession: ${event.sessionKey}\nZeit: ${event.timestamp.toISOString()}`;

  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text: message })
  });

  console.log("Deployment-Benachrichtigung gesendet");
}

Sieben: Praxisbeispiel 2 – Automatisiertes Unternehmens-Reporting-System

7.1 Szenariobeschreibung

Das KI-Digitaltransformations-Team eines E-Commerce-Unternehmens benötigt jeden Werktag um 8:00 Uhr eine automatische Integration von Daten aus vier verschiedenen Quellen (Bestellsystem, Lagersystem, Werbeplattform, Kundenservice), um einen Management-Tagesbericht zu erstellen und per E-Mail an die zuständigen Führungskräfte zu versenden.

7.2 Zeitplanungskonfiguration

Da OpenClaw Hooks kein integriertes Cron-Scheduling bietet, erfordert das automatisierte Reporting einen externen Zeitplaner zur Webhook-Auslösung:

# System-Crontab (in Kombination mit dem OpenClaw-Webhook-Endpunkt)
# Montag bis Freitag um 8 Uhr Tagesbericht auslösen
0 8 * * 1-5 curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bitte den heutigen Geschäftstagesbericht erstellen und an die Management-Postfächer senden"}'

# Jeden Montag um 9 Uhr Wochenbericht auslösen
0 9 * * 1 curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bitte den Geschäftszusammenfassungs-Wochenbericht der letzten Woche erstellen"}'

7.3 Berichtsbenachrichtigungs-Hook

// hooks/report-notifier/HOOK.md
---
name: report-notifier
description: "Sendet E-Mail-Benachrichtigung nach Berichterstellung"
metadata:
  openclaw:
    events: ["command:stop"]
    export: "default"
    requires:
      env: ["SMTP_HOST", "SMTP_USER", "SMTP_PASS"]
---

// hooks/report-notifier/handler.ts
import { createTransport } from "nodemailer";

export default async function handler(event) {
  if (event.action !== "stop") return;

  // Nur berichtsbezogene Sessions verarbeiten
  if (!event.sessionKey?.includes("report")) return;

  const dateStr = new Date().toLocaleDateString("de-DE", {
    year: "numeric", month: "long", day: "numeric"
  });

  console.log("Berichtsprozess abgeschlossen, sende Benachrichtigung", { date: dateStr });

  // Benachrichtigung direkt über SMTP senden (oder Webhook für externen E-Mail-Dienst verwenden)
  const transporter = createTransport({
    host: process.env.SMTP_HOST,
    auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
  });

  await transporter.sendMail({
    to: "[email protected]",
    subject: `【Tagesbericht】${dateStr} Geschäftszusammenfassung wurde erstellt`,
    text: `Der heutige Geschäftstagesbericht wurde automatisch vom KI-Agenten erstellt. Bitte den vollständigen Bericht im System einsehen.\nSession: ${event.sessionKey}`
  });

  console.log("Tagesberichtsbenachrichtigung gesendet", { date: dateStr });
}

Acht: Praxisbeispiel 3 – Echtzeit-Anomalieerkennung und Alarmierung

8.1 Szenariobeschreibung

Das SRE-Team einer SaaS-Plattform benötigt eine Benachrichtigung des diensthabenden Ingenieurs innerhalb von 30 Sekunden, wenn die System-Fehlerrate einen Schwellenwert überschreitet oder bestimmte kritische Fehlertypen auftreten, einschließlich einer automatischen Erstdiagnose.

8.2 Mehrstufige Alarmarchitektur

Durch Kombination von message:received- und command:stop-Ereignissen mit dem Webhook-Endpunkt wird ein mehrstufiges Echtzeit-Alarmsystem realisiert:

// hooks/critical-alert/HOOK.md
---
name: critical-alert
description: "Überwacht Agentennachrichten auf Fehler-Schlüsselwörter und löst Echtzeit-Alarme aus"
metadata:
  openclaw:
    events: ["message:received"]
    export: "default"
    requires:
      env: ["SLACK_WEBHOOK_URL", "PAGERDUTY_KEY"]
---

8.3 Echtzeit-Alarm-Hook

// hooks/critical-alert/handler.ts
export default async function handler(event) {
  if (event.action !== "received") return;

  const { content, channelId } = event.context;
  if (!content) return;

  // Kritische Fehler-Schlüsselwörter erkennen
  const criticalPatterns = ["CRITICAL", "FATAL", "OOM", "503", "timeout"];
  const isCritical = criticalPatterns.some(p =>
    content.toUpperCase().includes(p.toUpperCase())
  );

  if (!isCritical) return;

  console.warn("Kritischer Fehler löst Alarm aus", { channelId });

  // Parallele Ausführung: Slack-Alarm + PagerDuty-Alarm
  await Promise.allSettled([
    sendSlackAlert(content, channelId),
    sendPagerDutyAlert(content, channelId)
  ]);

  // Nachricht pushen, damit der Agent eine Erstdiagnose durchführt
  event.messages.push(
    `Kritische Fehlermeldung erkannt, bitte Erstdiagnose durchführen und Ergebnis-Zusammenfassung antworten. Fehlerinhalt: ${content.substring(0, 500)}`
  );
}

async function sendSlackAlert(content, channelId) {
  const webhookUrl = process.env.SLACK_WEBHOOK_URL;
  if (!webhookUrl) return;

  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `🚨 *CRITICAL ERROR* — Sofortige Bearbeitung erforderlich\n*Kanal*: ${channelId}\n*Nachricht*: ${content.substring(0, 200)}\n*Zeitpunkt*: ${new Date().toLocaleString("de-DE")}`
    })
  });
}

async function sendPagerDutyAlert(content, channelId) {
  const routingKey = process.env.PAGERDUTY_KEY;
  if (!routingKey) return;

  await fetch("https://events.pagerduty.com/v2/enqueue", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      routing_key: routingKey,
      event_action: "trigger",
      payload: {
        summary: `[${channelId}] Kritischer Fehler`,
        severity: "critical",
        source: "openclaw-hooks"
      }
    })
  });
}

8.4 Externes Scheduling für Fehlerraten-Monitoring

# Alle 5 Minuten über Webhook den Agenten zur Fehlerratprüfung auslösen
*/5 * * * * curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bitte die System-Fehlerrate der letzten 5 Minuten abfragen. Falls über 5 %, bitte Alarm an Slack #monitoring senden"}'

Neun: Performance-Optimierung und Best Practices

9.1 Hook-Performance-Benchmarks

Die folgenden Performance-Benchmark-Ergebnisse wurden auf einer Standard-Entwicklungsmaschine (Apple M2, 16 GB RAM) gemessen:

9.2 Debounce- und Throttle-Muster

In Hochfrequenz-Ereignisszenarien kann das direkte Auslösen von Hooks zu einer Überlastung führen. Es empfiehlt sich, Debounce- oder Throttle-Muster im Handler selbst zu implementieren:

// hooks/debounced-aggregator/handler.ts
// Einfaches Debounce im Handler implementieren: Ereignisse über Dateisystem sammeln und im Batch verarbeiten
import { readFileSync, writeFileSync, existsSync } from "fs";
import { join } from "path";

const BATCH_FILE = "/tmp/openclaw-hook-batch.json";
const WINDOW_MS = 10000;  // 10-Sekunden-Fenster

export default async function handler(event) {
  if (event.action !== "received") return;

  // Batch-Puffer lesen oder initialisieren
  let batch = [];
  if (existsSync(BATCH_FILE)) {
    batch = JSON.parse(readFileSync(BATCH_FILE, "utf-8"));
  }

  batch.push({
    timestamp: Date.now(),
    sessionKey: event.sessionKey,
    content: event.context.content?.substring(0, 200)
  });

  // Prüfen ob Fensterzeitraum überschritten
  const firstTimestamp = batch[0]?.timestamp || Date.now();
  if (Date.now() - firstTimestamp < WINDOW_MS) {
    // Fenster noch nicht abgelaufen, weiter sammeln
    writeFileSync(BATCH_FILE, JSON.stringify(batch));
    return;
  }

  // Fenster abgelaufen, Batch verarbeiten
  console.log("Batch-Verarbeitung von Ereignissen", { count: batch.length });
  await sendBatchNotification(batch);

  // Puffer leeren
  writeFileSync(BATCH_FILE, "[]");
}

async function sendBatchNotification(batch) {
  const webhook = process.env.SLACK_WEBHOOK_URL;
  if (!webhook) return;
  await fetch(webhook, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `📊 In den letzten 10 Sekunden ${batch.length} Nachrichten empfangen`
    })
  });
}

9.3 Hook-Parallelitätssteuerung

Über openclaw.jsons hooks.internal.entries steuern Sie präzise den Aktivierungsstatus und die Umgebungsvariablen jedes Hooks. In Kombination mit dem requires-Feld in HOOK.md wird sichergestellt, dass Hooks nur bei erfüllten Bedingungen geladen werden:

// ~/.openclaw/openclaw.json (JSON5)
{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        // Hohe Priorität: Alarm-Hooks (immer aktiviert sicherstellen)
        "critical-alert": {
          "enabled": true,
          "env": { "ALERT_LEVEL": "critical" }
        },
        "github-pr-deploy": {
          "enabled": true
        },
        // Niedrigere Priorität, bei Bedarf deaktivierbar
        "report-notifier": {
          "enabled": true
        }
      },
      "load": {
        // Zusätzliche Hook-Suchverzeichnisse (Team-Sharing)
        "extraDirs": ["/shared/team-hooks"]
      }
    }
  }
}

9.4 Idempotenz-Design

Wenn der Wiederholungsmechanismus aktiviert ist, kann ein Hook mehrfach ausgeführt werden. Die Sicherstellung der Idempotenz ist von entscheidender Bedeutung:

// hooks/idempotent-hook/handler.ts
import { existsSync, writeFileSync, readFileSync } from "fs";
import { join } from "path";

const PROCESSED_DIR = "/tmp/openclaw-hook-processed";

export default async function handler(event) {
  if (event.action !== "stop") return;

  // sessionKey als Idempotenz-Schlüssel verwenden
  const idempotencyKey = `${event.sessionKey}-${event.timestamp.toISOString().slice(0, 10)}`;
  const lockFile = join(PROCESSED_DIR, `${idempotencyKey}.lock`);

  // Prüfen, ob dieses Ereignis bereits verarbeitet wurde
  if (existsSync(lockFile)) {
    console.log("Ereignis bereits verarbeitet, doppelte Ausführung wird übersprungen", { sessionKey: event.sessionKey });
    return;
  }

  // Eigentliche Geschäftslogik ausführen
  await performNotification(event);

  // Verarbeitungsstatus speichern
  writeFileSync(lockFile, JSON.stringify({
    processed_at: new Date().toISOString(),
    sessionKey: event.sessionKey
  }));
}

async function performNotification(event) {
  // Konkrete Benachrichtigungslogik...
}

Zehn: Sicherheitsaspekte und Risikomanagement

10.1 Bedrohungsmodell für Hooks

Die wichtigsten Sicherheitsbedrohungen für das OpenClaw Hooks-System umfassen: Hook-Injection-Angriffe (bösartige Ereignis-Payloads, die Hooks zu unbeabsichtigten Aktionen veranlassen), Privilege Escalation (Hook-Skripte versuchen, auf Ressourcen außerhalb des autorisierten Bereichs zuzugreifen) und Supply-Chain-Angriffe (bösartige Abhängigkeitspakete in Hook-Skripten). Sowohl CrowdStrike als auch Cisco betonen in ihren Sicherheitsberichten, dass Hook-Mechanismen in KI-Agenten-Frameworks ein strenges Isolationsdesign erfordern.^[7][8]

10.2 Sandbox-Isolationsmechanismus

Das Hook-System von OpenClaw verwendet mehrstufige Sicherheitsmechanismen:

• Vorqualifikationsprüfung: Vor dem Laden eines Hooks werden automatisch die in HOOK.md deklarierten requires (benötigte Binärdateien, Umgebungsvariablen, OS-Kompatibilität) überprüft. Hooks, die die Bedingungen nicht erfüllen, werden nicht geladen.
• Sichere Installation: Bei der Installation von Hook Packs über openclaw hooks install wird npm install --ignore-scripts ausgeführt, um die Ausführung beliebigen Codes durch Installationsskripte zu verhindern.
• Dateipfadvalidierung: Dateien, auf die ein Hook zugreift, müssen sich im Workspace-Verzeichnis befinden (realpath-Prüfung), um Path-Traversal-Angriffe zu verhindern.
• Quellenbeschränkung: openclaw hooks install akzeptiert nur npm-Registry-Paketnamen und lehnt Git/URL/lokale Dateipfade ab, um das Supply-Chain-Risiko zu reduzieren.

10.3 Best Practices für die Sicherheit von Hook-Skripten

// hooks/secure-hook/handler.ts — Sicheres Hook-Skript-Beispiel
export default async function handler(event) {
  // 1. Strikte Validierung der Context-Struktur (Schutz gegen fehlerhafte bösartige Ereignisse)
  if (!isValidContext(event.context)) {
    console.warn("Context-Validierung fehlgeschlagen, Ausführung verweigert", {
      type: event.type,
      action: event.action,
      contextKeys: Object.keys(event.context || {})
    });
    return;
  }

  // 2. Keinem ausführbaren Inhalt im Context vertrauen
  const safeContent = sanitizeString(event.context.content);

  // 3. Keine sensiblen Daten in Logs aufzeichnen
  console.log("Ereignis wird verarbeitet", {
    type: `${event.type}:${event.action}`,
    sessionKey: event.sessionKey
    // Nicht protokollieren: context kann API-Keys, Tokens usw. enthalten
  });

  // ...Geschäftslogik
}

function isValidContext(context) {
  if (!context || typeof context !== "object") return false;
  return true;
}

function sanitizeString(input) {
  if (typeof input !== "string") return "";
  // Potenzielle Command-Injection-Zeichen entfernen
  return input.replace(/[;&|`$(){}[\]<>]/g, "").substring(0, 255);
}

10.4 Audit-Log-Konfiguration

OpenClaw verfügt über einen integrierten command-logger Hook, der automatisch alle Befehle in ~/.openclaw/logs/commands.log (JSONL-Format) protokolliert. Darüber hinaus kann über einen benutzerdefinierten Hook eine detailliertere Audit-Protokollierung realisiert werden:

// hooks/audit-logger/handler.ts — Benutzerdefiniertes Audit-Log
import { appendFileSync } from "fs";

export default async function handler(event) {
  const auditEntry = {
    timestamp: event.timestamp.toISOString(),
    type: `${event.type}:${event.action}`,
    sessionKey: event.sessionKey,
    contextKeys: Object.keys(event.context || {})
  };

  appendFileSync(
    ".openclaw/logs/hooks-audit.jsonl",
    JSON.stringify(auditEntry) + "\n"
  );
}

Aktivieren Sie zusätzlich den integrierten command-logger Hook:

openclaw hooks enable command-logger
# Logs werden nach ~/.openclaw/logs/commands.log geschrieben (JSONL-Format)

10.5 Verwaltung von Hook-Abhängigkeitspaketen

Über openclaw hooks install werden Hook Packs installiert. Die Abhängigkeiten werden in ~/.openclaw/hooks/<hook-id>/ abgelegt und mit npm install --ignore-scripts installiert, um die Ausführung beliebigen Codes durch Installationsskripte zu verhindern. Folgende Grundsätze sollten beachtet werden:

• Drittanbieter-Abhängigkeiten minimieren und bevorzugt Node.js-Standardmodule verwenden
• openclaw hooks install akzeptiert nur npm-Registry-Paketnamen (Git/URL/lokale Pfade werden abgelehnt)
• Jede Abhängigkeit sollte durch npm audit geprüft werden

# Installierte Hooks und deren Abhängigkeitsstatus anzeigen
openclaw hooks list --verbose

# Hook-Voraussetzungen und Abhängigkeiten prüfen
openclaw hooks check --json

Führen Sie regelmäßig npm audit durch, um bekannte Schwachstellen zu erkennen, und richten Sie automatisierte CI-Prüfungen ein:

# Hook-Sicherheitsscan in CI/CD integrieren
- name: Audit hook dependencies
  run: |
    openclaw hooks check
    npm audit --audit-level=high

10.6 Notfall-Deaktivierungsmechanismus

Wenn Sie bei einem Hook ein Sicherheitsproblem vermuten, können Sie ihn sofort deaktivieren, ohne die Konfiguration ändern zu müssen:

# Einzelnen Hook sofort deaktivieren (kein Gateway-Neustart erforderlich)
openclaw hooks disable critical-alert

# Status aller aktuellen Hooks anzeigen (inkl. Voraussetzungsprüfung)
openclaw hooks list --verbose

# Ausgabe im JSON-Format (für automatisierte Verarbeitung)
openclaw hooks list --json

# Erneut aktivieren
openclaw hooks enable critical-alert

Fazit: Hooks lassen KI-Agenten wirklich in die Engineering-Kultur des Unternehmens einwachsen

Das OpenClaw Hooks-System repräsentiert nicht nur ein technisches Feature, sondern einen entscheidenden Schritt auf dem Weg von KI-Agenten in die Produktionsumgebungen von Unternehmen. Durch die Zero-Polling-ereignisgesteuerte Architektur verwandeln Hooks KI-Agenten von „passiven Antwortwerkzeugen" in „proaktiv reagierende Systeme", die sich nahtlos in CI/CD-Prozesse, Monitoring-Systeme und die bestehende DevOps-Kultur integrieren lassen.

Die sechs Praxisbeispiele in diesem Artikel zeigen, dass die Einsatzmöglichkeiten von Hooks weit darüber hinausgehen – jedes Szenario, das „Wenn X eintritt, führe automatisch Y aus" erfordert, ist ein Anwendungsfall für Hooks. Mit der fortschreitenden Reifung des OpenClaw-Ökosystems erwarten wir, dass der Hooks Marketplace zu einer wichtigen Plattform für den unternehmensübergreifenden Austausch von Automatisierungslogik wird.^[3]

Im Bereich Sicherheit zeigen die Forschungsarbeiten von CrowdStrike und Cisco, dass die Automatisierungsfähigkeiten von KI-Agenten ein zweischneidiges Schwert sind.^[7][8] Die Einhaltung der in diesem Artikel vorgestellten Sicherheits-Best-Practices – strenge Sandbox-Isolation, Prinzip der geringsten Privilegien, vollständige Audit-Logs – ist die grundlegende Anforderung für ein verantwortungsvolles Hooks-Deployment.

Wenn Sie erwägen, OpenClaw Hooks für Ihr Team einzuführen, empfehlen wir, mit einem risikoarmen Logging- oder Benachrichtigungs-Hook zu beginnen und nach wachsendem Vertrauen schrittweise auf komplexere Automatisierungsszenarien zu erweitern. Die Lernkurve des Hooks-Systems ist relativ flach, aber der Nutzen – Ressourceneinsparung, Reaktionsgeschwindigkeit und die Befreiung von Ingenieurkapazitäten von repetitiven Aufgaben – wächst exponentiell mit zunehmender Nutzungstiefe.