Kontext-Engine

Eine Context Engine steuert, wie OpenClaw bei jedem Lauf den Modellkontext erstellt: welche Nachrichten einbezogen werden, wie der ältere Verlauf zusammengefasst wird und wie der Kontext über Subagent-Grenzen hinweg verwaltet wird.

OpenClaw enthält eine integrierte legacy Engine und verwendet sie standardmäßig. Installieren und wählen Sie eine Plugin-Engine nur aus, wenn Sie ein anderes Zusammenstellungs-, Compaction- oder sitzungsübergreifendes Abrufverhalten wünschen.

Schnellstart

openclaw doctor# oder Konfiguration direkt prüfen: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", // muss mit der registrierten Engine-ID des Plugins übereinstimmen    },    entries: {      "lossless-claw": {        enabled: true,        // Plugin-spezifische Konfiguration wird hier eingefügt (siehe Dokumentation des Plugins)      },    },  },}

Funktionsweise

Bei jeder Ausführung eines Modell-Prompts durch OpenClaw ist die Context Engine an vier Punkten des Lebenszyklus beteiligt:

Engines können außerdem eine optionale Methode maintain() für die Transkriptpflege implementieren (sichere Umschreibungen über runtimeContext.rewriteTranscriptEntries()) – nach dem Bootstrap, einem erfolgreichen Durchlauf oder einer Compaction. Setzen Sie info.turnMaintenanceMode: "background", um sie als verzögerte Arbeit auszuführen, statt die Antwort zu blockieren.

Für das mitgelieferte Nicht-ACP-Codex-Harness wendet OpenClaw denselben Lebenszyklus an, indem der zusammengestellte Kontext in Codex-Entwickleranweisungen und den Prompt des aktuellen Durchlaufs projiziert wird. Codex verwaltet weiterhin seinen nativen Thread-Verlauf und seinen nativen Komprimierer.

Subagent-Lebenszyklus (optional)

OpenClaw ruft zwei optionale Lebenszyklus-Hooks für Subagents auf:

Ergänzung des System-Prompts

Die Methode assemble kann eine Zeichenfolge systemPromptAddition zurückgeben. OpenClaw stellt diese dem System-Prompt für den Lauf voran. Dadurch können Engines dynamische Abrufhinweise, Anweisungen zum Retrieval oder kontextbezogene Hinweise einfügen, ohne statische Workspace-Dateien zu benötigen.

Die Legacy-Engine

Die integrierte Engine legacy bewahrt das ursprüngliche Verhalten von OpenClaw:

• Aufnahme: keine Aktion (der Sitzungsmanager übernimmt die Nachrichtenpersistenz direkt).
• Zusammenstellung: unveränderte Weitergabe (die vorhandene Pipeline aus Bereinigung → Validierung → Begrenzung in der Runtime übernimmt die Kontextzusammenstellung).
• Compaction: delegiert an die integrierte zusammenfassende Compaction, die eine einzige Zusammenfassung älterer Nachrichten erstellt und aktuelle Nachrichten unverändert beibehält.
• Nach dem Durchlauf: keine Aktion.

Die Legacy-Engine registriert keine Tools und stellt keine systemPromptAddition bereit.

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

Plugin-Engines

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

 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 }) {      // Speichern Sie die Nachricht in Ihrem Datenspeicher      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // Geben Sie Nachrichten zurück, die in das Budget passen      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // Fassen Sie älteren Kontext zusammen      return { ok: true, compacted: true };    },  }));}

Die Factory ctx enthält optionale Werte für config, agentDir und workspaceDir, damit Plugins einen agenten- oder workspacebezogenen Zustand vor dem ersten Lebenszyklusaufruf initialisieren können. Vor einem Nicht-Legacy-Aufruf von assemble() schließt der Host die registrierte asynchrone Vorbereitung des Speicher-Prompts ab. Der synchrone Helper buildMemorySystemPromptAddition(...) liest diesen unveränderlichen Snapshot des Laufs; geben Sie den bereitgestellten Tool-, Zitations-, Agenten- und Sitzungskontext unverändert weiter.

Aktivieren Sie die Engine anschließend in der Konfiguration:

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

Die ContextEngine-Schnittstelle

Erforderliche Elemente:

assemble gibt eine AssembleResult mit Folgendem zurück:

compact gibt eine CompactResult zurück. Wenn die Compaction die aktive Sitzungs- identität ändert, identifiziert result.sessionTarget (eine typisierte ContextEngineSessionTarget, die die Sitzungsidentität und den Speicherbereich enthält) die Nachfolgesitzung, die beim nächsten Wiederholungsversuch oder Durchlauf verwendet werden muss; result.sessionId spiegelt die Nachfolger-ID wider.

Optionale Elemente:

Runtime-Einstellungen

Lebenszyklus-Hooks, die innerhalb von OpenClaw ausgeführt werden, erhalten ein optionales Objekt runtimeSettings. Es handelt sich um eine versionierte, schreibgeschützte interne Producer-/Consumer-API-Oberfläche: OpenClaw erzeugt sie für die ausgewählte Context Engine, und die Context Engine verwendet sie innerhalb der Lebenszyklus-Hooks. Sie wird Benutzern nicht direkt angezeigt und erstellt keine dedizierte Berichtsoberfläche.

• schemaVersion: derzeit 1
• runtime: OpenClaw-Host, Laufzeitmodus (normal, fallback oder degraded) und optionale Harness-/Laufzeit-IDs
• contextEngineSelection: ID der ausgewählten Kontext-Engine und Auswahlquelle
• executionHost: Host-ID und Bezeichnung für die Oberfläche, die den Hook aufruft
• model: angefordertes Modell, aufgelöstes Modell, Provider und optionale Modellfamilie
• limits: Prompt-Tokenbudget und maximale Anzahl von Ausgabe-Token, sofern bekannt
• diagnostics: geschlossene Fallback- und Einschränkungsgrundcodes, sofern bekannt

Felder, die unbekannt sein können, werden als null dargestellt; Diskriminatorfelder wie Laufzeitmodus und Auswahlquelle bleiben nicht nullable. Ältere Engines bleiben kompatibel: Wenn eine strikt validierende Legacy-Engine runtimeSettings als unbekannte Eigenschaft ablehnt, wiederholt OpenClaw den Lebenszyklusaufruf ohne sie, statt die Engine unter Quarantäne zu stellen.

Host-Anforderungen

Kontext-Engines können unter info.hostRequirements Anforderungen an Host-Fähigkeiten deklarieren. OpenClaw prüft diese Anforderungen vor Beginn des Vorgangs und bricht mit einer aussagekräftigen Fehlermeldung ab, wenn die ausgewählte Laufzeit sie nicht erfüllen kann.

Deklarieren Sie für Agent-Ausführungen assemble-before-prompt, wenn die Engine den tatsächlichen Modell-Prompt über assemble() steuern muss:

info: {  id: "my-context-engine",  name: "Meine Kontext-Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Verwenden Sie die native Codex- oder eingebettete OpenClaw-Laufzeit oder wählen Sie die Legacy-Kontext-Engine aus.",    },  },}

Native Codex- und eingebettete OpenClaw-Agent-Ausführungen erfüllen assemble-before-prompt. Generische CLI-Backends erfüllen diese Fähigkeit nicht. Engines, die sie voraussetzen, werden daher abgelehnt, bevor der CLI-Prozess startet.

Fehlerisolierung

OpenClaw isoliert die ausgewählte Plugin-Engine vom Kern-Antwortpfad. Wenn eine Nicht-Legacy-Engine fehlt, die Vertragsvalidierung nicht besteht, während der Factory- Erstellung eine Ausnahme auslöst oder in einer Lebenszyklusmethode eine Ausnahme auslöst, stellt OpenClaw diese Engine für den aktuellen Gateway-Prozess unter Quarantäne und stuft die Kontext-Engine-Vorgänge auf die integrierte Engine legacy herab. Der Fehler wird zusammen mit dem fehlgeschlagenen Vorgang protokolliert, damit die zuständige Person das Plugin reparieren, aktualisieren oder deaktivieren kann, ohne dass der Agent keine Antworten mehr ausgibt.

Fehler bei Host-Anforderungen werden anders behandelt: Wenn eine Engine deklariert, dass einer Laufzeit eine erforderliche Fähigkeit fehlt, bricht OpenClaw vor Beginn der Ausführung ab. Dies schützt Engines, die bei Ausführung auf einem nicht unterstützten Host den Zustand beschädigen würden.

ownsCompaction

ownsCompaction steuert, ob die integrierte automatische Compaction innerhalb eines Versuchs der OpenClaw-Laufzeit für die Ausführung aktiviert bleibt:

Daraus ergeben sich zwei gültige Plugin-Muster:

Eine wirkungslose compact()-Implementierung ist für eine aktive, nicht eigenständig zuständige Engine unsicher, da sie den normalen /compact- und Überlaufwiederherstellungs-Compaction-Pfad für diesen Engine-Slot deaktiviert.

Konfigurationsreferenz

{  plugins: {    slots: {      // Aktive Kontext-Engine auswählen. Standard: "legacy".      // Auf eine Plugin-ID setzen, um eine Plugin-Engine zu verwenden.      contextEngine: "legacy",    },  },}

Beziehung zu Compaction und Speicher

Tipps

• Verwenden Sie openclaw doctor, um zu überprüfen, ob Ihre Engine korrekt geladen wird.
• Beim Wechsel der Engine behalten bestehende Sitzungen ihren aktuellen Verlauf bei. Die neue Engine übernimmt zukünftige Ausführungen.
• Engine-Fehler werden protokolliert, und die ausgewählte Plugin-Engine wird für den aktuellen Gateway-Prozess unter Quarantäne gestellt. OpenClaw greift bei Benutzerinteraktionen auf legacy zurück, damit Antworten weiterhin möglich sind. Sie sollten das fehlerhafte Plugin dennoch reparieren, aktualisieren, deaktivieren oder deinstallieren.
• Verwenden Sie für die Entwicklung openclaw plugins install -l ./my-engine, um ein lokales Plugin-Verzeichnis ohne Kopieren zu verknüpfen.

Verwandte Themen

• Compaction – Zusammenfassung langer Unterhaltungen
• Kontext – Aufbau des Kontexts für Agent-Interaktionen
• Plugin-Architektur – Registrierung von Kontext-Engine-Plugins
• Plugin-Manifest – Felder des Plugin-Manifests
• Plugins – Plugin-Übersicht