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 antiguo y cómo gestionar el contexto a través de los límites de subagentes.

OpenClaw incluye un motor legacy integrado y lo usa de forma predeterminada; la mayoría de los usuarios nunca necesitan cambiarlo. Instala y selecciona un motor de Plugin solo cuando quieras un comportamiento distinto de ensamblaje, Compaction o recuperación entre sesiones.

# Inicio rápido

openclaw doctor
# or inspect config directly:
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", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

# Cómo funciona

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

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 en el prompt del turno actual. Codex sigue siendo propietario de su historial de hilos nativo y de su compactador nativo.

# Ciclo de vida de subagentes (opcional)

OpenClaw llama a dos hooks opcionales del ciclo de vida de subagentes:

# Adición al prompt del sistema

El método assemble puede devolver una cadena systemPromptAddition. OpenClaw la antepone al prompt del sistema para 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: sin operación (el gestor de sesiones maneja directamente la persistencia de mensajes).
• Ensamblaje: paso directo (la canalización existente sanitize → validate → limit en el runtime maneja el ensamblaje de contexto).
• Compact: delega en la Compaction de resumen integrada, que crea un único resumen de los mensajes antiguos y mantiene intactos los mensajes recientes.
• Después del turno: sin operación.

El motor legacy no registra herramientas ni proporciona un systemPromptAddition.

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

# Motores de Plugin

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

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 Plugins puedan inicializar estado por agente o por espacio de trabajo antes de que se ejecute el primer hook de ciclo de vida.

Luego actívalo 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 rota la transcripción activa, result.sessionId y result.sessionFile identifican la sesión sucesora que debe usar el siguiente reintento o turno.

Miembros opcionales:

# ownsCompaction

ownsCompaction controla si la Compaction automática en intento integrada de Pi permanece activada para la ejecución:

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

Un compact() sin operación no es seguro para un motor activo que no posee Compaction porque desactiva la ruta normal de Compaction de /compact y recuperación de 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",
    },
  },
}

# Relación con Compaction y memoria

# 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 para ejecuciones futuras.
• Los errores del motor se registran y se muestran en diagnósticos. Si un motor de plugin no logra registrarse o el id del motor seleccionado no se puede resolver, OpenClaw no vuelve atrás automáticamente; las ejecuciones fallan hasta que corrijas el plugin o cambies plugins.slots.contextEngine de nuevo a "legacy".
• Para desarrollo, usa openclaw plugins install -l ./my-engine para enlazar un directorio local de plugin sin copiarlo.

# Relacionado

• Compaction - resumir conversaciones largas
• Contexto - cómo se construye el contexto para los turnos del agente
• Arquitectura de Plugin - registrar plugins de motor de contexto
• Manifiesto de Plugin - campos del manifiesto de plugin
• Plugins - descripción general de plugins