Contextengine

Een contextengine bepaalt hoe OpenClaw voor elke uitvoering modelcontext opbouwt: welke berichten worden opgenomen, hoe oudere geschiedenis wordt samengevat en hoe context over subagentgrenzen heen wordt beheerd.

OpenClaw wordt geleverd met een ingebouwde legacy-engine en gebruikt deze standaard. Installeer en selecteer alleen een plugin-engine als je ander gedrag wilt voor samenstelling, Compaction of ophalen uit eerdere sessies.

Snel aan de slag

openclaw doctor# of inspecteer de configuratie rechtstreeks:cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

openclaw plugins install @martian-engineering/lossless-claw

openclaw plugins install -l ./my-context-engine

// openclaw.json{  plugins: {    slots: {      contextEngine: "lossless-claw", // moet overeenkomen met de geregistreerde engine-id van de plugin    },    entries: {      "lossless-claw": {        enabled: true,        // Pluginspecifieke configuratie komt hier (zie de documentatie van de plugin)      },    },  },}

Hoe het werkt

Telkens wanneer OpenClaw een modelprompt uitvoert, neemt de contextengine deel op vier punten in de levenscyclus:

Engines kunnen ook een optionele methode maintain() implementeren voor transcriptonderhoud (veilige herschrijvingen via runtimeContext.rewriteTranscriptEntries()) na het opstarten, een geslaagde beurt of Compaction. Stel info.turnMaintenanceMode: "background" in om dit als uitgesteld werk uit te voeren in plaats van het antwoord te blokkeren.

Voor de meegeleverde Codex-harness zonder ACP past OpenClaw dezelfde levenscyclus toe door de samengestelde context te projecteren in de Codex-ontwikkelaarsinstructies en de prompt van de huidige beurt. Codex blijft zelf verantwoordelijk voor zijn eigen threadgeschiedenis en ingebouwde compactor.

Levenscyclus van subagents (optioneel)

OpenClaw roept twee optionele levenscyclushooks voor subagents aan:

Toevoeging aan de systeemprompt

De methode assemble kan een tekenreeks systemPromptAddition retourneren. OpenClaw voegt deze vóór de systeemprompt voor de uitvoering in. Zo kunnen engines dynamische richtlijnen voor herinneringen, ophaalinstructies of contextbewuste aanwijzingen invoegen zonder statische werkruimtebestanden te vereisen.

De legacy-engine

De ingebouwde legacy-engine behoudt het oorspronkelijke gedrag van OpenClaw:

• Opnemen: doet niets (de sessiebeheerder verwerkt het permanent opslaan van berichten rechtstreeks).
• Samenstellen: doorvoer (de bestaande pijplijn voor opschonen → valideren → begrenzen in de runtime verzorgt de contextsamenstelling).
• Comprimeren: delegeert naar de ingebouwde samenvattende Compaction, die één samenvatting van oudere berichten maakt en recente berichten intact laat.
• Na de beurt: doet niets.

De legacy-engine registreert geen tools en levert geen systemPromptAddition.

Wanneer geen plugins.slots.contextEngine is ingesteld (of wanneer deze op "legacy" is ingesteld), wordt deze engine automatisch gebruikt.

Plugin-engines

Een plugin kan via de plugin-API een contextengine registreren:

 export default function register(api) {  api.registerContextEngine("my-engine", (ctx) => ({    info: {      id: "my-engine",      name: "My Context Engine",      ownsCompaction: true,    },     async ingest({ sessionId, message, isHeartbeat }) {      // Sla het bericht op in je gegevensopslag      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // Retourneer berichten die binnen het budget passen      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // Vat oudere context samen      return { ok: true, compacted: true };    },  }));}

De factory ctx bevat optionele waarden config, agentDir en workspaceDir, zodat plugins status per agent of per werkruimte kunnen initialiseren vóór de eerste levenscyclusaanroep. Vóór een niet-legacy aanroep van assemble() voltooit de host de geregistreerde asynchrone voorbereiding van de geheugenprompt. De synchrone helper buildMemorySystemPromptAddition(...) leest die onveranderlijke momentopname van de uitvoering; geef de aangeleverde context voor tools, citaten, agent en sessie ongewijzigd door.

Schakel deze vervolgens in de configuratie in:

{  plugins: {    slots: {      contextEngine: "my-engine",    },    entries: {      "my-engine": {        enabled: true,      },    },  },}

De ContextEngine-interface

Vereiste leden:

assemble retourneert een AssembleResult met:

compact retourneert een CompactResult. Wanneer Compaction de actieve sessie-identiteit wijzigt, identificeert result.sessionTarget (een getypeerde ContextEngineSessionTarget die de sessie-identiteit en het opslagbereik bevat) de opvolgende sessie die bij de volgende nieuwe poging of beurt moet worden gebruikt; result.sessionId weerspiegelt de opvolgende id.

Optionele leden:

Runtime-instellingen

Levenscyclushooks die binnen OpenClaw worden uitgevoerd, ontvangen een optioneel runtimeSettings-object. Dit is een geversioneerd, alleen-lezen intern API-oppervlak voor producent/consument: OpenClaw produceert het voor de geselecteerde contextengine en de contextengine gebruikt het binnen levenscyclushooks. Het wordt niet rechtstreeks aan gebruikers weergegeven en creëert geen afzonderlijk rapportageoppervlak.

• schemaVersion: momenteel 1
• runtime: OpenClaw-host, runtimemodus (normal, fallback of degraded) en optionele harness-/runtime-id's
• contextEngineSelection: geselecteerde contextengine-id en selectiebron
• executionHost: host-id en label voor het oppervlak dat de hook aanroept
• model: aangevraagd model, herleid model, provider en optionele modelfamilie
• limits: prompttokenbudget en maximaal aantal uitvoertokens indien bekend
• diagnostics: gesloten fallback- en degradatieredencodes indien bekend

Velden die onbekend kunnen zijn, worden weergegeven als null; discriminatorvelden zoals runtimemodus en selectiebron blijven niet-nullable. Oudere engines blijven compatibel: als een strikte verouderde engine runtimeSettings afwijst als een onbekende eigenschap, probeert OpenClaw de levenscyclusaanroep opnieuw zonder deze eigenschap, in plaats van de engine in quarantaine te plaatsen.

Hostvereisten

Contextengines kunnen vereisten voor hostmogelijkheden declareren via info.hostRequirements. OpenClaw controleert deze vereisten voordat de bewerking wordt gestart en sluit bij een fout met een beschrijvende foutmelding wanneer de geselecteerde runtime er niet aan kan voldoen.

Declareer voor agentruns assemble-before-prompt wanneer de engine de daadwerkelijke modelprompt moet beheren via assemble():

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Gebruik de native Codex- of ingebedde OpenClaw-runtime, of selecteer de verouderde contextengine.",    },  },}

Native Codex- en ingebedde OpenClaw-agentruns voldoen aan assemble-before-prompt. Generieke CLI-backends doen dat niet. Engines die dit vereisen, worden daarom afgewezen voordat het CLI-proces wordt gestart.

Foutisolatie

OpenClaw isoleert de geselecteerde pluginengine van het kernpad voor antwoorden. Als een niet-verouderde engine ontbreekt, de contractvalidatie niet doorstaat, een fout veroorzaakt tijdens het maken via de factory of een fout veroorzaakt vanuit een levenscyclusmethode, plaatst OpenClaw die engine voor het huidige Gateway-proces in quarantaine en schakelt contextenginewerk terug naar de ingebouwde engine legacy. De fout wordt samen met de mislukte bewerking vastgelegd, zodat de beheerder de plugin kan repareren, bijwerken of uitschakelen zonder dat de agent stilvalt.

Fouten in hostvereisten zijn anders: wanneer een engine declareert dat een runtime een vereiste mogelijkheid mist, sluit OpenClaw bij een fout voordat de run wordt gestart. Dit beschermt engines die de status zouden beschadigen als ze op een niet-ondersteunde host zouden draaien.

ownsCompaction

ownsCompaction bepaalt of de ingebouwde automatische Compaction tijdens een poging van de OpenClaw-runtime voor de run ingeschakeld blijft:

Dat betekent dat er twee geldige pluginpatronen zijn:

Een no-op compact() is onveilig voor een actieve niet-beherende engine, omdat deze het normale /compact-pad en het Compaction-pad voor herstel na overloop voor dat engineslot uitschakelt.

Configuratiereferentie

{  plugins: {    slots: {      // Selecteer de actieve contextengine. Standaard: "legacy".      // Stel dit in op een plugin-id om een pluginengine te gebruiken.      contextEngine: "legacy",    },  },}

Relatie met Compaction en geheugen

Tips

• Gebruik openclaw doctor om te controleren of je engine correct wordt geladen.
• Wanneer je van engine wisselt, behouden bestaande sessies hun huidige geschiedenis. De nieuwe engine neemt toekomstige runs over.
• Enginefouten worden vastgelegd en de geselecteerde pluginengine wordt voor het huidige Gateway-proces in quarantaine geplaatst. OpenClaw valt voor gebruikersbeurten terug op legacy, zodat antwoorden kunnen doorgaan, maar je moet de defecte plugin nog steeds repareren, bijwerken, uitschakelen of verwijderen.
• Gebruik voor ontwikkeling openclaw plugins install -l ./my-engine om zonder kopiëren een lokale pluginmap te koppelen.

Gerelateerd

• Compaction - lange gesprekken samenvatten
• Context - hoe context voor agentbeurten wordt opgebouwd
• Pluginarchitectuur - contextengineplugins registreren
• Pluginmanifest - velden van het pluginmanifest
• Plugins - overzicht van plugins