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 plus ancien et comment gérer le contexte au-delà des limites des sous-agents.

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

Démarrage rapide

openclaw doctor# ou inspecter directement la config :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", // doit correspondre à l'id de moteur enregistré du plugin    },    entries: {      "lossless-claw": {        enabled: true,        // La config propre au plugin va ici (voir la documentation du plugin)      },    },  },}

Fonctionnement

Chaque fois qu'OpenClaw exécute une invite de modèle, le moteur de contexte intervient à quatre points du cycle de vie :

Pour le harnais Codex non-ACP intégré, OpenClaw applique le même cycle de vie en projetant le contexte assemblé dans les instructions développeur de Codex et l'invite 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 à l'invite système

La méthode assemble peut renvoyer une chaîne systemPromptAddition. OpenClaw l'ajoute au début de l'invite système pour l'exécution. Cela permet aux moteurs d'injecter des indications de rappel dynamiques, des instructions de récupération ou des conseils sensibles au contexte sans nécessiter de fichiers d'espace de travail statiques.

Le moteur legacy

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

• Ingestion : no-op (le gestionnaire de session gère directement la persistance des messages).
• Assembler : passage direct (le pipeline existant sanitize → validate → limit du runtime gère l'assemblage du contexte).
• Compacter : délègue à la compaction de résumé intégrée, qui crée un résumé unique des messages plus anciens et conserve les messages récents intacts.
• Après le tour : no-op.

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

Lorsqu'aucun plugins.slots.contextEngine n'est défini (ou lorsqu'il est défini sur "legacy"), ce moteur est utilisé automatiquement.

Moteurs de plugin

Un plugin peut enregistrer un moteur de contexte avec l'API de 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 fabrique 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 config :

{  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 le transcript actif, result.sessionId et result.sessionFile identifient la session successeur que la prochaine nouvelle tentative ou le prochain tour doit utiliser.

Membres facultatifs :

Paramètres d'exécution

Les hooks de cycle de vie exécutés dans OpenClaw reçoivent un objet runtimeSettings facultatif. Il s'agit d'une surface d'API interne producteur/consommateur versionnée et en lecture seule : OpenClaw le produit pour le moteur de contexte sélectionné, et le moteur de contexte le consomme dans les hooks de cycle de vie. Il n'est pas rendu directement aux utilisateurs et ne crée pas de surface de reporting dédiée.

• schemaVersion : actuellement 1
• runtime : hôte OpenClaw, mode runtime (normal, fallback ou degraded), et ids facultatifs de harnais/runtime
• contextEngineSelection : id du moteur de contexte sélectionné et source de sélection
• executionHost : id et libellé de l'hôte pour la surface qui invoque le hook
• model : modèle demandé, modèle résolu, fournisseur et famille de modèle facultative
• limits : budget de tokens de l'invite et nombre maximal de tokens de sortie lorsqu'ils sont connus
• diagnostics : codes fermés de raison de fallback et de dégradation lorsqu'ils sont connus

Les champs qui peuvent être inconnus sont représentés par null ; les champs discriminants tels que le mode runtime et la source de sélection restent non nullables. Les moteurs plus anciens restent compatibles : si un moteur legacy strict rejette runtimeSettings en tant que propriété inconnue, OpenClaw réessaie l'appel de cycle de vie sans celui-ci au lieu de mettre le moteur en quarantaine.

Exigences de l'hôte

Les moteurs de contexte peuvent déclarer des exigences de capacités d'hôte sur info.hostRequirements. OpenClaw vérifie ces exigences avant de démarrer l'opération et échoue de façon fermée avec une erreur descriptive lorsque le runtime sélectionné ne peut pas les satisfaire.

Pour les exécutions d'agent, déclarez assemble-before-prompt lorsque le moteur doit contrôler l'invite réelle du modèle via assemble() :

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use the native Codex or OpenClaw embedded runtime, or select the legacy context engine.",    },  },}

Les exécutions d'agent Codex natif et OpenClaw intégré satisfont assemble-before-prompt. Les backends CLI génériques ne le font pas ; les moteurs qui l'exigent sont donc rejetés avant le démarrage du processus CLI.

Isolation des échecs

OpenClaw isole le moteur de Plugin sélectionné du chemin de réponse principal. Si un moteur non hérité est manquant, échoue à la validation du contrat, lève une exception pendant la création de la fabrique, ou lève une exception depuis une méthode de cycle de vie, OpenClaw met ce moteur en quarantaine pour le processus Gateway actuel et rétrograde le travail du moteur de contexte vers le moteur legacy intégré. L’erreur est journalisée avec l’opération échouée afin que l’opérateur puisse réparer, mettre à jour ou désactiver le Plugin sans que l’agent devienne silencieux.

Les échecs liés aux exigences de l’hôte sont différents : lorsqu’un moteur déclare qu’un runtime ne dispose pas d’une capacité requise, OpenClaw échoue en mode fermé avant de démarrer l’exécution. Cela protège les moteurs qui corrompraient l’état s’ils s’exécutaient dans un hôte non pris en charge.

ownsCompaction

ownsCompaction contrôle si l’auto-Compaction intégrée en cours de tentative du runtime OpenClaw reste activée pour l’exécution :

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

Un compact() sans effet est dangereux pour un moteur actif non propriétaire, car il désactive le chemin normal de Compaction /compact et de récupération en cas de dépassement pour cet emplacement 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 futures exécutions.
• Les erreurs de moteur sont journalisées et le moteur de Plugin sélectionné est mis en quarantaine pour le processus Gateway actuel. OpenClaw revient à legacy pour les tours utilisateur afin que les réponses puissent continuer, mais vous devez tout de même réparer, mettre à jour, désactiver ou désinstaller le Plugin défectueux.
• Pour le développement, utilisez openclaw plugins install -l ./my-engine afin de lier un répertoire de Plugin local sans le copier.

Liens connexes

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