Motore di contesto

Un motore di contesto controlla come OpenClaw costruisce il contesto del modello per ogni esecuzione: quali messaggi includere, come riassumere la cronologia meno recente e come gestire il contesto attraverso i confini dei subagent.

OpenClaw include un motore legacy integrato e lo usa per impostazione predefinita: la maggior parte degli utenti non deve mai modificarlo. Installa e seleziona un motore Plugin solo quando desideri un comportamento diverso per assemblaggio, Compaction o richiamo tra sessioni.

Avvio rapido

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)      },    },  },}

Come funziona

Ogni volta che OpenClaw esegue un prompt del modello, il motore di contesto partecipa in quattro punti del ciclo di vita:

Per l'harness Codex non ACP in bundle, OpenClaw applica lo stesso ciclo di vita proiettando il contesto assemblato nelle istruzioni per sviluppatori di Codex e nel prompt del turno corrente. Codex mantiene comunque la proprietà della propria cronologia nativa dei thread e del compattatore nativo.

Ciclo di vita dei subagent (facoltativo)

OpenClaw chiama due hook facoltativi del ciclo di vita dei subagent:

Aggiunta al prompt di sistema

Il metodo assemble può restituire una stringa systemPromptAddition. OpenClaw la antepone al prompt di sistema dell'esecuzione. Questo permette ai motori di iniettare indicazioni dinamiche di richiamo, istruzioni di recupero o suggerimenti consapevoli del contesto senza richiedere file statici dell'area di lavoro.

Il motore legacy

Il motore legacy integrato preserva il comportamento originale di OpenClaw:

• Acquisizione: nessuna operazione (il gestore di sessione gestisce direttamente la persistenza dei messaggi).
• Assemblaggio: pass-through (la pipeline esistente sanitize → validate → limit nel runtime gestisce l'assemblaggio del contesto).
• Compact: delega alla Compaction di riepilogo integrata, che crea un unico riepilogo dei messaggi meno recenti e mantiene intatti i messaggi recenti.
• Dopo il turno: nessuna operazione.

Il motore legacy non registra strumenti né fornisce un systemPromptAddition.

Quando plugins.slots.contextEngine non è impostato (oppure è impostato su "legacy"), questo motore viene usato automaticamente.

Motori Plugin

Un Plugin può registrare un motore di contesto usando l'API Plugin:

 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 };    },  }));}

La factory ctx include valori facoltativi config, agentDir e workspaceDir così i Plugin possono inizializzare lo stato per agente o per area di lavoro prima dell'esecuzione del primo hook del ciclo di vita.

Poi abilitalo nella configurazione:

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

L'interfaccia ContextEngine

Membri obbligatori:

assemble restituisce un AssembleResult con:

compact restituisce un CompactResult. Quando la Compaction ruota la trascrizione attiva, result.sessionId e result.sessionFile identificano la sessione successiva che il prossimo tentativo o turno deve usare.

Membri facoltativi:

Impostazioni di runtime

Gli hook del ciclo di vita eseguiti all'interno di OpenClaw ricevono un oggetto runtimeSettings facoltativo. È una superficie API interna produttore/consumatore, versionata e di sola lettura: OpenClaw la produce per il motore di contesto selezionato e il motore di contesto la consuma all'interno degli hook del ciclo di vita. Non viene resa direttamente agli utenti e non crea una superficie di reporting dedicata.

• schemaVersion: attualmente 1
• runtime: host OpenClaw, modalità runtime (normal, fallback o degraded) e id harness/runtime facoltativi
• contextEngineSelection: id del motore di contesto selezionato e origine della selezione
• executionHost: id host ed etichetta per la superficie che invoca l'hook
• model: modello richiesto, modello risolto, provider e famiglia di modelli facoltativa
• limits: budget di token del prompt e token massimi di output quando noti
• diagnostics: codici chiusi di fallback e motivo degraded quando noti

I campi che possono essere sconosciuti sono rappresentati come null; i campi discriminatore come la modalità runtime e l'origine della selezione restano non nullable. I motori più vecchi rimangono compatibili: se un motore legacy rigoroso rifiuta runtimeSettings come proprietà sconosciuta, OpenClaw riprova la chiamata del ciclo di vita senza di essa invece di mettere il motore in quarantena.

Requisiti dell'host

I motori di contesto possono dichiarare requisiti di capacità dell'host su info.hostRequirements. OpenClaw verifica questi requisiti prima di avviare l'operazione e fallisce in modo chiuso con un errore descrittivo quando il runtime selezionato non può soddisfarli.

Per le esecuzioni degli agenti, dichiara assemble-before-prompt quando il motore deve controllare il prompt effettivo del modello tramite assemble():

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.",    },  },}

Le esecuzioni agente native di Codex e OpenClaw embedded soddisfano assemble-before-prompt. I backend CLI generici no, quindi i motori che lo richiedono vengono rifiutati prima dell'avvio del processo CLI.

Isolamento degli errori

OpenClaw isola il motore Plugin selezionato dal percorso di risposta principale. Se un motore non legacy manca, non supera la convalida del contratto, genera un'eccezione durante la creazione della factory o genera un'eccezione da un metodo del ciclo di vita, OpenClaw mette in quarantena quel motore per il processo Gateway corrente e degrada il lavoro del motore di contesto al motore legacy integrato. L'errore viene registrato con l'operazione non riuscita, così l'operatore può riparare, aggiornare o disabilitare il Plugin senza che l'agente resti silenzioso.

Gli errori dei requisiti dell'host sono diversi: quando un motore dichiara che un runtime non dispone di una capacità richiesta, OpenClaw si arresta in modo fail-closed prima di avviare l'esecuzione. Questo protegge i motori che corromperebbero lo stato se venissero eseguiti in un host non supportato.

ownsCompaction

ownsCompaction controlla se l'auto-compaction integrata nel runtime OpenClaw durante il tentativo resta abilitata per l'esecuzione:

Questo significa che esistono due pattern Plugin validi:

Un compact() no-op non è sicuro per un motore attivo che non possiede la compaction, perché disabilita il normale percorso di compaction /compact e di recupero dall'overflow per quello slot del motore.

Riferimento di configurazione

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

Relazione con compaction e memoria

Suggerimenti

• Usa openclaw doctor per verificare che il tuo motore venga caricato correttamente.
• Se cambi motore, le sessioni esistenti continuano con la loro cronologia corrente. Il nuovo motore prende il controllo per le esecuzioni future.
• Gli errori del motore vengono registrati e il motore Plugin selezionato viene messo in quarantena per il processo Gateway corrente. OpenClaw ripiega su legacy per i turni utente così le risposte possono continuare, ma dovresti comunque riparare, aggiornare, disabilitare o disinstallare il Plugin rotto.
• Per lo sviluppo, usa openclaw plugins install -l ./my-engine per collegare una directory Plugin locale senza copiarla.

Correlati

• Compaction - riepilogo delle conversazioni lunghe
• Contesto - come viene costruito il contesto per i turni dell'agente
• Architettura dei Plugin - registrazione dei Plugin motore di contesto
• Manifest Plugin - campi del manifest Plugin
• Plugin - panoramica dei Plugin