Compaction

Cada modelo tiene una ventana de contexto: la cantidad máxima de tokens que puede procesar. Cuando una conversación se acerca a ese límite, OpenClaw compacta los mensajes antiguos en un resumen para que el chat pueda continuar.

Cómo funciona

1. Los turnos antiguos de la conversación se resumen en una entrada compacta.
2. El resumen se guarda en la transcripción de la sesión.
3. Los mensajes recientes se mantienen intactos.

Cuando OpenClaw divide el historial en fragmentos de compactación, mantiene las llamadas a herramientas del asistente emparejadas con sus entradas toolResult correspondientes. Si un punto de división cae dentro de un bloque de herramienta, OpenClaw mueve el límite para que el par permanezca junto y se conserve la cola actual sin resumir.

El historial completo de la conversación permanece en disco. La compactación solo cambia lo que ve el modelo en el siguiente turno.

Compactación automática

La compactación automática está activada de forma predeterminada. Se ejecuta cuando la sesión se acerca al límite de contexto, o cuando el modelo devuelve un error de desbordamiento de contexto (en cuyo caso OpenClaw compacta y reintenta).

Verás:

• embedded run auto-compaction start / complete en los registros normales del Gateway.
• 🧹 Auto-compaction complete en modo detallado.
• /status mostrando 🧹 Compactions: <count>.

Compactación manual

Escribe /compact en cualquier chat para forzar una compactación. Agrega instrucciones para guiar el resumen:

/compact Focus on the API design decisions

Cuando agents.defaults.compaction.keepRecentTokens está configurado, la compactación manual respeta ese punto de corte de OpenClaw y mantiene la cola reciente en el contexto reconstruido. Sin un presupuesto explícito de conservación, la compactación manual se comporta como un punto de control estricto y continúa solo desde el nuevo resumen.

Configuración

Configura la compactación en agents.defaults.compaction dentro de tu openclaw.json. Las opciones más comunes se enumeran a continuación; para ver la referencia completa, consulta Análisis detallado de la gestión de sesiones.

Usar un modelo diferente

De forma predeterminada, la compactación usa el modelo principal del agente. Configura agents.defaults.compaction.model para delegar el resumen a un modelo más capaz o especializado. La anulación acepta una cadena provider/model-id o un alias sin prefijo configurado en agents.defaults.models:

{  "agents": {    "defaults": {      "compaction": {        "model": "openrouter/anthropic/claude-sonnet-4-6"      }    }  }}

Los alias configurados sin prefijo se resuelven a su proveedor y modelo canónicos antes de que comience la compactación. Si un valor sin prefijo coincide tanto con un alias como con un ID de modelo literal configurado, gana el ID de modelo literal. Un valor sin prefijo que no coincida permanece como ID de modelo en el proveedor activo.

Esto también funciona con modelos locales, por ejemplo un segundo modelo de Ollama dedicado al resumen:

{  "agents": {    "defaults": {      "compaction": {        "model": "ollama/llama3.1:8b"      }    }  }}

Cuando no está configurada, la compactación comienza con el modelo de la sesión activa. Si el resumen falla con un error de proveedor elegible para respaldo de modelo, OpenClaw reintenta ese intento de compactación a través de la cadena de respaldo de modelos existente de la sesión. La opción de respaldo es temporal y no se escribe de vuelta en el estado de la sesión. Una anulación explícita de agents.defaults.compaction.model permanece exacta y no hereda la cadena de respaldo de la sesión.

Preservación de identificadores

El resumen de compactación preserva identificadores opacos de forma predeterminada (identifierPolicy: "strict"). Anúlalo con identifierPolicy: "off" para deshabilitarlo, o con identifierPolicy: "custom" más identifierInstructions para indicaciones personalizadas.

Protección por bytes de transcripción activa

Cuando agents.defaults.compaction.maxActiveTranscriptBytes está configurado, OpenClaw activa la compactación local normal antes de una ejecución si el JSONL activo alcanza ese tamaño. Esto es útil para sesiones de larga duración donde la gestión de contexto del lado del proveedor puede mantener sano el contexto del modelo mientras la transcripción local sigue creciendo. No divide bytes JSONL sin procesar; solicita a la canalización normal de compactación que cree un resumen semántico.

Transcripciones sucesoras

Cuando agents.defaults.compaction.truncateAfterCompaction está habilitado, OpenClaw no reescribe la transcripción existente en el lugar. Crea una nueva transcripción sucesora activa a partir del resumen de compactación, el estado preservado y la cola sin resumir, y luego registra metadatos de punto de control que dirigen los flujos de rama/restauración a esa sucesora compactada. Las transcripciones sucesoras también eliminan turnos de usuario largos duplicados exactos que llegan dentro de una ventana corta de reintento, para que las tormentas de reintentos del canal no se arrastren a la siguiente transcripción activa después de la compactación.

OpenClaw ya no escribe copias .checkpoint.*.jsonl separadas para nuevas compactaciones. Los archivos de punto de control heredados existentes todavía pueden usarse mientras estén referenciados y se eliminan mediante la limpieza normal de sesiones.

Avisos de compactación

De forma predeterminada, la compactación se ejecuta en silencio. Configura notifyUser para mostrar mensajes breves de estado cuando la compactación empieza y termina:

{  agents: {    defaults: {      compaction: {        notifyUser: true,      },    },  },}

Vaciado de memoria

Antes de la compactación, OpenClaw puede ejecutar un turno de vaciado de memoria silencioso para almacenar notas duraderas en disco. Configura agents.defaults.compaction.memoryFlush.model cuando este turno de mantenimiento deba usar un modelo local en lugar del modelo de conversación activo:

{  "agents": {    "defaults": {      "compaction": {        "memoryFlush": {          "model": "ollama/qwen3:8b"        }      }    }  }}

La anulación del modelo de vaciado de memoria es exacta y no hereda la cadena de respaldo de la sesión activa. Consulta Memoria para obtener detalles y configuración.

Proveedores de compactación conectables

Los Plugins pueden registrar un proveedor de compactación personalizado mediante registerCompactionProvider() en la API del plugin. Cuando un proveedor está registrado y configurado, OpenClaw le delega el resumen en lugar de usar la canalización LLM incorporada.

Para usar un proveedor registrado, configura su id en tu configuración:

{  "agents": {    "defaults": {      "compaction": {        "provider": "my-provider"      }    }  }}

Configurar un provider fuerza automáticamente mode: "safeguard". Los proveedores reciben las mismas instrucciones de compactación y política de preservación de identificadores que la ruta incorporada, y OpenClaw aún conserva el contexto de sufijo de turnos recientes y turnos divididos después de la salida del proveedor.

Compactación frente a poda

La poda de sesión es un complemento más ligero que recorta la salida de herramientas sin resumir.

Solución de problemas

¿Se compacta con demasiada frecuencia? La ventana de contexto del modelo puede ser pequeña, o las salidas de herramientas pueden ser grandes. Prueba a habilitar la poda de sesión.

¿El contexto se siente obsoleto después de la compactación? Usa /compact Focus on <topic> para guiar el resumen, o habilita el vaciado de memoria para que las notas persistan.

¿Necesitas empezar de cero? /new inicia una sesión nueva sin compactar.

Para configuración avanzada (tokens reservados, preservación de identificadores, motores de contexto personalizados, compactación del lado del servidor de OpenAI), consulta el Análisis detallado de la gestión de sesiones.

Relacionado

• Sesión: gestión y ciclo de vida de sesiones.
• Poda de sesión: recorte de resultados de herramientas.
• Contexto: cómo se construye el contexto para los turnos del agente.
• Hooks: hooks del ciclo de vida de compactación (before_compaction, after_compaction).