​

Motore di contesto

​

Guida rapida

openclaw doctor
# oppure ispeziona direttamente la configurazione:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

​

Installazione di un plugin del motore di contesto

# Installa da npm
openclaw plugins install @martian-engineering/lossless-claw

# Oppure installa da un percorso locale (per lo sviluppo)
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 qui (consulta la documentazione del plugin)
      },
    },
  },
}

​

Come funziona

1. Ingest — chiamato quando viene aggiunto un nuovo messaggio alla sessione. Il motore può memorizzare 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 rientra nel budget di token.
3. Compact — chiamato quando la finestra di contesto è piena, o quando l’utente esegue /compact. Il motore riepiloga la cronologia meno recente per liberare spazio.
4. After turn — chiamato dopo il completamento di un’esecuzione. Il motore può rendere persistente lo stato, attivare la compattazione in background o aggiornare gli indici.

​

Ciclo di vita del sottoagente (facoltativo)

• onSubagentEnded — esegue la pulizia quando una sessione di sottoagente termina o viene rimossa.

​

Aggiunta al prompt di sistema

​

Il motore legacy

• Ingest: nessuna operazione (il gestore di 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 i messaggi recenti.
• After turn: nessuna operazione.

​

Motori plugin

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // Memorizza il messaggio nel tuo archivio dati
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget }) {
      // Restituisci i messaggi che rientrano nel budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

    async compact({ sessionId, force }) {
      // Riepiloga il contesto meno recente
      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 numero totale di token nel contesto assemblato. OpenClaw usa questo valore per le decisioni sulla soglia di compattazione e per il reporting diagnostico.
• systemPromptAddition (facoltativo, string) — anteposto al prompt di sistema.

​

ownsCompaction

• true — il motore possiede 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 di recupero da overflow e di qualsiasi compattazione proattiva che voglia 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: {
      // Seleziona il motore di contesto attivo. Predefinito: "legacy".
      // Impostalo su un id plugin per usare un motore plugin.
      contextEngine: "legacy",
    },
  },
}

​

Relazione con compattazione e memoria

• Compattazione è una delle responsabilità del motore di contesto. Il motore legacy delega alla funzionalità di riepilogo integrata di OpenClaw. I motori plugin possono implementare qualsiasi strategia di compattazione (riepiloghi DAG, recupero vettoriale, ecc.).
• Plugin di memoria (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 collaborare — un motore di contesto potrebbe usare dati del plugin di memoria durante l’assemblaggio.
• Potatura della sessione (riduzione in memoria dei risultati degli strumenti meno recenti) continua a essere eseguita indipendentemente dal motore di contesto attivo.

​

Suggerimenti

• Usa openclaw doctor per verificare che il tuo motore venga caricato correttamente.
• Se cambi motore, le sessioni esistenti continuano con la cronologia attuale. Il nuovo motore prenderà il controllo per le esecuzioni future.
• Gli errori del motore vengono registrati e mostrati nella diagnostica. Se un motore plugin non riesce a registrarsi o non è possibile risolvere l’id del motore selezionato, OpenClaw non esegue un fallback automatico; le esecuzioni falliscono finché non correggi il plugin oppure riporti plugins.slots.contextEngine a "legacy".
• Per lo sviluppo, usa openclaw plugins install -l ./my-engine per collegare una directory di plugin locale senza copiarla.

​

Correlati

• Contesto — come viene costruito il contesto per i turni dell’agente
• Architettura dei plugin — registrazione dei plugin del motore di contesto
• Compattazione — riepilogo delle conversazioni lunghe