Moteur de contexte

Un moteur de contexte contrôle la façon dont OpenClaw construit le contexte du modèle pour chaque exécution : quels messages inclure, comment résumer l’historique ancien et comment gérer le contexte au-delà des limites des sous-agents.

OpenClaw est livré avec un moteur legacy intégré et l’utilise par défaut - la plupart des utilisateurs n’ont jamais besoin de modifier cela. Installez et sélectionnez un moteur Plugin uniquement lorsque vous souhaitez un comportement différent d’assemblage, de Compaction ou de rappel intersessions.

# Démarrage rapide

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

# Fonctionnement

Chaque fois qu’OpenClaw exécute un prompt de modèle, le moteur de contexte intervient à quatre points du cycle de vie :

Pour le harnais Codex non-ACP fourni, OpenClaw applique le même cycle de vie en projetant le contexte assemblé dans les instructions développeur de Codex et dans le prompt du tour courant. Codex reste propriétaire de son historique de fil natif et de son compacteur natif.

# Cycle de vie des sous-agents (facultatif)

OpenClaw appelle deux hooks facultatifs du cycle de vie des sous-agents :

# Ajout au prompt système

La méthode assemble peut renvoyer une chaîne systemPromptAddition. OpenClaw la préfixe au prompt système de l’exécution. Cela permet aux moteurs d’injecter des consignes dynamiques de rappel, des instructions de récupération ou des indices contextuels sans nécessiter de fichiers statiques dans l’espace de travail.

# Le moteur legacy

Le moteur legacy intégré préserve le comportement d’origine d’OpenClaw :

• Ingestion : aucune opération (le gestionnaire de session gère directement la persistance des messages).
• Assemblage : transfert direct (le pipeline existant sanitize → validate → limit dans le runtime gère l’assemblage du contexte).
• Compactage : délègue à la Compaction de résumé intégrée, qui crée un résumé unique des messages anciens et conserve les messages récents intacts.
• Après le tour : aucune opération.

Le moteur legacy n’enregistre pas d’outils et ne fournit pas de systemPromptAddition.

Lorsque plugins.slots.contextEngine n’est pas défini (ou qu’il est défini sur "legacy"), ce moteur est utilisé automatiquement.

# Moteurs Plugin

Un Plugin peut enregistrer un moteur de contexte à l’aide de l’API 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 inclut des valeurs facultatives config, agentDir et workspaceDir afin que les plugins puissent initialiser un état par agent ou par espace de travail avant l’exécution du premier hook de cycle de vie.

Activez-le ensuite dans la configuration :

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

# L’interface ContextEngine

Membres requis :

assemble renvoie un AssembleResult avec :

compact renvoie un CompactResult. Lorsque la Compaction fait tourner la transcription active, result.sessionId et result.sessionFile identifient la session successeure que la prochaine nouvelle tentative ou le prochain tour doit utiliser.

Membres facultatifs :

# ownsCompaction

ownsCompaction contrôle si la Compaction automatique intégrée dans la tentative de Pi reste activée pour l’exécution :

Cela signifie qu’il existe deux modèles de Plugin valides :

Un compact() sans opération est dangereux pour un moteur actif non propriétaire, car il désactive le chemin normal de Compaction /compact et de récupération après dépassement pour ce slot de moteur.

# 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 la Compaction et la mémoire

# 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 exécutions futures.
• Les erreurs de moteur sont journalisées et affichées dans les diagnostics. Si un moteur Plugin ne parvient pas à s’enregistrer ou si l’id du moteur sélectionné ne peut pas être résolu, OpenClaw ne revient pas automatiquement au moteur précédent ; les exécutions échouent jusqu’à ce que vous corrigiez le plugin ou repassiez plugins.slots.contextEngine à "legacy".
• Pour le développement, utilisez openclaw plugins install -l ./my-engine pour lier un répertoire de plugin local sans le copier.

# Connexe

• Compaction - synthèse des longues conversations
• Contexte - comment le contexte est construit pour les tours d’agent
• Architecture des Plugin - enregistrement des plugins de moteur de contexte
• Manifeste de Plugin - champs du manifeste de plugin
• Plugins - vue d’ensemble des plugins