Hooks

Hooks sind kleine Skripte, die ausgeführt werden, wenn innerhalb des Gateway etwas passiert. Sie können aus Verzeichnissen erkannt und mit openclaw hooks geprüft werden. Der Gateway lädt interne Hooks erst, nachdem Sie Hooks aktiviert oder mindestens einen Hook-Eintrag, ein Hook-Pack, einen Legacy-Handler oder ein zusätzliches Hook-Verzeichnis konfiguriert haben.

Es gibt zwei Arten von Hooks in OpenClaw:

• Interne Hooks (diese Seite): werden innerhalb des Gateway ausgeführt, wenn Agent-Ereignisse ausgelöst werden, etwa /new, /reset, /stop oder Lebenszyklusereignisse.
• Webhooks: externe HTTP-Endpunkte, mit denen 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 an.

Die richtige Oberfläche wählen

OpenClaw hat mehrere Erweiterungsoberflächen, die ähnlich wirken, aber unterschiedliche Probleme lösen:

Verwenden Sie interne Hooks, wenn Sie Automatisierung möchten, die sich wie eine kleine installierte Integration verhält. Verwenden Sie typisierte Plugin-Hooks, wenn Sie Laufzeitsteuerung für den Lebenszyklus benötigen.

Schnellstart

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

Ereignistypen

Hooks schreiben

Hook-Struktur

Jeder Hook ist ein Verzeichnis mit zwei Dateien:

my-hook/├── HOOK.md          # Metadata + documentation└── handler.ts       # Handler implementation

Format von HOOK.md

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

Metadatenfelder (metadata.openclaw):

Handler-Implementierung

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

Jedes Ereignis enthält: type, action, sessionKey, timestamp, messages (Antworten nur auf antwortfähigen Oberflächen hier per Push hinzufügen) und context (ereignisspezifische Daten). Agent- und Tool-Plugin-Hook-Kontexte können außerdem trace enthalten, einen schreibgeschützten W3C-kompatiblen Diagnose-Trace-Kontext, den Plugins für die OTEL-Korrelation an strukturierte Logs übergeben können.

event.messages wird nur auf antwortfähigen Oberflächen wie command:* und message:received automatisch zugestellt. Reine Lebenszyklusereignisse wie agent:bootstrap, session:*, gateway:* oder message:sent haben keinen Antwortkanal und ignorieren per Push hinzugefügte Nachrichten.

Wichtige Ereigniskontexte

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

Nachrichtenereignisse (message:received): context.from, context.content, context.channelId, context.metadata (providerspezifische Daten einschließlich senderId, senderName, guildId). context.content bevorzugt bei befehlsartigen Nachrichten einen nicht leeren Befehlstext, fällt dann auf den rohen eingehenden Text und den generischen Text zurück; es enthält keine rein agentbezogene Anreicherung wie Thread-Verlauf oder Link-Zusammenfassungen.

Nachrichtenereignisse (message:sent): context.to, context.content, context.success, context.channelId.

Nachrichtenereignisse (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.

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

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

Sitzungs-Patch-Ereignisse (session:patch): context.sessionEntry, context.patch (nur geänderte Felder), context.cfg. Nur privilegierte Clients können Patch-Ereignisse auslösen.

Compaction-Ereignisse: session:compact:before enthält messageCount, tokenCount. session:compact:after ergänzt compactedCount, summaryLength, tokensBefore, tokensAfter.

command:stop beobachtet, dass der Benutzer /stop ausgibt; es gehört zum Abbruch-/Befehlslebenszyklus, nicht zu einem Gate für die Agent-Finalisierung. Plugins, die eine natürliche Abschlussantwort prüfen und den Agent um einen weiteren Durchlauf bitten 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 aber nur ausgelöst, wenn das Herunterfahren Teil eines erwarteten Neustarts ist und ein endlicher Wert für restartExpectedMs bereitgestellt wird. Während des Herunterfahrens ist jedes Warten auf Lebenszyklus-Hooks nach bestem Aufwand und begrenzt, sodass das Herunterfahren fortgesetzt wird, wenn ein Handler hängen bleibt. Das standardmäßige Wartebudget beträgt 5 Sekunden für gateway:shutdown und 10 Sekunden für gateway:pre-restart.

Verwenden Sie gateway:pre-restart für kurze Neustarthinweise, solange 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 restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,  ]);}

Zwischen dem Ereignis gateway:shutdown (oder gateway:pre-restart) und dem Rest der Herunterfahrsequenz löst der Gateway außerdem für jede Sitzung, die beim Stoppen des Prozesses noch aktiv war, einen typisierten session_end-Plugin-Hook aus. Der reason des Ereignisses ist shutdown bei einem einfachen SIGTERM/SIGINT-Stopp und restart, wenn das Schließen als Teil eines erwarteten Neustarts geplant wurde. Dieses Leeren ist begrenzt, sodass ein langsamer session_end-Handler den Prozessausstieg nicht blockieren kann; Sitzungen, die bereits durch Ersetzen / Zurücksetzen / Löschen / Compaction finalisiert wurden, werden übersprungen, um doppelte Auslösungen zu vermeiden.

Hook-Erkennung

Hooks werden aus diesen Verzeichnissen erkannt, in der Reihenfolge zunehmender Überschreibungspriorität:

1. Gebündelte Hooks: werden mit OpenClaw ausgeliefert
2. Plugin-Hooks: Hooks, die in installierten Plugins gebündelt sind
3. Verwaltete Hooks: ~/.openclaw/hooks/ (benutzerinstalliert, workspaceübergreifend geteilt). Zusätzliche Verzeichnisse aus hooks.internal.load.extraDirs teilen diese Priorität.
4. Workspace-Hooks: <workspace>/hooks/ (pro Agent, standardmäßig deaktiviert, bis sie ausdrücklich aktiviert werden)

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

Der Gateway überspringt beim Start die Erkennung interner Hooks, bis interne Hooks konfiguriert sind. Aktivieren Sie einen gebündelten oder verwalteten Hook mit openclaw hooks enable <name>, installieren Sie ein Hook-Pack oder setzen Sie hooks.internal.enabled=true, um sich anzumelden. Wenn Sie einen benannten Hook aktivieren, lädt der Gateway nur den Handler dieses Hooks; hooks.internal.enabled=true, zusätzliche Hook-Verzeichnisse und Legacy-Handler melden eine breite Erkennung an.

Hook-Packs

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

openclaw plugins install <path-or-spec>

npm-Spezifikationen sind ausschließlich Registry-Spezifikationen (Paketname plus optionale exakte Version oder dist-tag). Git-/URL-/Dateispezifikationen und Semver-Bereiche werden abgelehnt.

Gebündelte Hooks

Aktivieren Sie einen beliebigen gebündelten Hook:

openclaw hooks enable <hook-name>

Details zu session-memory

Extrahiert die letzten 15 Benutzer-/Assistentennachrichten und speichert sie unter <workspace>/memory/YYYY-MM-DD-HHMM.md mit dem lokalen Datum des Hosts. Die Speichererfassung läuft im Hintergrund, sodass Bestätigungen für /new und /reset nicht durch das Lesen des Transkripts oder die optionale Slug-Erzeugung verzögert werden. Setzen Sie hooks.internal.entries.session-memory.llmSlug: true, um beschreibende Dateinamen-Slugs mit dem konfigurierten Modell zu erzeugen. Erfordert, dass workspace.dir konfiguriert ist.

Konfiguration für bootstrap-extra-files

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

Pfade werden relativ zum Arbeitsbereich aufgelöst. Es werden nur erkannte Bootstrap-Basisnamen geladen (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).

Details zu command-logger

Protokolliert jeden Slash-Befehl 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 abschließt. Dadurch werden lange Turns auf Chat-Oberflächen weniger verwirrend, weil der Benutzer sehen kann, dass der Assistent den Kontext zusammenfasst und nach der Compaction fortfährt.

Details zu boot-md

Führt BOOT.md aus dem aktiven Arbeitsbereich aus, wenn der Gateway startet.

Plugin-Hooks

Plugins können typisierte Hooks über das Plugin SDK für tiefere Integration registrieren: Abfangen von Tool-Aufrufen, Ändern von Prompts, Steuern des Nachrichtenflusses und mehr. Verwenden Sie Plugin-Hooks, wenn Sie before_tool_call, before_agent_reply, before_install oder andere prozessinterne Lifecycle-Hooks benötigen.

Von Plugins verwaltete interne Hooks sind anders: Sie nehmen am groben Befehls-/Lifecycle-Ereignissystem dieser Seite teil und erscheinen in openclaw hooks list als plugin:<id>. Verwenden Sie diese für Nebeneffekte und Kompatibilität mit Hook-Paketen, nicht für geordnete Middleware oder Policy-Gates.

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

Konfiguration

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

Umgebungsvariablen pro Hook:

{  "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

# List all hooks (add --eligible, --verbose, or --json)openclaw hooks list # Show detailed info about a hookopenclaw hooks info <hook-name> # Show eligibility summaryopenclaw hooks check # Enable/disableopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

Best Practices

• Halten Sie Handler schnell. Hooks laufen während der Befehlsverarbeitung. Starten Sie aufwendige Arbeit nach dem Fire-and-forget-Prinzip mit void processInBackground(event).
• Behandeln Sie Fehler elegant. Umschließen Sie riskante Operationen mit try/catch; werfen Sie keine Fehler, damit andere Handler ausgeführt werden können.
• Filtern Sie Ereignisse früh. Kehren Sie sofort zurück, wenn Ereignistyp oder Aktion nicht relevant ist.
• Verwenden Sie spezifische Ereignisschlüssel. Bevorzugen Sie "events": ["command:new"] gegenüber "events": ["command"], um Overhead zu reduzieren.

Fehlerbehebung

Hook nicht gefunden

# Verify directory structurels -la ~/.openclaw/hooks/my-hook/# Should show: HOOK.md, handler.ts # List all discovered hooksopenclaw hooks list

Hook nicht berechtigt

openclaw hooks info my-hook

Prüfen Sie auf fehlende Binärdateien (PATH), Umgebungsvariablen, Konfigurationswerte oder OS-Kompatibilität.

Hook wird nicht ausgeführt

1. Prüfen Sie, ob der Hook aktiviert ist: openclaw hooks list
2. Starten Sie Ihren Gateway-Prozess neu, damit Hooks neu geladen werden.
3. Prüfen Sie die Gateway-Protokolle: ./scripts/clawlog.sh | grep hook

Verwandte Themen

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