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 a través de los límites de los subagentes.

OpenClaw incluye un motor legacy integrado y lo usa de forma predeterminada; la mayoría de los usuarios nunca necesitan cambiar esto. Instale y seleccione un motor de complemento solo cuando desee un comportamiento diferente de ensamblaje, compactación o recuperación entre sesiones.

Quick start

1. Verificar qué motor está activo

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

2. Instalar un motor de complemento

   Los complementos del motor de contexto se instalan como cualquier otro complemento de OpenClaw.

   Desde npmDesde una ruta local

   openclaw plugins install @martian-engineering/lossless-claw

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

3. Habilitar y seleccionar el motor

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

   Reinicie la puerta de enlace después de instalar y configurar.

4. Volver al heredado (opcional)

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

Cómo funciona

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

1. Ingestar

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

2. Ensamblar

Se llama antes de cada ejecución del modelo. El motor devuelve un conjunto ordenado de mensajes (y un systemPromptAddition opcional) que caben dentro del presupuesto de tokens.

3. Compactar

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

4. Después del turno

Se llama después de que se completa una ejecución. El motor puede persistir el estado, activar la compactación en segundo plano o actualizar los índices.

Para el arnés de Codex no ACP incluido, OpenClaw aplica el mismo ciclo de vida al proyectar el contexto ensamblado en las instrucciones del desarrollador de Codex y el mensaje del turno actual. Codex sigue siendo dueño de su historial de subprocesos nativo y su compactador nativo.

Ciclo de vida del subagente (opcional)

OpenClaw llama a dos ganchos opcionales del ciclo de vida del subagente:

Prepare shared context state before a child run starts. The hook receives parent/child session keys, `contextMode` (`isolated` or `fork`), available transcript ids/files, and optional TTL. If it returns a rollback handle, OpenClaw calls it when spawn fails after preparation succeeds. Native subagent spawns that request `lightContext` and resolve to `contextMode="isolated"` intentionally skip this hook so the child starts from the lightweight bootstrap context without context-engine-managed pre-spawn state. Clean up when a subagent session completes or is swept.

Adición del prompt del sistema

El método assemble puede devolver una cadena systemPromptAddition. OpenClaw antepone esto al mensaje del sistema para la ejecución. Esto permite a los motores inyectar orientación de recuperación dinámica, instrucciones de recuperación o pistas conscientes del contexto sin requerir archivos de espacio de trabajo estáticos.

El motor heredado

El motor integrado legacy preserva el comportamiento original de OpenClaw:

• Ingesta: no-op (el gestor de sesiones maneja la persistencia de mensajes directamente).
• Ensamblar: paso a través (la canalización existente de saneamiento → validación → límite en el tiempo de ejecución 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 los mensajes recientes intactos.
• After turn: no-op.

El motor heredado no registra herramientas ni proporciona una systemPromptAddition.

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

Motores de complementos

Un complemento puede registrar un motor de contexto utilizando la API de complementos:

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 }) {
      // 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 fábrica ctx incluye valores opcionales config, agentDir y workspaceDir para que los complementos puedan inicializar el estado por agente o por espacio de trabajo antes de que se ejecute el primer enlace del ciclo de vida.

Luego habilítelo en la configuración:

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

La interfaz ContextEngine

Miembros requeridos:

Miembro	Tipo	Propósito
info	Propiedad	ID del motor, nombre, versión y si es propietario de la compactación
ingest(params)	Método	Almacenar un solo mensaje
assemble(params)	Método	Construir contexto para una ejecución de modelo (devuelve AssembleResult)
compact(params)	Método	Resumir/reducir contexto

assemble devuelve un AssembleResult con:

Los mensajes ordenados para enviar al modelo. La estimación del motor del total de tokens en el contexto ensamblado. OpenClaw utiliza esto para decisiones de umbral de compactación e informes de diagnóstico. Antepuesto al prompt del sistema. Controla qué estimación de tokens utiliza el ejecutor para las comprobaciones preventivas de desbordamiento. Por defecto es `"assembled"`, lo que significa que solo se verifica la estimación del prompt ensamblado - apropiado para motores que devuelven un contexto con ventana y autónomo. Establézcalo en `"preassembly_may_overflow"` solo cuando su vista ensamblada pueda ocultar el riesgo de desbordamiento en la transcripción subyacente; el ejecutor entonces toma el máximo de la estimación ensamblada y la estimación del historial de sesión pre-ensamblado (sin ventana) al decidir si compactar preventivamente. De cualquier manera, los mensajes que devuelva siguen siendo lo que ve el modelo - `promptAuthority` solo afecta la precomprobación.

compact devuelve un CompactResult. Cuando la compactación rota la transcripción activa, result.sessionId y result.sessionFile identifican la sesión sucesora que el siguiente reintento o turno debe usar.

Miembros opcionales:

Miembro	Tipo	Propósito
bootstrap(params)	Método	Inicializar el estado del motor para una sesión. Se llama una vez cuando el motor ve una sesión por primera vez (por ejemplo, importar historial).
ingestBatch(params)	Método	Ingerir un turno completado como un lote. Se llama después de que se completa 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 (persistir el estado, activar la compactación en segundo plano).
prepareSubagentSpawn(params)	Método	Configurar el estado compartido para una sesión secundaria antes de que comience.
onSubagentEnded(params)	Método	Limpiar después de que termina un subagente.
dispose()	Método	Liberar recursos. Se llama durante el apagado de la puerta de enlace o la recarga del complemento; no por sesión.

Requisitos del host

Los motores de contexto pueden declarar requisitos de capacidad del host en info.hostRequirements. OpenClaw verifica estos requisitos antes de iniciar la operación y falla de forma segura con un error descriptivo cuando el tiempo de ejecución seleccionado no puede satisfacerlos.

Para ejecuciones de agentes, declare assemble-before-prompt cuando el motor deba controlar el prompt real del modelo a través de 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.",
    },
  },
}

Las ejecuciones de agentes integrados de Native Codex y 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 inicie el proceso de CLI.

Aislamiento de fallos

OpenClaw aísla el motor de complemento seleccionado de la ruta de respuesta principal. Si falta un motor que no sea heredado, falla la validación del contrato, lanza una excepción durante la creación de la fábrica o lanza una excepción desde un método de ciclo de vida, OpenClaw pone en cuarentena ese motor para el proceso de Gateway actual y degrada el trabajo del motor de contexto al motor incorporado legacy. El error se registra con la operación fallida para que el operador pueda reparar, actualizar o deshabilitar el complemento sin que el agente se quede en silencio.

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

ownsCompaction

ownsCompaction controla si la compactación automática incorporada en el tiempo de ejecución de OpenClaw permanece habilitada para la ejecución:

ownsCompaction: true

El motor es propietario del comportamiento de compactación. OpenClaw deshabilita la auto-compactación incorporada del tiempo de ejecución de OpenClaw para esa ejecución, y la implementación compact() del motor es responsable de /compact, la compactación de recuperación de desbordamiento y cualquier compactación proactiva que desee realizar en afterTurn(). OpenClaw aún puede ejecutar la salvaguardia de desbordamiento previa al mensaje; cuando predice que la transcripción completa se desbordará, la ruta de recuperación llama al compact() del motor activo antes de enviar otro mensaje.

ownsCompaction: false or unset

La auto-compactación incorporada del tiempo de ejecución de OpenClaw aún puede ejecutarse durante la ejecución del mensaje, pero el método compact() del motor activo aún se llama para /compact y la recuperación de desbordamiento.

Warning

ownsCompaction: false

no

significa que OpenClaw retroceda automáticamente a la ruta de compactación del motor heredado.

Eso significa que hay dos patrones de complementos válidos:

Owning modeModo de delegación

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

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

Un compact() nulo no es seguro para un motor no propietario activo porque deshabilita la ruta de compactación de /compact normal y de recuperación por desbordamiento para esa ranura 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",
    },
  },
}

Note

La ranura es exclusiva en tiempo de ejecución: solo se resuelve un motor de contexto registrado para una ejecución u operación de compactación determinada. Otros complementos kind: "context-engine" habilitados todavía pueden cargar y ejecutar su código de registro; plugins.slots.contextEngine solo selecciona qué id de motor registrado resuelve OpenClaw cuando necesita un motor de contexto.

Note

Desinstalación del complemento:

cuando desinstala el complemento 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 se requiere ninguna edición manual de la configuración.

Relación con la compactación y la memoria

Compactación

La compactación es una responsabilidad del motor de contexto. El motor heredado delega en el resumen integrado de OpenClaw. Los motores de complementos pueden implementar cualquier estrategia de compactación (resúmenes DAG, recuperación vectorial, etc.).

Complementos de memoria

Los complementos de memoria (plugins.slots.memory) son independientes de los motores de contexto. Los complementos de memoria proporcionan búsqueda/recuperación; los motores de contexto controlan lo que ve el modelo. Pueden trabajar juntos: un motor de contexto podría usar datos del complemento de memoria durante el ensamblaje. Los motores de complemento que deseen la ruta del mensaje de memoria activa deben preferir buildMemorySystemPromptAddition(...) de openclaw/plugin-sdk/core, que convierte las secciones del mensaje de memoria activa en un systemPromptAddition listo para anteponer. Si un motor necesita un control de menor nivel, todavía puede extraer líneas sin procesar de openclaw/plugin-sdk/memory-host-core a través de buildActiveMemoryPromptSection(...).

Poda de sesión

Recortar los resultados antiguos de herramientas en memoria aún se ejecuta independientemente de qué motor de contexto esté activo.

Consejos

• Use openclaw doctor para verificar que su motor se está cargando correctamente.
• Si cambia de motores, las sesiones existentes continúan con su historial actual. El nuevo motor toma el control para ejecuciones futuras.
• Los errores del motor se registran y el motor de complemento seleccionado se pone en cuarentena para el proceso actual de Gateway. OpenClaw recurre a legacy para los turnos del usuario para que las respuestas puedan continuar, pero aun así debes reparar, actualizar, deshabilitar o desinstalar el complemento roto.
• Para el desarrollo, usa openclaw plugins install -l ./my-engine para vincular un directorio de complementos local sin copiarlo.

Relacionado

• Compresión - resumiendo conversaciones largas
• Contexto - cómo se construye el contexto para los turnos del agente
• Arquitectura de complementos - registro de complementos de motor de contexto
• Manifiesto del complemento - campos del manifiesto del complemento
• Complementos - descripción general de los complementos