Hooks in OpenClaw: Den Agenten auf /new, /reset und andere Ereignisse reagieren lassen

Du tippst /new in den Chat, und die Sitzung beginnt von vorn. Ob ein Hook dabei tatsächlich gelaufen ist, zeigt dir sein Status allerdings nicht. In diesem Teil der Serie aktivierst du deshalb den mitgelieferten command-logger, löst ein Ereignis aus und prüfst den Eintrag, den der Hook dabei schreibt.

Interne Hooks sind laut OpenClaw kleine JavaScript- oder TypeScript-Handler. Sie laufen im Gateway-Prozess und reagieren auf Nachrichten- und Sitzungsereignisse, etwa um Sitzungskontext zu sichern oder Reset-Befehle zu protokollieren. Für häufige Aufgaben liefert OpenClaw fertige Hooks mit, ein eigenes Plugin brauchst du dafür nicht.

Interne Hooks richtig einordnen

OpenClaw trennt mehrere Automatisierungsflächen, die sich leicht verwechseln lassen:

Die Verwechslungsgefahr beginnt schon in der Konfiguration. hooks.internal steuert die internen Event-Handler, hooks.enabled dagegen den HTTP-Eingang. Auch message:received und message_received sind nicht dasselbe: message:received gehört zu den internen Hooks, message_received zu den typisierten Plugin-Hooks.

Interne Hooks laufen nicht in einer Sandbox. Nach Angaben von OpenClaw haben sie denselben Dateisystem-, Netzwerk- und Umgebungszugriff wie der Gateway-Prozess. Lies den Code deshalb vor der Aktivierung, vor allem bei Hooks aus einem Workspace oder einem heruntergeladenen Paket.

command-logger aktivieren und verifizieren

OpenClaw empfiehlt command-logger als Einstieg. Der Hook braucht keine zusätzlichen Binaries und keine Modellaufrufe. Sein Ergebnis landet in einer Datei, die du direkt lesen kannst.

Arbeite auf dem Gateway-Host, mit demselben Profil und derselben Konfiguration wie das laufende Gateway. Verschaffe dir einen Überblick und schalte den Hook ein:

openclaw hooks list
openclaw hooks info command-logger
openclaw hooks enable command-logger

Hat deine Konfiguration mehrere Agenten und keinen impliziten Owner, hängst du bei den Hook-Befehlen --agent <id> an. Im standardmäßigen hybriden Reload-Modus übernimmt das Gateway die Änderung ohne Neustart.

Ist der Reload-Modus ausgeschaltet, prüfe vor einem Neustart, ob noch Agentenläufe aktiv sind. Der sichere Neustart wartet begrenzt auf laufende Arbeit und kann nach Ablauf des Zeitlimits dennoch fortfahren:

openclaw gateway restart --safe

Ein einfaches openclaw gateway restart ist ebenfalls gültig, startet den Dienst aber ohne diese OpenClaw-bewusste Deferral-Prüfung neu. Nutze diese Variante nur, wenn du das bewusst möchtest.

Sende nun als autorisierter Nutzer /new oder /reset in einer Unterhaltung, die du gefahrlos zurücksetzen kannst. Danach schaust du auf dem Gateway-Host ins Log:

tail -n 5 ~/.openclaw/logs/commands.log

Du suchst eine neue JSON-Zeile mit "action":"new" oder "action":"reset", einem aktuellen Zeitstempel und dem sessionKey genau dieser Unterhaltung. Nutzt du ein eigenes State-Verzeichnis, liegt die Datei unter <stateDir>/logs/commands.log.

Der Eintrag ist der konkrete Nachweis, dass der Handler für dieses Ereignis gelaufen ist. openclaw hooks check allein reicht dafür nicht aus.

Laut OpenClaw enthält das Log Sitzungs- und Absenderkennungen. Wenn du diese Daten nicht behalten willst, schaltest du den Hook nach dem Test wieder ab:

openclaw hooks disable command-logger

Wenn der Logeintrag fehlt

Bleibt die Datei aus oder enthält sie keine passende JSON-Zeile, prüfst du die Verarbeitung in der Reihenfolge, in der ein Hook vom Verzeichnis bis zum Ereignis gelangt.

Kontrolliere zunächst, dass du auf dem Host des laufenden Gateways und mit dessen Profil arbeitest. Bei mehreren Agenten muss außerdem die richtige Agent-ID gewählt sein. Der JSON-Bericht zeigt unter anderem die ausgewerteten Verzeichnisse:

openclaw hooks list --json --agent <id>

Vergleiche workspaceDir und managedHooksDir mit dem erwarteten Workspace und State-Verzeichnis. Ohne mehrere Agenten kannst du --agent <id> weglassen. Stimmen Host, Profil oder Agent nicht, untersuchst du sonst ein anderes Hook-Inventar als das laufende Gateway.

Prüfe danach Erkennung, Metadaten und Anforderungen:

openclaw hooks info command-logger --agent <id>
openclaw hooks list --verbose --agent <id>

Fehlt command-logger vollständig, untersuche die ausgewerteten Verzeichnisse und den verwendeten OpenClaw-Stand. Erscheint er mit einem blockedReason, behebe die dort genannte fehlende Anforderung. Ein fehlendes deklariertes Event verhindert ebenfalls die Ladbarkeit.

Kontrolliere anschließend die aktive Gateway-Konfiguration. hooks.internal.enabled darf interne Hooks nicht abschalten. Bei einer Namensauswahl muss command-logger ausgewählt sein; ein Eintrag unter hooks.internal.entries.command-logger darf nicht mit enabled: false deaktiviert sein. Wie die JSON5-Konfiguration aufgebaut ist, zeigt der Artikel zur Gateway-Konfiguration.

Beobachte nun die laufenden Gateway-Logs:

openclaw logs --follow

Achte auf Import- oder Exportfehler, Boundary-Fehler, unbekannte Events und Meldungen wie Hook error [command:new]. Ein positiver Statusbericht schließt solche Laufzeitfehler nicht aus.

Löse während der Logbeobachtung als autorisierter Nutzer erneut exakt /new oder /reset in der vorgesehenen Unterhaltung aus. Gewöhnlicher Chattext erzeugt kein command:new-Event. Prüfe danach wieder <stateDir>/logs/commands.log. So kannst du unterscheiden, ob der Hook nicht entdeckt, durch Anforderungen blockiert, nicht ausgewählt, beim Import gescheitert oder lediglich nicht ausgelöst worden ist.

Bereit heißt nicht aktiviert oder ausgeführt

Die CLI-Felder ready, eligible und loadable beschreiben laut OpenClaw die auswertbaren Hook-Metadaten, erfüllte Anforderungen und eine vorhandene Deklaration von Events. Sie bestätigen weder den Hauptschalter hooks.internal.enabled noch die Auswahl des Hook-Namens.

Aktivierung und Auswahl bilden eine eigene Stufe. Danach muss das laufende Gateway das richtige Inventar laden, das Modul erfolgreich importieren und den Handler für seine deklarierten Events registrieren. Auch diese Schritte werden durch ready, eligible oder loadable nicht bestätigt.

Die Ausführung ist nochmals getrennt: Ein geladener und registrierter Handler kann ungenutzt bleiben, solange das passende Ereignis nicht eintritt. Deshalb prüfst du nach einer Änderung den hookspezifischen Nebeneffekt, beim command-logger also die neue JSON-Zeile.

Beim Reload bleibt diese Trennung wichtig. Laut Dokumentation bleiben bisherige Handler aktiv, wenn ein neu ausgewählter Handler nicht geladen werden kann. Die Konfiguration kann dann geändert sein, während das Gateway noch mit dem vorherigen Handler arbeitet. Bereits laufende Events enden mit ihrer bisherigen Auswahl; nachfolgende Events verwenden die neue Auswahl. gateway:startup wird durch einen Reload nicht erneut ausgelöst.

Wo die Konfiguration tatsächlich greift

Läuft dein Gateway auf einem anderen Rechner, landest du schnell in einer Falle. Nach Angaben von OpenClaw fragen hooks list, hooks info und hooks check das Inventar des ausgewählten Gateways ab und zeigen dir damit den entfernten Zustand.

hooks enable und hooks disable ändern dagegen immer die lokale Konfiguration und schicken nichts per RPC an ein entferntes Gateway. Wer vom Laptop aus aktiviert, ändert nur die Konfiguration auf dem Laptop; das entfernte Gateway bleibt unverändert. Ein konfiguriertes Remote-Gateway oder ein explizites OPENCLAW_GATEWAY_URL fällt bei einem Fehler auch nicht auf lokale Hooks zurück. Aktiviere und deaktiviere den Hook deshalb direkt auf dem Gateway-Host.

Ähnlich leicht missversteht man --agent <id>. Die Option wählt den Workspace, den du prüfst. Eine eigene Hook-Registry pro Agent gibt es nicht, denn der Eintrag hooks.internal.entries.<hookKey> gilt global. Soll ein Handler nur für einen bestimmten Agenten oder eine bestimmte Sitzung reagieren, muss er die Eventdaten selbst filtern.

Hooks, die zu einem Plugin gehören, erscheinen in hooks list als plugin:<id>. Du schaltest sie über das zugehörige Plugin ein und aus, nicht mit openclaw hooks enable oder openclaw hooks disable.

Handler kurz und begrenzt halten

Für eigene Handler lohnt ein Blick auf das Ausführungsmodell. Laut OpenClaw laufen die Handler eines Events nacheinander. Der Dispatcher wartet auf jeden Handler, protokolliert geworfene Fehler und fährt mit dem nächsten fort. Eine Prioritätsoption für Directory-Hooks gibt es nicht.

Verschiedene Events können sich überschneiden. Zugleich gibt es keinen allgemeinen Timeout oder ein Abbruchsignal. Auch eine dauerhafte Warteschlange, automatische Wiederholungen und eine Exactly-once-Garantie fehlen. Startet das Gateway neu oder endet der Prozess, kann laufende Arbeit verloren gehen.

Warte deshalb auf die Arbeit, die zum Handler gehört, und setze Netzwerkaufrufen einen Timeout. Begrenze Datenmengen und gestalte wiederholbare Operationen idempotent. Ein void doHeavyWork(event) entzieht die ausgelagerte Arbeit der Fehlerbehandlung des Dispatchers und kann länger leben als Sitzung oder Prozess.

Filtere unpassende Events möglichst früh aus. Nachrichteninhalte, komplette Konfigurationen und Zugangsdaten gehören nicht ins Log. Speichere nur die Angaben, die der Nebeneffekt benötigt. Schütze die Ausgabedateien und lege eine Aufbewahrungsdauer fest.

Aufgaben mit eigenem Job-Lebenszyklus gehören in eine Automation oder einen eigenen Dienst. Wie du zeit- und ereignisgesteuerte Abläufe dafür einrichtest, erklärt das Tutorial zu Cron-Jobs, Heartbeats und Automationen. Langlebige Timer, Watcher, Sockets und Clients sind in einem Plugin-Dienst mit geregeltem Shutdown besser aufgehoben.

Kernpunkte

Lies den Code, bevor du einen Hook aktivierst. Ändere die Konfiguration auf dem Host, auf dem das Gateway läuft, und prüfe dort Profil, Agent und Namensauswahl. Statusfelder beschreiben Metadaten und Voraussetzungen, aber keine erfolgreiche Aktivierung, keinen Import und keine Ausführung. Verlässlich ist der konkrete Nebeneffekt: beim command-logger eine passende JSON-Zeile für das autorisiert ausgelöste /new- oder /reset-Ereignis.