Kontext-Engine

Eine Kontext-Engine steuert, wie OpenClaw für jeden Durchlauf Modellkontext erstellt: welche Nachrichten einbezogen werden, wie ältere Historie zusammengefasst wird und wie Kontext über Subagent-Grenzen hinweg verwaltet wird.

OpenClaw wird mit einer integrierten legacy-Engine ausgeliefert und verwendet sie standardmäßig - die meisten Nutzer müssen dies nie ändern. Installieren und wählen Sie eine Plugin-Engine nur dann aus, wenn Sie ein anderes Verhalten für Zusammenstellung, Compaction oder sitzungsübergreifenden Abruf wünschen.

Schnellstart

openclaw doctor# or inspect config directly: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", // must match the plugin's registered engine id    },    entries: {      "lossless-claw": {        enabled: true,        // Plugin-specific config goes here (see the plugin's docs)      },    },  },}

Funktionsweise

Jedes Mal, wenn OpenClaw einen Modell-Prompt ausführt, beteiligt sich die Kontext-Engine an vier Lebenszykluspunkten:

Für den gebündelten Nicht-ACP-Codex-Harness wendet OpenClaw denselben Lebenszyklus an, indem der zusammengestellte Kontext in Codex-Developer-Anweisungen und den aktuellen Turn-Prompt projiziert wird. Codex verwaltet weiterhin seine native Thread-Historie und seinen nativen Compactor.

Subagent-Lebenszyklus (optional)

OpenClaw ruft zwei optionale Subagent-Lebenszyklus-Hooks auf:

System-Prompt-Ergänzung

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

Die Legacy-Engine

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

• Ingest: keine Operation (der Sitzungsmanager übernimmt die Nachrichtenpersistenz direkt).
• Assemble: Durchleitung (die bestehende Pipeline sanitize → validate → limit in der Runtime übernimmt die Kontextzusammenstellung).
• Compact: delegiert an die integrierte Zusammenfassungs-Compaction, die eine einzelne Zusammenfassung älterer Nachrichten erstellt und aktuelle Nachrichten unverändert lässt.
• After turn: keine Operation.

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

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

Plugin-Engines

Ein Plugin kann über die Plugin-API eine Kontext-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 }) {      // Store the message in your data store      return { ingested: true };    },     async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {      // Return messages that fit the budget      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,        }),      };    },     async compact({ sessionId, force }) {      // Summarize older context      return { ok: true, compacted: true };    },  }));}

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

Aktivieren Sie sie dann in der Konfiguration:

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

Die ContextEngine-Schnittstelle

Erforderliche Member:

assemble gibt ein AssembleResult zurück mit:

compact gibt ein CompactResult zurück. Wenn Compaction das aktive Transkript rotiert, identifizieren result.sessionId und result.sessionFile die Nachfolgesitzung, die der nächste Retry oder Turn verwenden muss.

Optionale Member:

Runtime-Einstellungen

Lebenszyklus-Hooks, die innerhalb von OpenClaw laufen, erhalten ein optionales runtimeSettings-Objekt. Es ist eine versionierte, schreibgeschützte interne Producer-/Consumer-API-Oberfläche: OpenClaw erzeugt sie für die ausgewählte Kontext-Engine, und die Kontext-Engine konsumiert sie innerhalb von Lebenszyklus-Hooks. Sie wird Nutzern nicht direkt angezeigt und erzeugt keine dedizierte Reporting-Oberfläche.

• schemaVersion: derzeit 1
• runtime: OpenClaw-Host, Runtime-Modus (normal, fallback oder degraded) und optionale Harness-/Runtime-IDs
• contextEngineSelection: ausgewählte Kontext-Engine-ID und Auswahlquelle
• executionHost: Host-ID und Label für die Oberfläche, die den Hook aufruft
• model: angefordertes Modell, aufgelöstes Modell, Provider und optionale Modellfamilie
• limits: Prompt-Token-Budget und maximale Ausgabe-Tokens, wenn bekannt
• diagnostics: geschlossene Fallback- und Degraded-Reason-Codes, wenn bekannt

Felder, die unbekannt sein können, werden als null dargestellt; Diskriminatorfelder wie Runtime-Modus und Auswahlquelle bleiben nicht-nullbar. Ältere Engines bleiben kompatibel: Wenn eine strikte Legacy-Engine runtimeSettings als unbekannte Eigenschaft ablehnt, wiederholt OpenClaw den Lebenszyklusaufruf ohne diese Eigenschaft, statt die Engine in Quarantäne zu setzen.

Host-Anforderungen

Kontext-Engines können Host-Capability-Anforderungen in info.hostRequirements deklarieren. OpenClaw prüft diese Anforderungen, bevor die Operation gestartet wird, und schlägt geschlossen mit einem beschreibenden Fehler fehl, wenn die ausgewählte Runtime sie nicht erfüllen kann.

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

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use the native Codex or OpenClaw embedded runtime, or select the legacy context engine.",    },  },}

Native Codex- und OpenClaw-Embedded-Agent-Durchläufe erfüllen assemble-before-prompt. Generische CLI-Backends tun dies nicht, daher werden Engines, die dies erfordern, abgelehnt, bevor der CLI-Prozess startet.

Fehlerisolation

OpenClaw isoliert die ausgewählte Plugin-Engine vom Kernpfad für Antworten. Wenn eine nicht veraltete Engine fehlt, die Vertragsvalidierung nicht besteht, während der Factory- Erstellung eine Ausnahme auslöst oder aus einer Lebenszyklusmethode eine Ausnahme auslöst, stellt OpenClaw diese Engine für den aktuellen Gateway-Prozess unter Quarantäne und stuft Context-Engine-Arbeit auf die integrierte legacy-Engine herab. Der Fehler wird mit der fehlgeschlagenen Operation protokolliert, damit der Betreiber das Plugin reparieren, aktualisieren oder deaktivieren kann, ohne dass der Agent stumm wird.

Fehler bei Host-Anforderungen sind anders: Wenn eine Engine erklärt, dass einer Runtime eine erforderliche Fähigkeit fehlt, schlägt OpenClaw vor dem Start des Runs geschlossen fehl. Das schützt Engines, die den Zustand beschädigen würden, wenn sie in einem nicht unterstützten Host ausgeführt würden.

ownsCompaction

ownsCompaction steuert, ob die integrierte In-Attempt-Auto-Compaction der OpenClaw-Runtime für den Run aktiviert bleibt:

Das bedeutet, dass es zwei gültige Plugin-Muster gibt:

Ein compact() ohne Wirkung ist für eine aktive, nicht besitzende Engine unsicher, weil es den normalen /compact- und Überlaufwiederherstellungs-Compaction-Pfad für diesen Engine-Slot deaktiviert.

Konfigurationsreferenz

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

Beziehung zu Compaction und Memory

Tipps

• Verwenden Sie openclaw doctor, um zu prüfen, ob Ihre Engine korrekt geladen wird.
• Wenn Sie Engines wechseln, werden bestehende Sessions mit ihrer aktuellen Historie fortgesetzt. Die neue Engine übernimmt künftige Runs.
• Engine-Fehler werden protokolliert, und die ausgewählte Plugin-Engine wird für den aktuellen Gateway-Prozess unter Quarantäne gestellt. OpenClaw fällt für Benutzer-Turns auf legacy zurück, damit Antworten fortgesetzt werden können, aber Sie sollten das defekte Plugin trotzdem 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
• Context - wie Kontext für Agent-Turns aufgebaut wird
• Plugin Architecture - Registrierung von Context-Engine-Plugins
• Plugin manifest - Plugin-Manifestfelder
• Plugins - Plugin-Übersicht