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 più vecchia e come gestire il contesto oltre i confini dei subagent.

OpenClaw include un motore legacy integrato e lo usa per impostazione predefinita: la maggior parte degli utenti non ha mai bisogno di cambiarlo. Installa e seleziona un motore Plugin solo quando vuoi un comportamento diverso di 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 incluso, OpenClaw applica lo stesso ciclo di vita proiettando il contesto assemblato nelle istruzioni sviluppatore di Codex e nel prompt del turno corrente. Codex continua a possedere la propria cronologia nativa del thread e il proprio compattatore nativo.

# Ciclo di vita del subagent (opzionale)

OpenClaw chiama due hook opzionali 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 per l'esecuzione. Questo consente ai motori di inserire indicazioni dinamiche di richiamo, istruzioni di recupero o suggerimenti consapevoli del contesto senza richiedere file statici nel workspace.

# Il motore legacy

Il motore legacy integrato conserva il comportamento originale di OpenClaw:

• Acquisizione: nessuna operazione (il gestore della sessione gestisce direttamente la persistenza dei messaggi).
• Assemblaggio: pass-through (la pipeline esistente sanitize → validate → limit nel runtime gestisce l'assemblaggio del contesto).
• Compaction: delega alla Compaction di riepilogo integrata, che crea un singolo riepilogo dei messaggi più vecchi 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 (o è impostato su "legacy"), questo motore viene usato automaticamente.

# Motori Plugin

Un Plugin può registrare un motore di contesto usando 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 }) {
      // 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 opzionali config, agentDir e workspaceDir così i Plugin possono inizializzare lo stato per agente o per workspace prima che venga eseguito il primo hook del ciclo di vita.

Quindi 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 il transcript attivo, result.sessionId e result.sessionFile identificano la sessione successiva che il prossimo retry o turno deve usare.

Membri opzionali:

# ownsCompaction

ownsCompaction controlla se la Compaction automatica in-tentativo integrata di Pi resta abilitata per l'esecuzione:

Questo significa che esistono due modelli Plugin validi:

Un compact() no-op non è sicuro per un motore attivo non proprietario perché disabilita il normale percorso di Compaction /compact e di recupero da overflow per quello slot 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 subentra per le esecuzioni future.
• Gli errori del motore vengono registrati e mostrati nella diagnostica. Se un motore Plugin non riesce a registrarsi o l'id del motore selezionato non può essere risolto, OpenClaw non esegue automaticamente il fallback; le esecuzioni falliscono finché non correggi il Plugin o non riporti plugins.slots.contextEngine a "legacy".
• Per lo sviluppo, usa openclaw plugins install -l ./my-engine per collegare una directory Plugin locale senza copiarla.

# Correlati

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