​

Moteur de contexte

​

Démarrage rapide

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

​

Installation d’un plugin de moteur de contexte

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

​

Fonctionnement

1. Ingestion — appelée lorsqu’un nouveau message est ajouté à la session. Le moteur peut stocker ou indexer le message dans son propre magasin de données.
2. Assemblage — appelée avant chaque exécution du modèle. Le moteur renvoie un ensemble ordonné de messages (et un systemPromptAddition facultatif) qui tiennent dans le budget de jetons.
3. Compactage — appelée lorsque la fenêtre de contexte est pleine, ou lorsque l’utilisateur exécute /compact. Le moteur résume l’historique plus ancien pour libérer de l’espace.
4. Après tour — appelée une fois l’exécution terminée. Le moteur peut persister l’état, déclencher un compactage en arrière-plan ou mettre à jour des index.

​

Cycle de vie des sous-agents (facultatif)

• onSubagentEnded — nettoie lorsque la session d’un sous-agent se termine ou est balayée.

​

Ajout à l’invite système

​

Le moteur hérité

• Ingestion : no-op (le gestionnaire de session gère directement la persistance des messages).
• Assemblage : transmission directe (le pipeline sanitize → validate → limit existant dans l’environnement d’exécution gère l’assemblage du contexte).
• Compactage : délègue au compactage de résumé intégré, qui crée un résumé unique des anciens messages et conserve intacts les messages récents.
• Après tour : no-op.

​

Moteurs de 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’interface ContextEngine

• messages — les messages ordonnés à envoyer au modèle.
• estimatedTokens (requis, number) — l’estimation par le moteur du nombre total de jetons dans le contexte assemblé. OpenClaw l’utilise pour les décisions de seuil de compactage et les rapports de diagnostic.
• systemPromptAddition (facultatif, string) — préfixé à l’invite système.

​

ownsCompaction

• true — le moteur prend en charge le comportement de compactage. OpenClaw désactive l’auto-compactage intégré de Pi pour cette exécution, et l’implémentation compact() du moteur est responsable de /compact, du compactage de récupération après dépassement, ainsi que de tout compactage proactif qu’il souhaite effectuer dans afterTurn().
• false ou non défini — l’auto-compactage intégré de Pi peut toujours s’exécuter pendant l’exécution de l’invite, mais la méthode compact() du moteur actif est toujours appelée pour /compact et la récupération après dépassement.

• Mode propriétaire — implémentez votre propre algorithme de compactage et définissez ownsCompaction: true.
• Mode de délégation — définissez ownsCompaction: false et faites en sorte que compact() appelle delegateCompactionToRuntime(...) depuis openclaw/plugin-sdk/core pour utiliser le comportement de compactage intégré d’OpenClaw.

​

Référence de configuration

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

​

Relation avec le compactage et la mémoire

• Le compactage est l’une des responsabilités du moteur de contexte. Le moteur hérité délègue au résumé intégré d’OpenClaw. Les moteurs de plugin peuvent implémenter n’importe quelle stratégie de compactage (résumés DAG, récupération vectorielle, etc.).
• Les plugins de mémoire (plugins.slots.memory) sont distincts des moteurs de contexte. Les plugins de mémoire fournissent la recherche/récupération ; les moteurs de contexte contrôlent ce que le modèle voit. Ils peuvent fonctionner ensemble — un moteur de contexte peut utiliser des données du plugin de mémoire pendant l’assemblage. Les moteurs de plugin qui veulent le chemin actif d’invite mémoire devraient privilégier buildMemorySystemPromptAddition(...) depuis openclaw/plugin-sdk/core, qui convertit les sections actives de l’invite mémoire en un systemPromptAddition prêt à être préfixé. Si un moteur a besoin d’un contrôle de plus bas niveau, il peut toujours récupérer les lignes brutes depuis openclaw/plugin-sdk/memory-host-core via buildActiveMemoryPromptSection(...).
• L’élagage de session (suppression en mémoire des anciens résultats d’outils) continue de s’exécuter quel que soit le moteur de contexte actif.

​

Conseils

• Utilisez openclaw doctor pour vérifier que votre moteur se charge correctement.
• Si vous changez de moteur, les sessions existantes conservent leur historique actuel. Le nouveau moteur prend le relais pour les exécutions futures.
• Les erreurs de moteur sont consignées dans les journaux et affichées dans les diagnostics. Si un moteur de plugin ne parvient pas à s’enregistrer ou si l’ID de moteur sélectionné ne peut pas être résolu, OpenClaw ne bascule pas automatiquement ; les exécutions échouent jusqu’à ce que vous corrigiez le plugin ou que vous redéfinissiez plugins.slots.contextEngine sur "legacy".
• Pour le développement, utilisez openclaw plugins install -l ./my-engine pour lier un répertoire de plugin local sans le copier.

​

Lié

• Contexte — comment le contexte est construit pour les tours de l’agent
• Architecture des plugins — enregistrement de plugins de moteur de contexte
• Compactage — résumé des longues conversations