Motor de contexto

Un motor de contexto controla cómo OpenClaw construye el contexto del modelo para cada ejecución: qué mensajes incluir, cómo resumir el historial anterior y cómo gestionar el contexto entre los límites de los subagentes.

OpenClaw incluye un motor legacy integrado y lo usa de forma predeterminada. Instale y seleccione un motor de Plugin solo cuando necesite un comportamiento diferente de ensamblaje, Compaction o recuperación entre sesiones.

Inicio rápido

openclaw doctor# o inspeccione directamente la configuración: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", // debe coincidir con el id de motor registrado del Plugin    },    entries: {      "lossless-claw": {        enabled: true,        // La configuración específica del Plugin va aquí (consulte la documentación del Plugin)      },    },  },}

Cómo funciona

Cada vez que OpenClaw ejecuta un prompt del modelo, el motor de contexto participa en cuatro puntos del ciclo de vida:

Los motores también pueden implementar un método opcional maintain() para el mantenimiento de la transcripción (reescrituras seguras mediante runtimeContext.rewriteTranscriptEntries()) después de la inicialización, de un turno correcto o de la Compaction. Establezca info.turnMaintenanceMode: "background" para ejecutarlo como trabajo diferido en lugar de bloquear la respuesta.

Para el entorno Codex no ACP incluido, OpenClaw aplica el mismo ciclo de vida proyectando el contexto ensamblado en las instrucciones para desarrolladores de Codex y en el prompt del turno actual. Codex sigue controlando su historial de hilos nativo y su compactador nativo.

Ciclo de vida de los subagentes (opcional)

OpenClaw invoca dos hooks opcionales del ciclo de vida de los subagentes:

Adición al prompt del sistema

El método assemble puede devolver una cadena systemPromptAddition. OpenClaw la antepone al prompt del sistema de la ejecución. Esto permite que los motores inyecten orientación dinámica de recuperación, instrucciones de recuperación o sugerencias sensibles al contexto sin requerir archivos estáticos del espacio de trabajo.

El motor legacy

El motor legacy integrado conserva el comportamiento original de OpenClaw:

• Ingesta: no realiza ninguna operación (el gestor de sesiones controla directamente la persistencia de mensajes).
• Ensamblaje: paso directo (la canalización existente de saneamiento → validación → limitación del entorno gestiona el ensamblaje del contexto).
• Compaction: delega en la Compaction de resumen integrada, que crea un único resumen de los mensajes anteriores y mantiene intactos los mensajes recientes.
• Después del turno: no realiza ninguna operación.

El motor legacy no registra herramientas ni proporciona un systemPromptAddition.

Cuando no se establece plugins.slots.contextEngine (o se establece en "legacy"), este motor se usa automáticamente.

Motores de Plugin

Un Plugin puede registrar un motor de contexto mediante la API de plugins:

  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 }) {      // Almacene el mensaje en su almacén de datos      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // Devuelva mensajes que se ajusten al presupuesto      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // Resuma el contexto anterior      return { ok: true, compacted: true };    },  }));}

La fábrica ctx incluye valores opcionales config, agentDir y workspaceDir para que los plugins puedan inicializar el estado por agente o por espacio de trabajo antes de que se ejecute el primer hook del ciclo de vida.

A continuación, habilítelo en la configuración:

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

La interfaz ContextEngine

Miembros obligatorios:

assemble devuelve un AssembleResult con:

compact devuelve un CompactResult. Cuando la Compaction cambia la identidad de la sesión activa, result.sessionTarget (un ContextEngineSessionTarget tipado que contiene la identidad de la sesión y el ámbito del almacén) identifica la sesión sucesora que debe usar el siguiente reintento o turno; result.sessionId refleja el id sucesor.

Miembros opcionales:

Configuración del entorno

Los hooks del ciclo de vida que se ejecutan dentro de OpenClaw reciben un objeto runtimeSettings opcional. Es una superficie de API interna de productor/consumidor, versionada y de solo lectura: OpenClaw la produce para el motor de contexto seleccionado y el motor de contexto la consume dentro de los hooks del ciclo de vida. No se muestra directamente a los usuarios ni crea una superficie de informes específica.

• schemaVersion: actualmente 1
• runtime: host de OpenClaw, modo del entorno (normal, fallback o degraded) e ids opcionales del entorno o arnés
• contextEngineSelection: id del motor de contexto seleccionado y origen de la selección
• executionHost: id y etiqueta del host para la superficie que invoca el hook
• model: modelo solicitado, modelo resuelto, proveedor y familia de modelos opcional
• limits: presupuesto de tokens del prompt y número máximo de tokens de salida cuando se conocen
• diagnostics: códigos cerrados de motivo del modo alternativo y degradado cuando se conocen

Los campos que pueden ser desconocidos se representan como null; los campos discriminadores, como el modo de ejecución y el origen de la selección, no admiten valores nulos. Los motores antiguos siguen siendo compatibles: si un motor heredado estricto rechaza runtimeSettings por ser una propiedad desconocida, OpenClaw reintenta la llamada del ciclo de vida sin ella, en lugar de poner el motor en cuarentena.

Requisitos del host

Los motores de contexto pueden declarar requisitos de capacidades del host en info.hostRequirements. OpenClaw comprueba estos requisitos antes de iniciar la operación y aplica un cierre seguro con un error descriptivo cuando el entorno de ejecución seleccionado no puede satisfacerlos.

Para las ejecuciones de agentes, declare assemble-before-prompt cuando el motor deba controlar el prompt real del modelo mediante assemble():

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use el entorno de ejecución nativo de Codex o el entorno integrado de OpenClaw, o seleccione el motor de contexto heredado.",    },  },}

Las ejecuciones de agentes con Codex nativo y el entorno integrado de OpenClaw satisfacen assemble-before-prompt. Los backends de CLI genéricos no lo hacen, por lo que los motores que lo requieren se rechazan antes de que se inicie el proceso de CLI.

Aislamiento de fallos

OpenClaw aísla el motor del plugin seleccionado de la ruta principal de respuestas. Si un motor no heredado no está disponible, no supera la validación del contrato, genera una excepción durante la creación de la fábrica o desde un método del ciclo de vida, OpenClaw pone ese motor en cuarentena durante el proceso actual del Gateway y transfiere el trabajo del motor de contexto al motor legacy integrado. El error se registra junto con la operación fallida para que el operador pueda reparar, actualizar o deshabilitar el plugin sin que el agente deje de responder.

Los fallos de requisitos del host son diferentes: cuando un motor declara que un entorno de ejecución carece de una capacidad requerida, OpenClaw aplica un cierre seguro antes de iniciar la ejecución. Esto protege a los motores que corromperían el estado si se ejecutaran en un host no compatible.

ownsCompaction

ownsCompaction controla si la compactación automática integrada durante el intento del entorno de ejecución de OpenClaw permanece habilitada para la ejecución:

Esto significa que existen dos patrones de plugin válidos:

Un método compact() que no realiza ninguna operación no es seguro para un motor activo no propietario, ya que deshabilita la ruta normal de compactación de /compact y de recuperación ante desbordamientos para ese espacio de motor.

Referencia de configuración

{  plugins: {    slots: {      // Seleccione el motor de contexto activo. Valor predeterminado: "legacy".      // Establézcalo en el identificador de un plugin para utilizar su motor.      contextEngine: "legacy",    },  },}

Relación con la compactación y la memoria

Consejos

• Use openclaw doctor para verificar que el motor se carga correctamente.
• Al cambiar de motor, las sesiones existentes conservan su historial actual. El nuevo motor se hace cargo de las ejecuciones futuras.
• Los errores del motor se registran y el motor del plugin seleccionado se pone en cuarentena durante el proceso actual del Gateway. OpenClaw recurre a legacy para los turnos del usuario, de modo que las respuestas puedan continuar, pero aun así se debe reparar, actualizar, deshabilitar o desinstalar el plugin defectuoso.
• Para el desarrollo, use openclaw plugins install -l ./my-engine para vincular un directorio de plugin local sin copiarlo.

Contenido relacionado

• Compaction - resumen de conversaciones largas
• Contexto - cómo se crea el contexto para los turnos del agente
• Arquitectura de plugins - registro de plugins de motores de contexto
• Manifiesto de plugins - campos del manifiesto de plugins
• Plugins - descripción general de los plugins