OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Fundamentals

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

    bash
    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

    bash
    openclaw plugins install @martian-engineering/lossless-claw

    Desde una ruta local

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

  • Habilitar y seleccionar el motor

    json5
    // 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:

    prepareSubagentSpawnmethod

    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.

    onSubagentEndedmethod

    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:

    ts
     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:

    json5
    {  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:

    messagesMessage[]required

    Los mensajes ordenados que se enviarán al modelo.

    estimatedTokensnumberrequired

    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.

    systemPromptAdditionstring

    Se antepone al prompt del sistema.

    promptAuthority"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.

    contextProjectionContextEngineProjection

    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():

    ts
    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.

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

    Modo propietario

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

    Modo de delegación

    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

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

    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

    Was this useful?
    On this page

    On this page