Configura el Context Engine de OpenClaw en 5 minutos

¿Alguna vez has sentido que tu agente pierde el hilo cuando la conversación se alarga demasiado? Gestionar el contexto manualmente es un dolor de cabeza, especialmente cuando intentas equilibrar el límite de tokens con la necesidad de recordar detalles importantes sin que el modelo se confunda o el presupuesto se dispare.

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

OpenClaw incluye un motor legacy integrado. Los plugins pueden registrar motores alternativos que reemplazan el ciclo de vida del context-engine activo.

Inicio rápido

Comprueba qué motor está activo:

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

Instalación de un plugin de context engine

Los plugins de context engine se instalan como cualquier otro plugin de OpenClaw. Instálalo primero y luego selecciona el motor en el slot correspondiente:

# Install from npm
openclaw plugins install @martian-engineering/lossless-claw

# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine

Después, activa el plugin y selecciónalo como el motor activo en tu configuración:

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

Reinicia el Gateway después de instalar y configurar.

Para volver al motor integrado, cambia contextEngine a "legacy" (o elimina la clave por completo; "legacy" es el valor por defecto).

Cómo funciona

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

1. Ingest: se llama cuando se añade un nuevo mensaje a la sesión. El motor puede almacenar o indexar el mensaje en su propio almacenamiento de datos.
2. Assemble: se llama antes de cada ejecución del modelo. El motor devuelve un conjunto ordenado de mensajes (y un systemPromptAddition opcional) que quepan dentro del presupuesto de tokens.
3. Compact: se llama cuando la ventana de contexto está llena o cuando el usuario ejecuta /compact. El motor resume el historial antiguo para liberar espacio.
4. After turn: se llama después de que se completa una ejecución. El motor puede persistir el estado, activar una compactación en segundo plano o actualizar índices.

Ciclo de vida del subagente (opcional)

Actualmente, OpenClaw llama a un hook del ciclo de vida del subagente:

• onSubagentEnded: limpia los datos cuando una sesión de subagente termina o es eliminada.

El hook prepareSubagentSpawn es parte de la interfaz para uso futuro, pero el runtime aún no lo invoca.

System prompt addition

El método assemble puede devolver un string systemPromptAddition. OpenClaw añade esto al principio del system prompt para la ejecución. Esto permite que los motores inyecten guías de recuerdo dinámicas, instrucciones de recuperación o pistas conscientes del contexto sin necesidad de archivos de workspace estáticos.

El motor legacy

El motor legacy integrado mantiene el comportamiento original de OpenClaw:

• Ingest: no hace nada (el gestor de sesiones maneja la persistencia de mensajes directamente).
• Assemble: paso directo (el pipeline existente de sanitize → validate → limit en el runtime maneja el ensamblaje del contexto).
• Compact: delega en la compactación de resumen integrada, que crea un único resumen de los mensajes antiguos y mantiene intactos los mensajes recientes.
• After turn: no hace nada.

El motor legacy no registra herramientas ni proporciona un systemPromptAddition.

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

Motores de plugins

Un plugin puede registrar un context engine usando la API de plugins:

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

Luego, actívalo 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 del motor, nombre, versión y si gestiona su propia compactación
ingest(params)	Método	Almacena un solo mensaje
assemble(params)	Método	Construye el contexto para una ejecución (devuelve AssembleResult)
compact(params)	Método	Resume o reduce el contexto

assemble devuelve un AssembleResult con:

• messages: los mensajes ordenados para enviar al modelo.
• estimatedTokens (obligatorio, number): la estimación del motor del total de tokens en el contexto ensamblado. OpenClaw usa esto para decisiones de umbral de compactación e informes de diagnóstico.
• systemPromptAddition (opcional, string): se añade al principio del system prompt.

Miembros opcionales:

Miembro	Tipo	Propósito
bootstrap(params)	Método	Inicializa el estado del motor para una sesión. Se llama la primera vez que el motor ve una sesión.
ingestBatch(params)	Método	Ingiere un turno completo como un lote. Se llama tras una ejecución con todos los mensajes de ese turno a la vez.
afterTurn(params)	Método	Trabajo post-ejecución (persistir estado, activar compactación en segundo plano).
prepareSubagentSpawn(params)	Método	Configura el estado compartido para una sesión hija.
onSubagentEnded(params)	Método	Limpieza después de que un subagente termina.
dispose()	Método	Libera recursos. Se llama al apagar el Gateway o recargar el plugin; no por sesión.

ownsCompaction

ownsCompaction controla si la auto-compactación integrada de Pi durante el intento permanece activa:

• true: el motor controla el comportamiento de compactación. OpenClaw desactiva la auto-compactación integrada de Pi para esa ejecución, y la implementación compact() del motor es responsable de /compact, la compactación por desbordamiento y cualquier compactación proactiva en afterTurn().
• false o no definido: la auto-compactación integrada de Pi puede ejecutarse durante la ejecución del prompt, pero el método compact() del motor activo se sigue llamando para /compact y recuperación de desbordamiento.

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

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

• Modo propietario (Owning mode): implementas tu propio algoritmo de compactación y estableces ownsCompaction: true.
• Modo delegado (Delegating mode): estableces ownsCompaction: false y haces que compact() llame a delegateCompactionToRuntime(...) desde openclaw/plugin-sdk/core para usar el comportamiento integrado de OpenClaw.

Un compact() que no haga nada (no-op) es inseguro para un motor activo que no sea propietario, porque desactiva la ruta normal de /compact y de recuperación por desbordamiento para ese slot de motor.

Referencia de configuración

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}

El slot es exclusivo en tiempo de ejecución: solo se resuelve un context engine registrado para una ejecución u operación de compactación determinada. Otros plugins de tipo kind: "context-engine" activados pueden cargar y ejecutar su código de registro; plugins.slots.contextEngine solo selecciona qué ID de motor resuelve OpenClaw cuando necesita uno.

Relación con la compactación y la memoria

• Compaction es una de las responsabilidades del context engine. El motor legacy delega en la resumida integrada de OpenClaw. Los motores de plugins pueden implementar cualquier estrategia (resúmenes DAG, recuperación vectorial, etc.).
• Memory plugins (plugins.slots.memory) son independientes de los motores de contexto. Los plugins de memoria ofrecen búsqueda y recuperación; los motores de contexto controlan qué ve el modelo. Pueden trabajar juntos: un motor de contexto podría usar datos de un plugin de memoria durante el ensamblaje.
• Session pruning (recorte de resultados de herramientas antiguos en memoria) se sigue ejecutando independientemente de qué motor de contexto esté activo.

Consejos

• Usa openclaw doctor para verificar que tu motor se está cargando correctamente.
• Si cambias de motor, las sesiones existentes continúan con su historial actual. El nuevo motor toma el control en las futuras ejecuciones.
• Los errores del motor se registran y aparecen en los diagnósticos. Si un motor de plugin falla al registrarse o el ID seleccionado no se puede resolver, OpenClaw no vuelve atrás automáticamente; las ejecuciones fallarán hasta que arregles el plugin o cambies contextEngine a "legacy".
• Para desarrollo, usa openclaw plugins install -l ./my-engine para enlazar un directorio local sin copiar archivos.

Pasos siguientes

• Contexto — cómo se construye el contexto para los turnos del agente
• Arquitectura de Plugins — registro de plugins de context engine
• Compactación — resumen de conversaciones largas

¿Necesitas ayuda configurando tu motor de contexto? Prueba nuestro AI Setup Assistant.