OpenClaw Context Engine: Eigene Logik in 3 Schritten

Kennst du das Problem? Dein Agent startet brillant, aber nach ein paar Runden verliert er den Faden oder die Token-Kosten schießen durch die Decke. Das Management von Context ist oft der größte Flaschenhals, wenn du komplexe Workflows baust.

Eine Context Engine steuert genau das: Sie entscheidet, wie OpenClaw den Model-Context für jeden Run aufbaut. Sie legt fest, welche Nachrichten einbezogen werden, wie die Historie zusammengefasst wird und wie der Context über Subagent-Grenzen hinweg verwaltet wird. OpenClaw wird mit einer eingebauten legacy Engine ausgeliefert, aber Plugins können alternative Engines registrieren, um den gesamten Lifecycle zu übernehmen.

Schnellstart

Prüfe zuerst, welche Engine gerade aktiv ist:

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

Installation eines Context-Engine-Plugins

Context-Engine-Plugins werden wie jedes andere OpenClaw-Plugin installiert. Installiere es zuerst und wähle die Engine dann im Slot aus:

# Install from npm
openclaw plugins install @martian-engineering/lossless-claw

# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine

Aktiviere dann das Plugin und wähle es als aktive Engine in deiner Konfiguration aus:

{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

Starte das Gateway nach der Installation und Konfiguration neu.

Um zur eingebauten Engine zurückzukehren, setze contextEngine auf "legacy" (oder entferne den Key komplett — "legacy" ist der Standard).

Funktionsweise

Jedes Mal, wenn OpenClaw einen Model-Prompt ausführt, greift die Context Engine an vier Punkten im Lifecycle ein:

Ingest — wird aufgerufen, wenn eine neue Nachricht zur Session hinzugefügt wird. Die Engine kann die Nachricht in ihrem eigenen Datenspeicher speichern oder indizieren.
Assemble — wird vor jedem Model-Run aufgerufen. Die Engine gibt einen geordneten Satz von Nachrichten (und optional eine systemPromptAddition) zurück, die in das Token-Budget passen.
Compact — wird aufgerufen, wenn das Context-Window voll ist oder wenn du /compact ausführst. Die Engine fasst die ältere Historie zusammen, um Platz zu schaffen.
After turn — wird nach Abschluss eines Runs aufgerufen. Die Engine kann den Status persistieren, eine Hintergrund-Compaction auslösen oder Indizes aktualisieren.

Subagent-Lifecycle (optional)

OpenClaw ruft derzeit einen Hook für den Subagent-Lifecycle auf:

onSubagentEnded — Aufräumen, wenn eine Subagent-Session abgeschlossen oder entfernt wird.

Der Hook prepareSubagentSpawn ist Teil des Interface für die zukünftige Verwendung, wird aber derzeit noch nicht von der Runtime aufgerufen.

System Prompt Addition

Die assemble-Methode kann einen systemPromptAddition-String zurückgeben. OpenClaw stellt diesen dem System-Prompt für den Run voran. So können Engines dynamische Recall-Anweisungen, Retrieval-Instruktionen oder kontextbezogene Hinweise einfügen, ohne dass statische Workspace-Dateien nötig sind.

Die Legacy-Engine

Die eingebaute legacy Engine behält das ursprüngliche Verhalten von OpenClaw bei:

Ingest: No-op (der Session-Manager kümmert sich direkt um die Nachrichten-Persistenz).
Assemble: Pass-through (die bestehende Sanitize → Validate → Limit Pipeline in der Runtime übernimmt die Context-Zusammenstellung).
Compact: Delegiert an die eingebaute Summarization-Compaction, die eine einzelne Zusammenfassung älterer Nachrichten erstellt und aktuelle Nachrichten intakt lässt.
After turn: No-op.

Die Legacy-Engine registriert keine Tools und bietet keine systemPromptAddition an.

Wenn kein plugins.slots.contextEngine gesetzt ist (oder auf "legacy" steht), wird diese Engine automatisch verwendet.

Plugin-Engines

Ein Plugin kann eine Context Engine über die Plugin-API registrieren:

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },
  }));
}

Aktiviere sie dann in der Konfiguration:

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

Das ContextEngine-Interface

Erforderliche Member:

Member	Art	Zweck
`info`	Property	Engine-ID, Name, Version und ob sie Compaction selbst verwaltet
`ingest(params)`	Methode	Speichert eine einzelne Nachricht
`assemble(params)`	Methode	Baut den Context für einen Model-Run (gibt `AssembleResult` zurück)
`compact(params)`	Methode	Fasst den Context zusammen oder reduziert ihn

assemble gibt ein AssembleResult zurück mit:

messages — die geordneten Nachrichten, die an das Model gesendet werden.
estimatedTokens (erforderlich, number) — die Schätzung der Engine über die gesamten Token im zusammengestellten Context. OpenClaw nutzt dies für Entscheidungen über Compaction-Schwellenwerte und Diagnose-Berichte.
systemPromptAddition (optional, string) — wird dem System-Prompt vorangestellt.

Optionale Member:

Member	Art	Zweck
`bootstrap(params)`	Methode	Initialisiert den Engine-Status für eine Session. Wird einmal aufgerufen, wenn die Engine eine Session zum ersten Mal sieht.
`ingestBatch(params)`	Methode	Verarbeitet einen abgeschlossenen Turn als Batch. Wird nach einem Run mit allen Nachrichten dieses Turns aufgerufen.
`afterTurn(params)`	Methode	Lifecycle-Arbeit nach dem Run (Status persistieren, Hintergrund-Compaction auslösen).
`prepareSubagentSpawn(params)`	Methode	Richtet den gemeinsamen Status für eine Child-Session ein.
`onSubagentEnded(params)`	Methode	Aufräumen, nachdem ein Subagent beendet wurde.
`dispose()`	Methode	Gibt Ressourcen frei. Wird beim Shutdown des Gateways oder beim Reload des Plugins aufgerufen — nicht pro Session.

ownsCompaction

ownsCompaction steuert, ob die eingebaute Auto-Compaction von Pi für den Run aktiviert bleibt:

true — die Engine verwaltet das Compaction-Verhalten selbst. OpenClaw deaktiviert die eingebaute Auto-Compaction für diesen Run. Die compact()-Implementierung der Engine ist verantwortlich für /compact, Overflow-Recovery und jede proaktive Compaction in afterTurn().
false oder nicht gesetzt — die eingebaute Auto-Compaction kann während der Prompt-Ausführung weiterhin laufen, aber die compact()-Methode der aktiven Engine wird trotzdem für /compact und Overflow-Recovery aufgerufen.

ownsCompaction: false bedeutet nicht, dass OpenClaw automatisch auf den Compaction-Pfad der Legacy-Engine zurückfällt.

Das bedeutet, es gibt zwei valide Plugin-Muster:

Owning mode — implementiere deinen eigenen Compaction-Algorithmus und setze ownsCompaction: true.
Delegating mode — setze ownsCompaction: false und lass compact() die Funktion delegateCompactionToRuntime(...) aus openclaw/plugin-sdk/core aufrufen, um das Standard-Verhalten zu nutzen.

Eine No-op compact()-Methode ist für eine aktive Engine im Non-Owning-Mode unsicher, da sie den normalen Pfad für /compact und Overflow-Recovery blockiert.

Konfigurations-Referenz

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}

Der Slot ist zur Laufzeit exklusiv — es wird nur eine registrierte Context Engine für einen bestimmten Run oder eine Compaction-Operation aufgelöst. Andere aktivierte Plugins vom Typ kind: "context-engine" können zwar geladen werden, aber plugins.slots.contextEngine bestimmt, welche Engine OpenClaw tatsächlich nutzt.

Verhältnis zu Compaction und Memory

Compaction ist eine der Aufgaben der Context Engine. Die Legacy-Engine delegiert dies an die eingebaute Summarization. Plugin-Engines können eigene Strategien wie DAG-Summaries oder Vector-Retrieval implementieren.
Memory-Plugins (plugins.slots.memory) sind getrennt von Context Engines. Memory-Plugins bieten Suche und Retrieval; Context Engines steuern, was das Model tatsächlich sieht. Sie können zusammenarbeiten — eine Context Engine könnte Daten eines Memory-Plugins beim Assembly nutzen.
Session Pruning (das Kürzen alter Tool-Ergebnisse im Speicher) läuft immer, unabhängig davon, welche Context Engine aktiv ist.

Tipps

Nutze openclaw doctor, um zu verifizieren, dass deine Engine korrekt geladen wird.
Wenn du die Engine wechselst, behalten bestehende Sessions ihre bisherige Historie. Die neue Engine übernimmt ab den zukünftigen Runs.
Engine-Fehler werden geloggt und in der Diagnose angezeigt. Wenn ein Plugin die Registrierung verpatzt oder die ID nicht aufgelöst werden kann, gibt es keinen automatischen Fallback; Runs schlagen fehl, bis du die Konfiguration korrigierst.
Nutze für die Entwicklung openclaw plugins install -l ./my-engine, um ein lokales Verzeichnis zu verlinken, ohne Dateien zu kopieren.

Nächste Schritte

Context — wie Context für Agent-Turns aufgebaut wird
Plugin-Architektur — Registrierung von Context-Engine-Plugins
Compaction — Zusammenfassung langer Konversationen

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.