Hooks

Hooks sind kleine Skripte, die innerhalb des Gateway ausgeführt werden, wenn Agent-Ereignisse ausgelöst werden: Befehle wie /new, /reset, /stop, Session-Compaction, Gateway-Lebenszyklus und Nachrichtenfluss. Sie werden in Verzeichnissen erkannt und mit openclaw hooks verwaltet. Das Gateway lädt interne Hooks erst, nachdem Sie Hooks aktiviert oder mindestens einen Hook-Eintrag, ein Hook-Paket, einen Legacy-Handler oder ein zusätzliches Hook-Verzeichnis konfiguriert haben.

In OpenClaw gibt es zwei Arten von Hooks:

• Interne Hooks (diese Seite): werden innerhalb des Gateway ausgeführt, wenn Agent-Ereignisse ausgelöst werden.
• Webhooks: externe HTTP-Endpunkte, über die andere Systeme Arbeit in OpenClaw auslösen können. Siehe Webhooks.

Hooks können auch in Plugins gebündelt sein. openclaw hooks list zeigt sowohl eigenständige Hooks als auch von Plugins verwaltete Hooks (angezeigt als plugin:<id>).

Die richtige Oberfläche auswählen

OpenClaw verfügt über mehrere Erweiterungsoberflächen, die ähnlich aussehen, aber unterschiedliche Probleme lösen:

Verwenden Sie interne Hooks, wenn Sie eine Automatisierung wünschen, die sich wie eine kleine installierte Integration verhält. Verwenden Sie typisierte Plugin-Hooks, wenn Sie Kontrolle über den Laufzeitlebenszyklus benötigen.

Schnellstart

# Verfügbare Hooks auflistenopenclaw hooks list # Einen Hook aktivierenopenclaw hooks enable session-memory # Hook-Status prüfenopenclaw hooks check # Detaillierte Informationen abrufenopenclaw hooks info session-memory

Ereignistypen

Hooks abonnieren einen bestimmten Schlüssel aus dieser Tabelle oder einen reinen Familiennamen (command, session, agent, gateway, message), um jede Aktion dieser Familie zu empfangen. Der OpenClaw-Kern gibt nichts anderes aus, daher ist jeder andere Name fast immer ein Tippfehler, durch den der Hook unbemerkt inaktiv bleibt (nur ein Plugin, das ein benutzerdefiniertes Ereignis ausgibt, könnte ihn auslösen). Der Hook-Loader protokolliert für solche Namen eine Warnung (zum Beispiel command:nwe), und openclaw hooks info <name> kennzeichnet sie, sodass ein Hook, der nie ausgeführt wird, diagnostiziert werden kann.

Hooks schreiben

Hook-Struktur

Jeder Hook ist ein Verzeichnis, das zwei Dateien enthält:

my-hook/├── HOOK.md          # Metadaten + Dokumentation└── handler.ts       # Handler-Implementierung

Die Handler-Datei kann handler.ts, handler.js, index.ts oder index.js sein.

HOOK.md-Format

---name: my-hookdescription: "Kurze Beschreibung der Funktion dieses Hooks"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # Mein Hook Hier steht die ausführliche Dokumentation.

Metadatenfelder (metadata.openclaw):

Handler-Implementierung

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] Neuer Befehl ausgelöst`);  // Ihre Logik hier   // Optional eine Antwort auf antwortfähigen Oberflächen senden  event.messages.push("Hook ausgeführt!");}; export default handler;

Jedes Ereignis enthält: type, action, sessionKey, timestamp, messages und context (ereignisspezifische Daten). Typisierte Kontexte von Plugin-Hooks für Agent- und Tool-Hooks können außerdem trace enthalten, einen schreibgeschützten, W3C-kompatiblen Kontext für Diagnose-Traces, den Plugins zur OTEL-Korrelation an strukturierte Protokolle übergeben können.

An event.messages angehängte Zeichenfolgen werden nur bei command:new und command:reset an den Chat zurückgesendet (als Antwort an die ursprüngliche Konversation weitergeleitet) sowie bei session:compact:before / session:compact:after (als Compaction-Statusmeldungen gesendet). Alle anderen Ereignisse, einschließlich command:stop, message:*, agent:bootstrap, session:patch und gateway:*, ignorieren angehängte Nachrichten.

Wichtige Aspekte des Ereigniskontexts

Befehlsereignisse (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.senderId, context.workspaceDir, context.cfg.

Befehlsereignisse (command:stop): context.sessionEntry, context.sessionId, context.commandSource, context.senderId.

Nachrichtenereignisse (message:received): context.from, context.content, context.channelId, context.media (geordnete, bereitgestellte Fakten zu Anhängen), context.originalMedia sowie context.mediaStagingPending, wenn Remote-Medien noch nicht lokal bereitgestellt wurden, und context.metadata (providerspezifische Daten einschließlich senderId, senderName, guildId). context.content bevorzugt bei befehlsähnlichen Nachrichten einen nicht leeren Befehlstext und greift anschließend auf den rohen eingehenden Text und den allgemeinen Text zurück; ausschließlich für den Agent bestimmte Anreicherungen wie Thread-Verlauf oder Link-Zusammenfassungen sind nicht enthalten. Veraltete Medienaliase innerhalb von metadata sind als veraltet markiert.

Nachrichtenereignisse (message:sent): context.to, context.content, context.success, context.channelId sowie context.error, wenn das Senden fehlgeschlagen ist.

Nachrichtenereignisse (message:transcribed): context.transcript, context.from, context.channelId und context.media. context.mediaPath und context.mediaType bleiben veraltete Aliase für den ersten Fakt.

Nachrichtenereignisse (message:preprocessed): context.bodyForAgent (endgültiger angereicherter Text), context.from, context.channelId.

Bootstrap-Ereignisse (agent:bootstrap): context.bootstrapFiles (veränderbares Array), context.agentId.

Session-Patch-Ereignisse (session:patch): context.sessionEntry, context.patch (nur geänderte Felder), context.cfg. Nur privilegierte Clients können Patch-Ereignisse auslösen; der Kontext ist eine Kopie, sodass Handler den aktiven Session-Eintrag nicht verändern können.

Compaction-Ereignisse: session:compact:before enthält messageCount, tokenCount. session:compact:after fügt compactedCount, summaryLength, tokensBefore, tokensAfter hinzu.

command:stop beobachtet, wie der Benutzer /stop ausgibt; dies betrifft den Abbruch-/Befehlslebenszyklus und ist kein Gate für die Finalisierung des Agent. Plugins, die eine natürliche endgültige Antwort prüfen und den Agent zu einem weiteren Durchlauf auffordern müssen, sollten stattdessen den typisierten Plugin-Hook before_agent_finalize verwenden. Siehe Plugin-Hooks.

Gateway-Lebenszyklusereignisse: gateway:shutdown enthält reason und restartExpectedMs und wird ausgelöst, wenn das Herunterfahren des Gateway beginnt. gateway:pre-restart enthält denselben Kontext, wird jedoch nur ausgelöst, wenn das Herunterfahren Teil eines erwarteten Neustarts ist und ein endlicher restartExpectedMs-Wert bereitgestellt wird. Während des Herunterfahrens wird auf jeden Lebenszyklus-Hook nur nach bestem Bemühen und zeitlich begrenzt gewartet, sodass das Herunterfahren fortgesetzt wird, wenn ein Handler hängen bleibt. Das standardmäßige Zeitbudget beträgt 5 Sekunden für gateway:shutdown und 10 Sekunden für gateway:pre-restart.

Verwenden Sie gateway:pre-restart für kurze Neustartmeldungen, solange die Kanäle noch verfügbar sind:

  const execFileAsync = promisify(execFile); export default async function handler(event) {  if (event.type !== "gateway" || event.action !== "pre-restart") {    return;  }   const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);  await execFileAsync("openclaw", [    "system",    "event",    "--mode",    "now",    "--text",    `Gateway wird in ~${restartInSeconds}s neu gestartet (${event.context.reason}). Jetzt einen Checkpoint erstellen.`,  ]);}

Zwischen dem Ereignis gateway:shutdown (oder gateway:pre-restart) und dem restlichen Ablauf des Herunterfahrens löst das Gateway außerdem für jede Session, die beim Beenden des Prozesses noch aktiv war, einen typisierten Plugin-Hook session_end aus. Der Wert reason des Ereignisses ist shutdown bei einem einfachen Stopp durch SIGTERM/SIGINT und restart, wenn das Schließen im Rahmen eines erwarteten Neustarts geplant wurde. Dieser Abschluss ist zeitlich begrenzt, damit ein langsamer session_end-Handler das Beenden des Prozesses nicht blockieren kann. Sessions, die bereits durch Ersetzen / Zurücksetzen / Löschen / Compaction finalisiert wurden, werden übersprungen, um eine doppelte Auslösung zu vermeiden.

Hook-Erkennung

Hooks werden aus vier Quellen erkannt:

1. Mitgelieferte Hooks: werden mit OpenClaw ausgeliefert
2. Plugin-Hooks: sind in installierten Plugins enthalten; können mitgelieferte Hooks mit demselben Namen überschreiben
3. Verwaltete Hooks: ~/.openclaw/hooks/ (vom Benutzer installiert, arbeitsbereichsübergreifend freigegeben); können mitgelieferte und Plugin-Hooks überschreiben. Zusätzliche Verzeichnisse aus hooks.internal.load.extraDirs haben dieselbe Priorität.
4. Arbeitsbereichs-Hooks: <workspace>/hooks/ (pro Agent, standardmäßig deaktiviert, bis sie ausdrücklich aktiviert werden)

Arbeitsbereichs-Hooks können neue Hook-Namen hinzufügen, aber keine mitgelieferten, verwalteten oder von Plugins bereitgestellten Hooks mit demselben Namen überschreiben.

Das Gateway überspringt beim Start die Erkennung interner Hooks, bis interne Hooks konfiguriert sind. Aktivieren Sie einen mitgelieferten oder verwalteten Hook mit openclaw hooks enable <name>, installieren Sie ein Hook-Paket oder legen Sie hooks.internal.enabled=true fest, um die Erkennung zu aktivieren. Wenn Sie einen benannten Hook aktivieren, lädt das Gateway nur den Handler dieses Hooks; hooks.internal.enabled=true, zusätzliche Hook-Verzeichnisse und Legacy-Handler aktivieren die umfassende Erkennung.

Hook-Pakete

Hook-Pakete sind npm-Pakete, die Hooks über openclaw.hooks in package.json exportieren. Installation mit:

openclaw plugins install <path-or-spec>

Npm-Spezifikationen dürfen nur aus der Registry stammen (Paketname + optionale exakte Version oder dist-tag). Git-/URL-/Dateispezifikationen und SemVer-Bereiche werden abgelehnt. Die älteren Befehle openclaw hooks install und openclaw hooks update sind veraltete Aliasse für openclaw plugins install / openclaw plugins update.

Mitgelieferte Hooks

Aktivieren Sie einen beliebigen mitgelieferten Hook:

openclaw hooks enable <hook-name>

Details zu session-memory

Extrahiert die letzten Benutzer-/Assistentennachrichten (standardmäßig 15, konfigurierbar mit hooks.internal.entries.session-memory.messages) und speichert sie anhand des lokalen Datums des Hosts unter <workspace>/memory/YYYY-MM-DD-HHMM.md. Die Speichererfassung läuft im Hintergrund, sodass Bestätigungen für /new und /reset nicht durch das Lesen des Transkripts oder die optionale Slug-Generierung verzögert werden. Legen Sie hooks.internal.entries.session-memory.llmSlug: true fest, um aussagekräftige Dateinamen-Slugs zu generieren, und legen Sie optional hooks.internal.entries.session-memory.model auf einen konfigurierten Alias wie sonnet, eine reine Modell-ID beim Standard-Provider des Agenten oder eine provider/model-Referenz fest. Wenn model nicht angegeben ist, verwendet die Slug-Generierung das Standardmodell des Agenten und greift bei Nichtverfügbarkeit auf Zeitstempel-Slugs zurück. Erfordert die Konfiguration von workspace.dir.

Konfiguration von bootstrap-extra-files

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

patterns und files werden als Aliasse von paths akzeptiert. Pfade werden relativ zum Arbeitsbereich aufgelöst und müssen darin verbleiben. Nur erkannte Bootstrap-Basisnamen werden geladen (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).

Details zu command-logger

Protokolliert jeden Schrägstrichbefehl als JSON-Zeile (Zeitstempel, Aktion, Sitzungsschlüssel, Absender-ID, Quelle) in ~/.openclaw/logs/commands.log.

Details zu compaction-notifier

Sendet kurze Statusmeldungen in die aktuelle Unterhaltung, wenn OpenClaw mit der Compaction des Sitzungstranskripts beginnt und sie beendet. Dadurch sind lange Durchläufe auf Chat-Oberflächen weniger verwirrend, weil Benutzer sehen können, dass der Assistent den Kontext zusammenfasst und nach der Compaction fortfährt.

Details zu boot-md

Führt BOOT.md beim Start des Gateways für jeden konfigurierten Agentenbereich aus, sofern die Datei im aufgelösten Arbeitsbereich dieses Agenten vorhanden ist.

Plugin-Hooks

Plugins können über das Plugin SDK typisierte Hooks für eine tiefere Integration registrieren: Werkzeugaufrufe abfangen, Prompts ändern, den Nachrichtenfluss steuern und mehr. Verwenden Sie Plugin-Hooks, wenn Sie before_tool_call, before_agent_reply, before_install oder andere prozessinterne Lebenszyklus-Hooks benötigen.

Von Plugins verwaltete interne Hooks unterscheiden sich davon: Sie nehmen am auf dieser Seite beschriebenen groben Befehls-/Lebenszyklus-Ereignissystem teil und erscheinen in openclaw hooks list als plugin:<id>. Verwenden Sie diese für Nebeneffekte und die Kompatibilität mit Hook-Paketen, nicht für geordnete Middleware oder Richtlinienprüfungen.

Die vollständige Referenz zu Plugin-Hooks finden Sie unter Plugin-Hooks.

Konfiguration

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

Hook-spezifische Umgebungswerte erfüllen die Eignungsprüfungen eines Hooks für requires.env (zusammen mit der Prozessumgebung), und Handler können sie aus ihrem Hook-Konfigurationseintrag lesen:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

Zusätzliche Hook-Verzeichnisse:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

CLI-Referenz

# Alle Hooks auflisten (--eligible, --verbose oder --json hinzufügen)openclaw hooks list # Detaillierte Informationen zu einem Hook anzeigenopenclaw hooks info <hook-name> # Zusammenfassung der Eignung anzeigenopenclaw hooks check # Aktivieren/deaktivierenopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

Bewährte Methoden

• Halten Sie Handler schnell. Hooks werden während der Befehlsverarbeitung ausgeführt. Starten Sie aufwendige Arbeiten nach dem Fire-and-Forget-Prinzip mit void processInBackground(event).
• Behandeln Sie Fehler kontrolliert. Umschließen Sie riskante Vorgänge mit try/catch; lösen Sie keine Ausnahme aus, damit andere Handler ausgeführt werden können.
• Filtern Sie Ereignisse frühzeitig. Kehren Sie sofort zurück, wenn der Ereignistyp oder die Aktion nicht relevant ist.
• Verwenden Sie spezifische Ereignisschlüssel. Bevorzugen Sie "events": ["command:new"] gegenüber "events": ["command"], um den Aufwand zu reduzieren.

Fehlerbehebung

Hook wird nicht erkannt

# Verzeichnisstruktur überprüfenls -la ~/.openclaw/hooks/my-hook/# Sollte Folgendes anzeigen: HOOK.md, handler.ts # Alle erkannten Hooks auflistenopenclaw hooks list

Hook ist nicht geeignet

openclaw hooks info my-hook

Prüfen Sie, ob Binärdateien (PATH), Umgebungsvariablen oder Konfigurationswerte fehlen oder ob Betriebssystemkompatibilität besteht.

Hook wird nicht ausgeführt

1. Überprüfen Sie, ob der Hook aktiviert ist: openclaw hooks list
2. Starten Sie Ihren Gateway-Prozess neu, damit die Hooks erneut geladen werden.
3. Prüfen Sie die Gateway-Protokolle: openclaw logs --follow | grep -i hook

Verwandte Themen

• CLI-Referenz: Hooks
• Webhooks
• Plugin-Hooks — prozessinterne Plugin-Lebenszyklus-Hooks
• Konfiguration