Kontext-Engine

Eine Context Engine steuert, wie OpenClaw den Modellkontext für jeden Lauf 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 dann aus, wenn Sie ein anderes Verhalten bei Zusammenstellung, Compaction oder sitzungsübergreifendem Abruf 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 kommt hierhin (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 maintain()-Methode für die Transkriptpflege implementieren (sichere Umschreibungen über runtimeContext.rewriteTranscriptEntries()) – nach der Initialisierung, einem erfolgreichen Turn oder einer Compaction. Setzen Sie info.turnMaintenanceMode: "background", um sie als aufgeschobene Arbeit auszuführen, anstatt die Antwort zu blockieren.

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

Lebenszyklus von Subagents (optional)

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

Ergänzung des System-Prompts

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

Die legacy-Engine

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

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

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

Wenn plugins.slots.contextEngine nicht festgelegt (oder auf "legacy" gesetzt) ist, 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,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // Fassen Sie älteren Kontext zusammen      return { ok: true, compacted: true };    },  }));}

Der Factory-Kontext ctx enthält optionale Werte für config, agentDir und workspaceDir, damit Plugins den Zustand pro Agent oder Workspace initialisieren können, bevor der erste Lebenszyklus-Hook ausgeführt wird.

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 ein AssembleResult mit folgenden Elementen zurück:

compact gibt ein CompactResult zurück. Wenn die Compaction die Identität der aktiven Sitzung ändert, identifiziert result.sessionTarget (ein typisiertes ContextEngineSessionTarget, das die Sitzungsidentität und den Speicherbereich enthält) die Nachfolgesitzung, die beim nächsten Wiederholungsversuch oder Turn verwendet werden muss; result.sessionId spiegelt die Nachfolger-ID wider.

Optionale Elemente:

Laufzeiteinstellungen

Lebenszyklus-Hooks, die innerhalb von OpenClaw ausgeführt werden, erhalten ein optionales runtimeSettings-Objekt. Es ist eine versionierte, schreibgeschützte interne API-Oberfläche zwischen Produzent und Konsument: 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 erzeugt keine eigene Berichtsoberfläche.

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

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

Host-Anforderungen

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

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

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

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

Fehlerisolierung

OpenClaw isoliert die ausgewählte Plugin-Engine vom zentralen Antwortpfad. Wenn eine Nicht-Legacy-Engine fehlt, die Vertragsvalidierung nicht besteht, bei der Factory-Erstellung eine Ausnahme auslöst oder aus einer Lebenszyklusmethode heraus eine Ausnahme auslöst, stellt OpenClaw diese Engine für den aktuellen Gateway-Prozess unter Quarantäne und stuft die Kontext-Engine-Verarbeitung auf die integrierte legacy-Engine zurück. Der Fehler wird zusammen mit dem fehlgeschlagenen Vorgang protokolliert, sodass der Betreiber das Plugin reparieren, aktualisieren oder deaktivieren kann, ohne dass der Agent nicht mehr antwortet.

Fehler bei Host-Anforderungen werden anders behandelt: Wenn eine Engine deklariert, dass einer Laufzeit eine erforderliche Fähigkeit fehlt, bricht OpenClaw vor dem Start der Ausführung sicher ab. Dies schützt Engines, die ihren Zustand beschädigen würden, wenn sie auf einem nicht unterstützten Host ausgeführt 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 verantwortliche Engine unsicher, da sie den normalen Compaction-Pfad für /compact und die Wiederherstellung nach einem Überlauf 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.
• Wenn Sie die Engine wechseln, werden bestehende Sitzungen mit ihrem aktuellen Verlauf fortgesetzt. 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 fällt bei Benutzerinteraktionen auf legacy zurück, sodass weiterhin Antworten ausgegeben werden können. Sie sollten das defekte 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 – Überblick über Plugins