Compactación

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

Cómo funciona

Los turnos de conversación más antiguos se resumen en una entrada compacta.
El resumen se guarda en la transcripción de la sesión.
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 herramientas, OpenClaw mueve el límite para que el par permanezca junto y se preserve la cola no resumida actual.

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

Auto-compactación

La auto-compactación está activada por defecto. 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 reintentar).

Verás:

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

Firmas de desbordamiento reconocidas

OpenClaw detecta el desbordamiento de contexto a partir de estos patrones de error del proveedor:

request_too_large
context length exceeded
input exceeds the maximum number of tokens
input token count exceeds the maximum number of input tokens
input is too long for the model
ollama error: context length exceeded

Compactación manual

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

/compact Focus on the API design decisions

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

Configuración

Configure la compactación bajo agents.defaults.compaction en su openclaw.json. Los controles más comunes se enumeran a continuación; para la referencia completa, consulte Profundización en la gestión de sesiones.

Usar un modelo diferente

De forma predeterminada, la compactación utiliza el modelo principal del agente. Configure agents.defaults.compaction.model para delegar el resumen a un modelo más capaz o especializado. La anulación acepta cualquier cadena provider/model-id:

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

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

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

Cuando no está configurado, la compactación comienza con el modelo de sesión activo. Si el resumen falla con un error de proveedor elegible para reserva de modelo (fallback), OpenClaw reintenta ese intento de compactación a través de la cadena de reserva de modelo existente de la sesión. La elección de reserva es temporal y no se escribe de nuevo en el estado de la sesión. Una anulación explícita agents.defaults.compaction.model permanece exacta y no hereda la cadena de reserva de la sesión.

Preservación de identificadores

La compactación por resumen preserva los identificadores opacos de forma predeterminada (identifierPolicy: "strict"). Anule esto con identifierPolicy: "off" para desactivar, o identifierPolicy: "custom" más identifierInstructions para una guía personalizada.

Guardián de bytes de transcripción activa

Cuando se establece agents.defaults.compaction.maxActiveTranscriptBytes, 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 del contexto en el lado del proveedor puede mantener el contexto del modelo sano mientras la transcripción local sigue creciendo. No divide los bytes JSONL sin procesar; pide a la canalización de compactación normal que cree un resumen semántico.

Transcripciones sucesoras

Cuando agents.defaults.compaction.truncateAfterCompaction está habilitado, OpenClaw no reescribe la transcripción existente en su lugar. Crea una nueva transcripción sucesora activa a partir del resumen de compactación, el estado preservado y la cola no resumida, y luego registra metadatos de punto de control que dirigen los flujos de bifurcación/restauración a ese sucesor compactado. Las transcripciones sucesoras también descartan turnos largos de usuario duplicados exactos que lleguen dentro de una ventana corta de reintento, de modo que las tormentas de reintento del canal no se transfieran a la siguiente transcripción activa después de la compactación.

OpenClaw ya no escribe copias separadas de .checkpoint.*.jsonl para nuevas compactaciones. Los archivos de punto de control heredados existentes aún se pueden usar mientras se hace referencia a ellos y son eliminados por la limpieza normal de la sesión.

Avisos de compactación

De forma predeterminada, la compactación se ejecuta silenciosamente. Establezca notifyUser para mostrar mensajes de estado breves cuando se inicia y completa la compactación:

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

Volcado de memoria

Antes de la compactación, OpenClaw puede ejecutar un turno de lavado de memoria silencioso para almacenar notas duraderas en el disco. Establezca 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 lavado de memoria es exacta y no hereda la cadena de reserva de la sesión activa. Consulte Memoria para obtener detalles y configuración.

Proveedores de compactación conectables

Los complementos pueden registrar un proveedor de compactación personalizado a través de registerCompactionProvider() en la API de complementos. Cuando se registra y configura un proveedor, OpenClaw delega la resumisión a él en lugar de a la canalización LLM integrada.

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

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

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

Compactación frente a poda

	Compactación	Poda
Lo que hace	Resume la conversación anterior	Recorta resultados de herramientas antiguos
¿Guardado?	Sí (en la transcripción de la sesión)	No (solo en memoria, por solicitud)
Alcance	Conversación completa	Solo resultados de herramientas

Session pruning es un complemento más ligero que recorta la salida de las herramientas sin resumir.

Solución de problemas

¿Compactando con demasiada frecuencia? La ventana de contexto del modelo puede ser pequeña, o las salidas de las herramientas pueden ser grandes. Intente habilitar session pruning.

¿El contexto se siente obsoleto después de la compactación? Use /compact Focus on <topic> para guiar el resumen, o habilite el memory flush para que las notas sobrevivan.

¿Necesita una limpieza total? /new inicia una sesión nueva sin compactar.

Para una configuración avanzada (reservar tokens, preservación de identificadores, motores de contexto personalizados, compactación del lado del servidor de OpenAI), consulte el Session management deep dive.

Relacionado

Session: gestión y ciclo de vida de la sesión.
Session pruning: recorte de resultados de herramientas.
Context: cómo se construye el contexto para los turnos del agente.
Hooks: ganchos del ciclo de vida de compactación (before_compaction, after_compaction).