Motore di contesto

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

OpenClaw include un motore legacy integrato e lo utilizza per impostazione predefinita. Installare e selezionare un motore Plugin solo quando si desidera un comportamento diverso per l'assemblaggio, la Compaction o il recupero tra sessioni.

Avvio rapido

openclaw doctor# oppure ispezionare direttamente la configurazione: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", // deve corrispondere all'id del motore registrato dal plugin    },    entries: {      "lossless-claw": {        enabled: true,        // La configurazione specifica del plugin va inserita qui (consultare la documentazione del plugin)      },    },  },}

Funzionamento

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

I motori possono inoltre implementare un metodo facoltativo maintain() per la manutenzione della trascrizione (riscritture sicure tramite runtimeContext.rewriteTranscriptEntries()) dopo il bootstrap, un turno completato correttamente o la Compaction. Impostare info.turnMaintenanceMode: "background" per eseguirlo come attività differita anziché bloccare la risposta.

Per l'harness Codex non ACP incluso, OpenClaw applica lo stesso ciclo di vita proiettando il contesto assemblato nelle istruzioni per sviluppatori di Codex e nel prompt del turno corrente. Codex continua a gestire la propria cronologia nativa dei thread e il proprio compattatore nativo.

Ciclo di vita dei subagenti (facoltativo)

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

Aggiunta al prompt di sistema

Il metodo assemble può restituire una stringa systemPromptAddition. OpenClaw la antepone al prompt di sistema dell'esecuzione. Ciò consente ai motori di inserire indicazioni dinamiche per il recupero, istruzioni di reperimento o suggerimenti sensibili al contesto senza richiedere file statici nell'area di lavoro.

Il motore precedente

Il motore legacy integrato mantiene il comportamento originale di OpenClaw:

• Acquisizione: nessuna operazione (il gestore delle sessioni gestisce direttamente la persistenza dei messaggi).
• Assemblaggio: pass-through (la pipeline esistente di sanificazione → convalida → limitazione nel runtime gestisce l'assemblaggio del contesto).
• Compattazione: delega alla Compaction di riepilogo integrata, che crea un singolo riepilogo dei messaggi meno recenti e mantiene intatti quelli recenti.
• Dopo il turno: nessuna operazione.

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

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

Motori Plugin

Un Plugin può registrare un motore di contesto utilizzando l'API del 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 }) {      // Archivia il messaggio nel proprio archivio dati      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // Restituisce messaggi che rientrano nel budget      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 }) {      // Riassume il contesto meno recente      return { ok: true, compacted: true };    },  }));}

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

Quindi abilitarlo 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 modifica l'identità della sessione attiva, result.sessionTarget (un ContextEngineSessionTarget tipizzato che contiene l'identità della sessione e l'ambito dell'archivio) identifica la sessione successiva che deve essere utilizzata dal tentativo o turno successivo; result.sessionId rispecchia l'id successivo.

Membri facoltativi:

Impostazioni di runtime

Gli hook del ciclo di vita eseguiti all'interno di OpenClaw ricevono un oggetto facoltativo runtimeSettings. Si tratta di una superficie API interna produttore/consumatore, di sola lettura e con versione: OpenClaw la produce per il motore di contesto selezionato e il motore di contesto la utilizza negli hook del ciclo di vita. Non viene mostrata direttamente agli utenti e non crea una superficie dedicata per i rapporti.

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

I campi che possono essere sconosciuti sono rappresentati come null; i campi discriminanti, come la modalità runtime e l'origine della selezione, rimangono non nullable. I motori meno recenti rimangono compatibili: se un motore legacy rigoroso rifiuta runtimeSettings come proprietà sconosciuta, OpenClaw ripete 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 relativi alle capacità dell'host in info.hostRequirements. OpenClaw verifica tali requisiti prima di avviare l'operazione e applica il blocco preventivo con un errore descrittivo quando il runtime selezionato non è in grado di soddisfarli.

Per le esecuzioni dell'agente, dichiarare 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:        "Usare il runtime Codex nativo o quello incorporato di OpenClaw, oppure selezionare il motore di contesto legacy.",    },  },}

Le esecuzioni degli agenti Codex native e quelle incorporate di OpenClaw soddisfano assemble-before-prompt. I backend CLI generici non lo fanno, pertanto i motori che lo richiedono vengono rifiutati prima dell'avvio del processo CLI.

Isolamento degli errori

OpenClaw isola il motore del plugin selezionato dal percorso principale delle risposte. Se un motore non legacy è assente, non supera la convalida del contratto, genera un'eccezione durante la creazione della factory o da un metodo del ciclo di vita, OpenClaw mette tale motore in quarantena per il processo Gateway corrente e trasferisce il lavoro del motore di contesto al motore legacy integrato. L'errore viene registrato insieme all'operazione non riuscita, affinché l'operatore possa riparare, aggiornare o disabilitare il plugin senza che l'agente smetta di rispondere.

Gli errori relativi ai requisiti dell'host sono diversi: quando un motore dichiara che a un runtime manca una capacità richiesta, OpenClaw applica il blocco preventivo prima di avviare l'esecuzione. Ciò protegge i motori che danneggerebbero lo stato se venissero eseguiti in un host non supportato.

ownsCompaction

ownsCompaction determina se la compattazione automatica integrata nel runtime di OpenClaw durante il tentativo rimane abilitata per l'esecuzione:

Ciò significa che esistono due modelli di plugin validi:

Un'implementazione senza operazioni di compact() non è sicura per un motore attivo non proprietario, perché disabilita il normale percorso di compattazione /compact e di recupero dall'overflow per lo slot di tale motore.

Riferimento per la configurazione

{  plugins: {    slots: {      // Seleziona il motore di contesto attivo. Valore predefinito: "legacy".      // Impostare l'ID di un plugin per utilizzare il relativo motore.      contextEngine: "legacy",    },  },}

Relazione con la compattazione e la memoria

Suggerimenti

• Usare openclaw doctor per verificare che il motore venga caricato correttamente.
• Quando si cambia motore, le sessioni esistenti proseguono con la cronologia corrente. Il nuovo motore subentra nelle esecuzioni future.
• Gli errori del motore vengono registrati e il motore del plugin selezionato viene messo in quarantena per il processo Gateway corrente. OpenClaw ricorre a legacy per i turni dell'utente affinché le risposte possano continuare, ma è comunque necessario riparare, aggiornare, disabilitare o disinstallare il plugin non funzionante.
• Per lo sviluppo, usare openclaw plugins install -l ./my-engine per collegare una directory locale del plugin senza copiarla.

Contenuti correlati

• Compaction - riepilogo delle conversazioni lunghe
• Contesto - modalità di creazione del contesto per i turni dell'agente
• Architettura dei plugin - registrazione dei plugin dei motori di contesto
• Manifest del plugin - campi del manifest del plugin
• Plugin - panoramica dei plugin