Hooks in OpenClaw

Hooks sind die Druckplatten von OpenClaw. Irgendetwas passiert im Gateway, die Platte wird ausgelöst und ein kleines Skript reagiert sofort.

Genau das macht sie interessant. Du bekommst ereignisgesteuerte Automatisierung, ohne gleich ein ganzes Plugin zu bauen, und ohne jede Kleinigkeit in den Haupt-Prompt deines Agenten zu stopfen.

Laut offizieller OpenClaw-Doku sind Hooks kleine Skripte, die aus gebündelten, verwalteten, pluginbasierten und Workspace-Verzeichnissen entdeckt werden. Sie bleiben inaktiv, bis du Hooks aktivierst oder mindestens einen Hook-Eintrag konfigurierst. Das ist eine vernünftige Leitplanke. Eventgesteuerter Kleber ist nützlich. Eventgesteuerter Kleber überall ruiniert Wochenenden.

Wofür Hooks eigentlich gedacht sind

Hooks sind am stärksten, wenn du eine enge Reaktion auf ein klares Event brauchst.

• etwas mitschreiben oder protokollieren, wenn ein Command läuft
• zusätzliche Bootstrap-Dateien einfügen, bevor eine Agenten-Session startet
• vor einem geplanten Restart eine kurze sichtbare Warnung senden
• Speicher sichern, wenn eine Session zurückgesetzt wird
• leichtgewichtig auf eingehende oder ausgehende Nachrichten reagieren

Das Grundmuster ist simpel: Ein Event feuert, eine kleine Logik läuft, dann geht das System weiter. Wenn das langweilig klingt, ist das gut. Langweilige Infrastruktur ist oft die Infrastruktur, die Produktion überlebt.

Was Hooks auslösen kann

Die offizielle Hooks-Doku teilt Events in ein paar Familien auf.

Command-Events

Hooks können auf command:new, command:reset, command:stop oder das allgemeine command-Event hören. Das ist nützlich, wenn ein Slash-Command Spuren hinterlassen, Kontext sichern oder eine kleine Nebenaktion auslösen soll.

Message-Events

Du kannst Hooks an message:received, message:transcribed, message:preprocessed und message:sent hängen. Dadurch sind Hooks gut für leichtgewichtige Audits, Message-Shaping oder Benachrichtigungen rund um Kanalverkehr.

Session- und Agent-Lebenszyklus

Hooks können auch vor und nach Compaction reagieren, wenn Session-Eigenschaften geändert werden, und während des Agent-Bootstraps. Das sind die Events, mit denen Operatoren die Laufzeit sauber halten können, ohne jeden Agenten per Hand umzubauen.

Gateway-Lebenszyklus

gateway:startup, gateway:shutdown und gateway:pre-restart zählen, wenn die Maschine selbst ein wenig Zeremonie braucht. Eine kurze Restart-Warnung oder eine BOOT.md-Aktion gehört hierhin und nicht in irgendeinen zufälligen Gesprächsprompt.

Gute Hook-Anwendungsfälle

Die Doku bringt gebündelte Beispiele mit und daran sieht man ziemlich klar, wofür Hooks gedacht sind.

Session-Memory sichern

Der gebündelte session-memory-Hook speichert aktuellen Session-Kontext, wenn /new oder /reset passiert. Das ist ein typischer Hook-Job: klein, ereignisgebunden und leichter zu verstehen als ein größeres Plugin.

Bootstrap anpassen

Der Hook bootstrap-extra-files fügt zusätzliche Workspace-Dateien beim Agent-Bootstrap ein. Wenn du ein Monorepo oder mehrere Packages betreibst, ist das ein sauberer Ort für Zusatzkontext, ohne deine Standarddateien in eine Rumpelschublade zu verwandeln.

Operatives Logging

Der command-logger-Hook schreibt Command-Events in ein zentrales Log. Genau für solche Audit-Spuren sind Hooks stark, weil die Aktion schmal und der Trigger eindeutig ist.

Restart-Hinweise

Das Event gateway:pre-restart ist ein gutes Beispiel dafür, wo Hooks elegant wirken. Ein Hook kann Menschen warnen, solange Kanäle noch leben, statt sie rätseln zu lassen, warum der Assistent kurz still geworden ist.

Warum Hooks nicht einfach nur kleine Plugins sind

Dieser Unterschied zählt. Hooks sind die schnelle Reaktionsschicht. Plugins sind die tiefere Integrationsschicht.

Wenn du Dinge wie Tool-Interception, Prompt-Shaping, Install-Verhalten oder wiederverwendbare paketierte Logik mit breiterem Lifecycle brauchst, ist das Plugin-System die bessere Wahl. Wenn du nur brauchst: "Wenn dieses Event passiert, führe dieses kleine Skript aus", dann reichen Hooks meistens.

Der schnelle Test ist: Wenn das Verhalten als Zweierordner mit HOOK.md und handler.ts albern wirkt, bist du wahrscheinlich schon aus dem Hook-Territorium raus.

Wie ein Hook aufgebaut ist

OpenClaw erwartet ein kleines Verzeichnis mit Metadaten und Handler.

my-hook/
├── HOOK.md
└── handler.ts

Die Metadaten definieren Hook-Name, Beschreibung, Events und Anforderungen. Der Handler bekommt das Event-Payload und kann reagieren, loggen oder eine sichtbare Nachricht an den Nutzer anhängen.

---
name: restart-warning
description: "Warn before a planned gateway restart"
metadata:
  { "openclaw": { "emoji": "⚠️", "events": ["gateway:pre-restart"] } }
---

export default async function handler(event) {
  if (event.type !== "gateway" || event.action !== "pre-restart") return;
  event.messages.push("Gateway restart expected soon. Save your work if needed.");
}

Genau so solltest du daran denken. Kleine Einheit, expliziter Trigger, schmale Nebenwirkung.

Wie du Hooks prüfst und aktivierst

Die CLI-Seite ist absichtlich klein. Du listest, prüfst, inspizierst und aktivierst.

openclaw hooks list
openclaw hooks info session-memory
openclaw hooks check
openclaw hooks enable session-memory

Die Doku erwähnt noch ein wichtiges Detail: Workspace-Hooks sind standardmäßig deaktiviert, bis du sie explizit aktivierst. Das ist ein gesundes Default, weil zufällige Hook-Ordner so nicht heimlich Produktionsverhalten werden.

Das echte Risiko: fragile Hook-Ketten

Hooks kippen dann um, wenn Menschen sie wie eine heimliche Workflow-Engine behandeln.

Ein Hook setzt eine Datei. Ein anderer Hook erwartet diese Datei. Ein dritter Hook liest sie und sendet eine Nachricht. Dann vergisst jemand, welches Event zuerst feuert, ein Restart landet mitten drin und plötzlich debuggst du unsichtbare Rohrleitungen um 23:40 Uhr. Das ist keine Automatisierung. Das ist eine Schatzsuche mit schlechterem Licht.

Die größten Fehlerbilder sind:

• mehrere Hooks mit undokumentierter Reihenfolgeabhängigkeit
• Business-Logik, die sich in Event-Reaktionen versteckt
• Nebenwirkungen, die schwer zu beobachten oder zu testen sind
• Hooks, die so groß werden, dass sie längst ein Plugin oder TaskFlow-Job sein sollten

Wie Hooks wartbar bleiben

Kleine Hooks altern gut. Clevere Hook-Systeme nicht.

• Halte einen Hook bei einem klaren Event-Job. Wenn du dafür ein Diagramm brauchst, ist er zu groß.
• Bevorzuge klare Namen. restart-warning ist besser als gateway-helper.
• Dokumentiere Anforderungen in HOOK.md. Fehlende Binaries, Env-Variablen oder Config sollten nie Ratespiel sein.
• Nutze Hooks für Reaktionen, nicht für Orchestrierung. Wenn Arbeit Waits, Retries und abhängige Stufen hat, gehört sie eher in TaskFlow.
• Nutze Plugins für tiefere Eingriffe. Wenn du typisierte Plugin-Hooks wie before_tool_call oder before_agent_finalize brauchst, hör auf so zu tun, als würde ein simpler Hook reichen.
• Mach Abschalten sicher. Ein guter Hook lässt sich deaktivieren, ohne den Rest des Systems zu brechen.

Wann Hooks die richtige Antwort sind

Wähle Hooks, wenn der Trigger schon innerhalb von OpenClaw liegt und die Reaktion klein, lokal und ereignisförmig ist.

• Nutze einen Hook für leichte Event-Reaktionen.
• Nutze Cron, wenn Zeit der Trigger ist.
• Nutze TaskFlow, wenn die Arbeit ein mehrstufiger dauerhafter Lauf wird.
• Nutze ein Plugin, wenn das Verhalten tiefe, wiederverwendbare Integration braucht.

Diese Sortierregel spart erstaunlich viel Schmerz. Hooks sind nicht die Stars der Show. Sie sind die sauberen Bühnenarbeiter, die im richtigen Moment genau einen Stuhl bewegen und dann wieder verschwinden.