​

Context Engine

​

Démarrage rapide

openclaw doctor
# ou inspectez directement la configuration :
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

​

Installer un plugin de moteur de contexte

# Installer depuis npm
openclaw plugins install @martian-engineering/lossless-claw

# Ou installer depuis un chemin local (pour le développement)
openclaw plugins install -l ./my-context-engine

// openclaw.json
{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // doit correspondre à l’id de moteur enregistré du plugin
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // La configuration spécifique au plugin va ici (voir la documentation du plugin)
      },
    },
  },
}

​

Fonctionnement

1. Ingest — appelé lorsqu’un nouveau message est ajouté à la session. Le moteur peut stocker ou indexer le message dans son propre magasin de données.
2. Assemble — appelé avant chaque exécution du modèle. Le moteur renvoie un ensemble ordonné de messages (et éventuellement un systemPromptAddition) qui tiennent dans le budget de jetons.
3. Compact — appelé 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. After turn — appelé une fois l’exécution terminée. Le moteur peut conserver l’état, déclencher une compaction en arrière-plan ou mettre à jour les index.

​

Cycle de vie du sous-agent (facultatif)

• onSubagentEnded — nettoyage lorsqu’une session de sous-agent se termine ou est purgée.

​

Ajout au prompt système

​

Le moteur hérité

• Ingest : no-op (le gestionnaire de session gère directement la persistance des messages).
• Assemble : passage direct (le pipeline existant sanitize → validate → limit dans le runtime gère l’assemblage du contexte).
• Compact : délègue à la compaction intégrée par résumé, qui crée un résumé unique des anciens messages et conserve les messages récents intacts.
• After turn : no-op.

​

Moteurs de 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 }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

    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 total de jetons dans le contexte assemblé. OpenClaw l’utilise pour les décisions de seuil de compaction et les rapports de diagnostic.
• systemPromptAddition (facultatif, string) — préfixé au prompt système.

​

ownsCompaction

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

• Mode propriétaire — implémentez votre propre algorithme de compaction et définissez ownsCompaction: true.
• Mode 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 compaction intégré d’OpenClaw.

​

Référence de configuration

{
  plugins: {
    slots: {
      // Sélectionne le moteur de contexte actif. Par défaut : "legacy".
      // Définissez-le sur un id de plugin pour utiliser un moteur de plugin.
      contextEngine: "legacy",
    },
  },
}

​

Relation avec la compaction et la mémoire

• La compaction est une responsabilité 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 compaction (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/la 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 les données d’un plugin de mémoire pendant l’assemblage.
• L’élagage de session (suppression des anciens résultats d’outils en mémoire) 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 continuent avec leur historique actuel. Le nouveau moteur prend le relais pour les futures exécutions.
• Les erreurs du moteur sont journalisées et remontées dans les diagnostics. Si un moteur de plugin échoue à s’enregistrer ou si l’id du moteur sélectionné ne peut pas être résolu, OpenClaw ne revient pas automatiquement en arrière ; les exécutions échouent tant que vous ne corrigez pas le plugin ou ne redéfinissez pas 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é

• Context — comment le contexte est construit pour les tours d’agent
• Architecture des plugins — enregistrement des plugins de moteur de contexte
• Compaction — résumé des longues conversations