/new, /reset, /stop, sessiecompactie, de levenscyclus van de Gateway en de berichtenstroom. Ze worden in mappen gedetecteerd en beheerd met openclaw hooks. De Gateway laadt interne hooks pas nadat je hooks hebt ingeschakeld of ten minste één hookvermelding, hookpakket, verouderde handler of extra hookmap hebt geconfigureerd.
OpenClaw heeft twee soorten hooks:
- Interne hooks (deze pagina): worden binnen de Gateway uitgevoerd wanneer agentgebeurtenissen plaatsvinden.
- Webhooks: externe HTTP-eindpunten waarmee andere systemen werk in OpenClaw kunnen activeren. Zie Webhooks.
openclaw hooks list toont zowel zelfstandige hooks als door plugins beheerde hooks (weergegeven als plugin:<id>).
Kies het juiste uitbreidingspunt
OpenClaw heeft verschillende uitbreidingspunten die op elkaar lijken, maar verschillende problemen oplossen:
Gebruik interne hooks voor automatisering die zich gedraagt als een kleine geïnstalleerde integratie. Gebruik getypeerde pluginhooks wanneer je controle over de runtimelevenscyclus nodig hebt.
Snel aan de slag
Gebeurtenistypen
Hooks abonneren zich op een specifieke sleutel uit deze tabel, of op alleen een familienaam (command, session, agent, gateway, message) om elke actie
in die familie te ontvangen. De kern van OpenClaw zendt niets anders uit, dus elke andere naam is vrijwel
altijd een typefout waardoor de hook stilzwijgend inactief blijft (alleen een plugin die een
aangepaste gebeurtenis uitzendt, kan deze activeren). De hooklader registreert een waarschuwing voor zulke namen
(bijvoorbeeld command:nwe) en openclaw hooks info <name> markeert ze, zodat een
hook die nooit wordt uitgevoerd kan worden gediagnosticeerd.
Hooks schrijven
Hookstructuur
Elke hook is een map met twee bestanden:handler.ts, handler.js, index.ts of index.js zijn.
Indeling van HOOK.md
metadata.openclaw):
Handlerimplementatie
type, action, sessionKey, timestamp, messages en context (gebeurtenisspecifieke gegevens). Contexten van getypeerde pluginhooks voor agent- en toolhooks kunnen ook trace bevatten, een alleen-lezen, W3C-compatibele diagnostische traceercontext die plugins kunnen doorgeven aan gestructureerde logboeken voor OTEL-correlatie.
Tekenreeksen die aan event.messages worden toegevoegd, worden alleen teruggestuurd naar de chat voor
command:new en command:reset (gerouteerd als antwoord op het oorspronkelijke
gesprek) en voor session:compact:before / session:compact:after
(verzonden als statusmeldingen over Compaction). Alle andere gebeurtenissen, waaronder
command:stop, message:*, agent:bootstrap, session:patch en
gateway:*, negeren toegevoegde berichten.
Belangrijkste onderdelen van de gebeurteniscontext
Opdrachtgebeurtenissen (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.senderId, context.workspaceDir, context.cfg.
Opdrachtgebeurtenissen (command:stop): context.sessionEntry, context.sessionId, context.commandSource, context.senderId.
Berichtgebeurtenissen (message:received): context.from, context.content, context.channelId, context.media (geordende, voorbereide feiten over bijlagen), context.originalMedia plus context.mediaStagingPending wanneer externe media nog niet lokaal zijn voorbereid, en context.metadata (providerspecifieke gegevens, waaronder senderId, senderName, guildId). context.content geeft voor berichten die op opdrachten lijken de voorkeur aan een niet-lege opdrachttekst en valt vervolgens terug op de onbewerkte inkomende tekst en de algemene tekst; het bevat geen verrijking die alleen voor agents beschikbaar is, zoals threadgeschiedenis of linksamenvattingen. Verouderde media-aliassen binnen metadata zijn afgeschaft.
Berichtgebeurtenissen (message:sent): context.to, context.content, context.success, context.channelId, plus context.error wanneer het verzenden is mislukt.
Berichtgebeurtenissen (message:transcribed): context.transcript, context.from, context.channelId en context.media. context.mediaPath en context.mediaType blijven verouderde aliassen voor het eerste feit.
Berichtgebeurtenissen (message:preprocessed): context.bodyForAgent (uiteindelijke verrijkte tekst), context.from, context.channelId.
Bootstrapgebeurtenissen (agent:bootstrap): context.bootstrapFiles (wijzigbare reeks), context.agentId.
Gebeurtenissen voor sessiewijzigingen (session:patch): context.sessionEntry, context.patch (alleen gewijzigde velden), context.cfg. Alleen geprivilegieerde clients kunnen wijzigingsgebeurtenissen activeren; de context is een kloon, zodat handlers het actieve sessie-item niet kunnen wijzigen.
Compaction-gebeurtenissen: session:compact:before bevat messageCount, tokenCount. session:compact:after voegt compactedCount, summaryLength, tokensBefore, tokensAfter toe.
command:stop neemt waar dat de gebruiker /stop geeft; dit betreft annulering/de levenscyclus van de opdracht
en is geen poort voor het voltooien van de agent. Plugins die een
natuurlijk definitief antwoord moeten inspecteren en de agent om nog een verwerkingsronde willen vragen, moeten in plaats daarvan de getypeerde
pluginhook before_agent_finalize gebruiken. Zie Pluginhooks.
Gebeurtenissen in de levenscyclus van de Gateway: gateway:shutdown bevat reason en restartExpectedMs en wordt geactiveerd wanneer het afsluiten van de Gateway begint. gateway:pre-restart bevat dezelfde context, maar wordt alleen geactiveerd wanneer het afsluiten deel uitmaakt van een verwachte herstart en een eindige waarde voor restartExpectedMs wordt opgegeven. Tijdens het afsluiten wordt op elke levenscyclushook naar beste vermogen en gedurende een begrensde periode gewacht, zodat het afsluiten doorgaat als een handler vastloopt. Het standaardwachtbudget is 5 seconden voor gateway:shutdown en 10 seconden voor gateway:pre-restart.
Gebruik gateway:pre-restart voor korte herstartmeldingen terwijl kanalen nog beschikbaar zijn:
gateway:shutdown (of gateway:pre-restart) en de rest van de afsluitvolgorde activeert de Gateway ook een getypeerde pluginhook session_end voor elke sessie die nog actief was toen het proces stopte. De reason van de gebeurtenis is shutdown voor een gewone stop via SIGTERM/SIGINT en restart wanneer het sluiten is gepland als onderdeel van een verwachte herstart. Deze afhandeling is begrensd, zodat een trage session_end-handler het afsluiten van het proces niet kan blokkeren. Sessies die al zijn voltooid via vervangen / opnieuw instellen / verwijderen / Compaction worden overgeslagen om dubbele activering te voorkomen.
Hookdetectie
Hooks worden uit vier bronnen gedetecteerd:- Gebundelde hooks: meegeleverd met OpenClaw
- Pluginhooks: gebundeld in geïnstalleerde plugins; kunnen gebundelde hooks met dezelfde naam overschrijven
- Beheerde hooks:
~/.openclaw/hooks/(door de gebruiker geïnstalleerd, gedeeld tussen werkruimten); kunnen gebundelde hooks en pluginhooks overschrijven. Extra mappen uithooks.internal.load.extraDirshebben dezelfde prioriteit. - Werkruimtehooks:
<workspace>/hooks/(per agent, standaard uitgeschakeld totdat ze expliciet worden ingeschakeld)
openclaw hooks enable <name>, installeer een hookpakket of stel hooks.internal.enabled=true in om hiervoor te kiezen. Wanneer je één benoemde hook inschakelt, laadt de Gateway alleen de handler van die hook; hooks.internal.enabled=true, extra hookmappen en verouderde handlers schakelen brede detectie in.
Hookpakketten
Hookpakketten zijn npm-pakketten die hooks exporteren viaopenclaw.hooks in package.json. Installeer ze met:
openclaw hooks install en openclaw hooks update zijn verouderde aliassen voor openclaw plugins install / openclaw plugins update.
Gebundelde hooks
Schakel een gebundelde hook in:
Details van session-memory
Extraheert de laatste berichten van de gebruiker/assistent (standaard 15, configureerbaar methooks.internal.entries.session-memory.messages) en slaat ze op in <workspace>/memory/YYYY-MM-DD-HHMM.md met de lokale datum van de host. Het vastleggen van het geheugen wordt op de achtergrond uitgevoerd, zodat bevestigingen van /new en /reset niet worden vertraagd door het lezen van transcripten of het optioneel genereren van slugs. Stel hooks.internal.entries.session-memory.llmSlug: true in om beschrijvende slugs voor bestandsnamen te genereren en stel eventueel hooks.internal.entries.session-memory.model in op een geconfigureerde alias zoals sonnet, een kale model-ID bij de standaardprovider van de agent of een provider/model-verwijzing. Voor het genereren van slugs wordt het standaardmodel van de agent gebruikt wanneer model is weggelaten; als dit niet beschikbaar is, wordt teruggevallen op slugs met tijdstempels. Vereist dat workspace.dir is geconfigureerd.
Configuratie van bootstrap-extra-files
patterns en files worden geaccepteerd als aliassen van paths. Paden worden relatief ten opzichte van de werkruimte opgelost en moeten daarbinnen blijven. Alleen herkende bootstrapbasisnamen worden geladen (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).
Details van command-logger
Logt elke slashopdracht als een JSON-regel (tijdstempel, actie, sessiesleutel, afzender-ID, bron) naar~/.openclaw/logs/commands.log.
Details van compaction-notifier
Stuurt korte statusberichten naar het huidige gesprek wanneer OpenClaw begint en klaar is met het compact maken van het sessietranscript. Dit maakt lange beurten minder verwarrend in chatinterfaces, omdat de gebruiker kan zien dat de assistent de context samenvat en na de compactie doorgaat.Details van boot-md
VoertBOOT.md uit wanneer de Gateway wordt opgestart voor elk geconfigureerd agentbereik, als het bestand bestaat in de opgeloste werkruimte van die agent.
Pluginhooks
Plugins kunnen getypeerde hooks registreren via de Plugin SDK voor diepere integratie: toolaanroepen onderscheppen, prompts wijzigen, de berichtenstroom beheren en meer. Gebruik pluginhooks wanneer jebefore_tool_call, before_agent_reply,
before_install of andere levenscyclushooks binnen het proces nodig hebt.
Door plugins beheerde interne hooks zijn anders: ze nemen deel aan het grove
opdracht-/levenscyclusgebeurtenissensysteem van deze pagina en verschijnen in openclaw hooks list als
plugin:<id>. Gebruik deze voor neveneffecten en compatibiliteit met hookpakketten, niet
voor geordende middleware of beleidscontroles.
Zie Pluginhooks voor de volledige referentie voor pluginhooks.
Configuratie
requires.env (naast de procesomgeving), en handlers kunnen ze uit hun hookconfiguratie-item lezen:
De verouderde configuratie-indeling met de array
hooks.internal.handlers wordt nog steeds ondersteund voor achterwaartse compatibiliteit, maar nieuwe hooks moeten het op detectie gebaseerde systeem gebruiken.CLI-referentie
Aanbevolen werkwijzen
- Houd handlers snel. Hooks worden uitgevoerd tijdens de verwerking van opdrachten. Start zwaar werk zonder erop te wachten met
void processInBackground(event). - Handel fouten correct af. Plaats risicovolle bewerkingen in try/catch; werp geen fouten op, zodat andere handlers kunnen worden uitgevoerd.
- Filter gebeurtenissen vroegtijdig. Keer onmiddellijk terug als het gebeurtenistype/de actie niet relevant is.
- Gebruik specifieke gebeurtenissleutels. Geef de voorkeur aan
"events": ["command:new"]boven"events": ["command"]om overhead te verminderen.
Probleemoplossing
Hook niet gedetecteerd
Hook niet geschikt
Hook wordt niet uitgevoerd
- Controleer of de hook is ingeschakeld:
openclaw hooks list - Start je Gateway-proces opnieuw zodat de hooks opnieuw worden geladen.
- Controleer de Gateway-logboeken:
openclaw logs --follow | grep -i hook
Gerelateerd
- CLI-referentie: hooks
- Webhooks
- Pluginhooks — levenscyclushooks voor plugins binnen het proces
- Configuratie