Motor de contexto

Un motor de contexto controla cómo OpenClaw crea 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 utiliza de forma predeterminada. Instale y seleccione un motor de Plugin únicamente cuando necesite un comportamiento diferente para el ensamblaje, la Compaction o la recuperación entre sesiones.

Inicio rápido

Comprobar qué motor está activo

openclaw doctor
# o inspeccionar la configuración directamente:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

Instalar un motor de Plugin

Los Plugins de motor de contexto se instalan como cualquier otro Plugin de OpenClaw.

Desde npm
Desde una ruta local

openclaw plugins install @martian-engineering/lossless-claw

openclaw plugins install -l ./my-context-engine

Habilitar y seleccionar el motor

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

Reinicie el Gateway después de instalarlo y configurarlo.

Volver al motor heredado (opcional)

Establezca contextEngine en "legacy" (o elimine la clave por completo; "legacy" es el valor predeterminado).

Cómo funciona

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

1. Ingesta

Se invoca cuando se añade un mensaje nuevo a la sesión. El motor puede almacenar o indexar el mensaje en su propio almacén de datos.

2. Ensamblaje

Se invoca antes de cada ejecución del modelo. El motor devuelve un conjunto ordenado de mensajes (y un systemPromptAddition opcional) que se ajustan al presupuesto de tokens.

3. Compactación

Se invoca cuando la ventana de contexto está llena o cuando se ejecuta /compact. El motor resume el historial anterior para liberar espacio.

4. Después del turno

Se invoca después de que finaliza una ejecución. El motor puede conservar el estado, activar la Compaction en segundo plano o actualizar los índices.

Los motores también pueden implementar un método maintain() opcional para el mantenimiento de transcripciones (reescrituras seguras mediante runtimeContext.rewriteTranscriptEntries()) después del arranque, 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 arnés Codex no ACP incluido, OpenClaw aplica el mismo ciclo de vida proyectando el contexto ensamblado en las instrucciones de desarrollador de Codex y el prompt del turno actual. Codex sigue gestionando su propio historial nativo de hilos y su compactador nativo.

Ciclo de vida de los subagentes (opcional)

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

method

Prepara el estado de contexto compartido antes de que comience una ejecución secundaria. El hook recibe las claves de sesión principal/secundaria, contextMode (isolated o fork), los identificadores/archivos de transcripción disponibles y un TTL opcional. Si devuelve un controlador de reversión, OpenClaw lo invoca cuando la creación falla después de que la preparación haya finalizado correctamente. Las creaciones nativas de subagentes que solicitan lightContext y se resuelven como contextMode="isolated" omiten intencionadamente este hook para que el subagente comience con el contexto de arranque ligero, sin estado previo a la creación gestionado por el motor de contexto.

method

Limpia los recursos cuando una sesión de subagente finaliza o se elimina.

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 indicaciones dinámicas de recuperación, instrucciones de recuperación o sugerencias adaptadas al contexto sin requerir archivos estáticos del espacio de trabajo.

El motor heredado

El motor legacy integrado conserva el comportamiento original de OpenClaw:

Ingesta: sin operación (el gestor de sesiones administra directamente la persistencia de los mensajes).
Ensamblaje: paso directo (el pipeline existente de saneamiento → validación → limitación del entorno de ejecución gestiona el ensamblaje del contexto).
Compactación: 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: sin operación.

El motor heredado no registra herramientas ni proporciona un systemPromptAddition. Cuando no se establece ningún plugins.slots.contextEngine (o se establece en "legacy"), este motor se utiliza automáticamente.

Motores de Plugin

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

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

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 }) {
      // Almacenar el mensaje en el almacén de datos
      return { ingested: true };
    },

    async assemble({
      sessionId,
      sessionKey,
      messages,
      tokenBudget,
      availableTools,
      citationsMode,
    }) {
      // Devolver mensajes que se ajusten al presupuesto
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },

    async compact({ sessionId, force }) {
      // Resumir 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 la primera llamada del ciclo de vida. Antes de una llamada assemble() no heredada, el host completa la preparación asíncrona registrada del prompt de memoria. El asistente síncrono buildMemorySystemPromptAddition(...) lee esa instantánea inmutable de la ejecución; pase sin cambios el contexto proporcionado de herramientas, citas, agente y sesión. A continuación, habilítelo en la configuración:

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

La interfaz ContextEngine

Miembros obligatorios:

Miembro	Tipo	Propósito
`info`	Propiedad	Id, nombre y versión del motor, y si gestiona la Compaction
`ingest(params)`	Método	Almacenar un único mensaje
`assemble(params)`	Método	Crear el contexto para una ejecución del modelo (devuelve `AssembleResult`)
`compact(params)`	Método	Resumir/reducir el contexto

assemble devuelve un AssembleResult con:

Message[]

requerido

Los mensajes ordenados que se enviarán al modelo.

number

requerido

La estimación del motor del total de tokens del contexto ensamblado. OpenClaw la utiliza para las decisiones sobre el umbral de Compaction y los informes de diagnóstico.

string

Se antepone al prompt del sistema.

"assembled" | "preassembly_may_overflow"

Controla qué estimación de tokens utiliza el ejecutor para las comprobaciones preventivas de desbordamiento. El valor predeterminado es "assembled", lo que significa que solo se comprueba la estimación del prompt ensamblado para los motores que no gestionan la Compaction. Los motores que establecen ownsCompaction: true administran su propia admisión de prompts, por lo que OpenClaw omite de forma predeterminada la comprobación previa genérica del prompt. Establezca "preassembly_may_overflow" únicamente cuando la vista ensamblada pueda ocultar el riesgo de desbordamiento en la transcripción subyacente; en ese caso, el ejecutor mantiene activa la comprobación genérica y toma el máximo entre la estimación ensamblada y la estimación del historial de la sesión previa al ensamblaje (sin ventanas) al decidir si se debe compactar de forma preventiva. En cualquier caso, los mensajes devueltos siguen siendo lo que ve el modelo; promptAuthority solo afecta a la comprobación previa.

ContextEngineProjection

Ciclo de vida de proyección opcional para hosts con hilos persistentes del backend (por ejemplo, el servidor de aplicaciones de Codex). mode: "thread_bootstrap" con un epoch estable solicita al host que inyecte el contexto ensamblado una vez por época y reutilice el hilo del backend hasta que cambie la época, en lugar de volver a proyectarlo en cada turno. Omita este campo para la proyección normal por turno.

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 utilizar el siguiente reintento o turno; result.sessionId refleja el identificador sucesor. Miembros opcionales:

Miembro	Tipo	Propósito
`bootstrap(params)`	Método	Inicializar el estado del motor para una sesión. Se invoca una vez cuando el motor encuentra una sesión por primera vez (p. ej., al importar el historial).
`maintain(params)`	Método	Mantenimiento de la transcripción después del arranque, de un turno correcto o de la Compaction. Utilice `runtimeContext.rewriteTranscriptEntries()` para realizar reescrituras seguras.
`ingestBatch(params)`	Método	Ingerir un turno completado como un lote. Se invoca después de que finalice una ejecución, con todos los mensajes de ese turno a la vez.
`afterTurn(params)`	Método	Trabajo del ciclo de vida posterior a la ejecución (conservar el estado, activar la Compaction en segundo plano).
`prepareSubagentSpawn(params)`	Método	Configurar el estado compartido de una sesión secundaria antes de que comience.
`onSubagentEnded(params)`	Método	Limpiar los recursos después de que finalice un subagente.
`dispose()`	Método	Liberar recursos. Se invoca durante el apagado del Gateway o la recarga del Plugin, no en cada sesión.

Configuración del entorno de ejecución

Los hooks del ciclo de vida que se ejecutan dentro de OpenClaw reciben un objeto runtimeSettings opcional. Es una superficie de API interna, versionada y de solo lectura para productores y consumidores: 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 de ejecución (normal, fallback o degraded) e identificadores opcionales del arnés o entorno de ejecución
contextEngineSelection: identificador del motor de contexto seleccionado y origen de la selección
executionHost: identificador 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 de motivo de cierre preventivo y degradación 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 anteriores siguen siendo compatibles: si un motor heredado estricto rechaza runtimeSettings como 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 preventivo con un error descriptivo cuando el entorno de ejecución seleccionado no puede satisfacerlos. Para las ejecuciones del agente, 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 del agente en Codex nativo y en 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 la 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 degrada 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 desactivar 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 preventivo antes de iniciar la ejecución. Esto protege a los motores que dañarí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 activada para la ejecución:

ownsCompaction: true

El motor controla el comportamiento de compactación. OpenClaw desactiva la compactación automática integrada del entorno de ejecución de OpenClaw y la comprobación previa genérica de desbordamiento antes del prompt para esa ejecución, y la implementación de compact() del motor es responsable de /compact, de la compactación de recuperación ante desbordamiento del proveedor y de cualquier compactación proactiva que se quiera realizar en afterTurn(). OpenClaw sigue ejecutando la protección contra desbordamiento previa al prompt cuando el motor devuelve promptAuthority: "preassembly_may_overflow" desde assemble().

ownsCompaction: false o sin establecer

La compactación automática integrada del entorno de ejecución de OpenClaw aún puede ejecutarse durante la ejecución del prompt, pero se sigue llamando al método compact() del motor activo para /compact y la recuperación ante desbordamiento.

ownsCompaction: false no significa que OpenClaw recurra automáticamente a la ruta de compactación del motor heredado.

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

Modo propietario
Modo de delegación

Implemente su propio algoritmo de compactación y establezca ownsCompaction: true.

Establezca ownsCompaction: false y haga que compact() llame a delegateCompactionToRuntime(...) desde openclaw/plugin-sdk/core para utilizar el comportamiento de compactación integrado de OpenClaw.

Una implementación de compact() que no realiza ninguna operación no es segura para un motor activo que no controla la compactación, porque desactiva la ruta normal de compactación de /compact y de recuperación ante desbordamiento para esa ranura del motor.

Referencia de configuración

{
  plugins: {
    slots: {
      // Seleccione el motor de contexto activo. Valor predeterminado: "legacy".
      // Establezca el identificador de un Plugin para utilizar su motor.
      contextEngine: "legacy",
    },
  },
}

La ranura es exclusiva durante la ejecución: solo se resuelve un motor de contexto registrado para una ejecución u operación de compactación determinada. Otros Plugins kind: "context-engine" activados aún pueden cargarse y ejecutar su código de registro; plugins.slots.contextEngine solo selecciona qué identificador de motor registrado resuelve OpenClaw cuando necesita un motor de contexto.

Desinstalación del Plugin: al desinstalar el Plugin seleccionado actualmente como plugins.slots.contextEngine, OpenClaw restablece la ranura al valor predeterminado (legacy). El mismo comportamiento de restablecimiento se aplica a plugins.slots.memory. No es necesario editar manualmente la configuración.

Relación con la compactación y la memoria

Compaction

Compaction es una de las responsabilidades del motor de contexto. El motor heredado delega en la función de resumen integrada de OpenClaw. Los motores de Plugins pueden implementar cualquier estrategia de compactación (resúmenes DAG, recuperación vectorial, etc.).

Plugins de memoria

Los Plugins de memoria (plugins.slots.memory) son independientes de los motores de contexto. Los Plugins de memoria proporcionan búsqueda y recuperación; los motores de contexto controlan lo que ve el modelo. Pueden funcionar conjuntamente: un motor de contexto podría utilizar datos de un Plugin de memoria durante el ensamblaje. Los motores de Plugins que quieran utilizar la ruta activa del prompt de memoria deben usar buildMemorySystemPromptAddition(...) desde openclaw/plugin-sdk/core, que convierte las secciones del prompt de memoria preparadas por el host en un systemPromptAddition listo para anteponer, sin exponer la disposición del Plugin de memoria.

Poda de sesiones

El recorte en memoria de los resultados antiguos de herramientas se sigue ejecutando independientemente del motor de contexto que esté activo.

Consejos

Use openclaw doctor para comprobar que el motor se carga correctamente.
Al cambiar de motor, las sesiones existentes continúan con 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, desactivar o desinstalar el Plugin defectuoso.
Para el desarrollo, use openclaw plugins install -l ./my-engine para vincular un directorio local de Plugins 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 del Plugin - campos del manifiesto del Plugin
Plugins - descripción general de los Plugins

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Motor de contexto

Inicio rápido

Cómo funciona

Ciclo de vida de los subagentes (opcional)

Adición al prompt del sistema

El motor heredado

Motores de Plugin

La interfaz ContextEngine

Configuración del entorno de ejecución

Requisitos del host

Aislamiento de fallos

ownsCompaction

Referencia de configuración

Relación con la compactación y la memoria

Consejos

Contenido relacionado

​Inicio rápido

​Cómo funciona

​Ciclo de vida de los subagentes (opcional)

​Adición al prompt del sistema

​El motor heredado

​Motores de Plugin

​La interfaz ContextEngine

​Configuración del entorno de ejecución

​Requisitos del host

​Aislamiento de fallos

​ownsCompaction

​Referencia de configuración

​Relación con la compactación y la memoria

​Consejos

​Contenido relacionado

Inicio rápido

Cómo funciona

Ciclo de vida de los subagentes (opcional)

Adición al prompt del sistema

El motor heredado

Motores de Plugin

La interfaz ContextEngine

Configuración del entorno de ejecución

Requisitos del host

Aislamiento de fallos

ownsCompaction

Referencia de configuración

Relación con la compactación y la memoria

Consejos

Contenido relacionado