​

Motore di contesto

​

Guida rapida

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

​

Installazione di un plugin del motore di contesto

# Install from npm
openclaw plugins install @martian-engineering/lossless-claw

# Or install from a local path (for development)
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

1. Ingest — chiamato quando un nuovo messaggio viene aggiunto alla sessione. Il motore può archiviare o indicizzare il messaggio nel proprio archivio dati.
2. Assemble — chiamato prima di ogni esecuzione del modello. Il motore restituisce un insieme ordinato di messaggi (e un eventuale systemPromptAddition) che rientrano nel budget di token.
3. Compact — chiamato quando la finestra di contesto è piena, o quando l’utente esegue /compact. Il motore riassume la cronologia meno recente per liberare spazio.
4. After turn — chiamato dopo il completamento di un’esecuzione. Il motore può persistere lo stato, attivare la compattazione in background o aggiornare gli indici.

​

Ciclo di vita dei subagenti (facoltativo)

• onSubagentEnded — pulizia quando una sessione di subagente viene completata o rimossa.

​

Aggiunta al prompt di sistema

​

Il motore legacy

• Ingest: no-op (il gestore della sessione si occupa direttamente della persistenza dei messaggi).
• Assemble: pass-through (la pipeline esistente sanitize → validate → limit nel runtime gestisce l’assemblaggio del contesto).
• Compact: delega alla compattazione di riepilogo integrata, che crea un singolo riepilogo dei messaggi meno recenti e mantiene intatti quelli recenti.
• After turn: no-op.

​

Motori plugin

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    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 };
    },
  }));
}

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

​

L’interfaccia ContextEngine

• messages — i messaggi ordinati da inviare al modello.
• estimatedTokens (obbligatorio, number) — la stima del motore del totale dei token nel contesto assemblato. OpenClaw usa questo valore per le decisioni sulla soglia di compattazione e per la reportistica diagnostica.
• systemPromptAddition (facoltativo, string) — anteposto al prompt di sistema.

​

ownsCompaction

• true — il motore gestisce il comportamento di compattazione. OpenClaw disabilita la compattazione automatica integrata di Pi per quell’esecuzione e l’implementazione compact() del motore è responsabile di /compact, della compattazione per il recupero da overflow e di qualsiasi compattazione proattiva che desidera eseguire in afterTurn().
• false o non impostato — la compattazione automatica integrata di Pi può comunque essere eseguita durante l’esecuzione del prompt, ma il metodo compact() del motore attivo viene comunque chiamato per /compact e per il recupero da overflow.

• Modalità proprietaria — implementa il tuo algoritmo di compattazione e imposta ownsCompaction: true.
• Modalità delegata — imposta ownsCompaction: false e fai in modo che compact() chiami delegateCompactionToRuntime(...) da openclaw/plugin-sdk/core per usare il comportamento di compattazione integrato di OpenClaw.

​

Riferimento della configurazione

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

​

Relazione con compattazione e memoria

• Compaction è una delle responsabilità del motore di contesto. Il motore legacy delega al riepilogo integrato di OpenClaw. I motori plugin possono implementare qualsiasi strategia di compattazione (riepiloghi DAG, vector retrieval, ecc.).
• Memory plugins (plugins.slots.memory) sono separati dai motori di contesto. I plugin di memoria forniscono ricerca/recupero; i motori di contesto controllano ciò che il modello vede. Possono lavorare insieme: un motore di contesto può usare dati del plugin di memoria durante l’assemblaggio. I motori plugin che vogliono il percorso di prompt della memoria attiva dovrebbero preferire buildMemorySystemPromptAddition(...) da openclaw/plugin-sdk/core, che converte le sezioni attive del prompt di memoria in un systemPromptAddition pronto da anteporre. Se un motore ha bisogno di un controllo di livello inferiore, può comunque recuperare le righe grezze da openclaw/plugin-sdk/memory-host-core tramite buildActiveMemoryPromptSection(...).
• Session pruning (il trimming dei vecchi risultati degli strumenti in memoria) continua a essere eseguito indipendentemente dal motore di contesto attivo.

​

Suggerimenti

• Usa openclaw doctor per verificare che il motore venga caricato correttamente.
• Se cambi motore, le sessioni esistenti continuano con la loro cronologia attuale. Il nuovo motore subentra per le esecuzioni future.
• Gli errori del motore vengono registrati nei log e mostrati nella diagnostica. Se un motore plugin non riesce a registrarsi o l’ID motore selezionato non può essere risolto, OpenClaw non effettua automaticamente un fallback; le esecuzioni falliscono finché non correggi il plugin o non reimposti plugins.slots.contextEngine su "legacy".
• Per lo sviluppo, usa openclaw plugins install -l ./my-engine per collegare una directory di plugin locale senza copiarla.

​

Correlati

• Context — come viene costruito il contesto per i turni dell’agente
• Plugin Architecture — registrazione dei plugin del motore di contesto
• Compaction — riepilogo delle conversazioni lunghe