Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 anteriores en un resumen para que el chat pueda continuar.

​
Cómo funciona

  1. Los turnos anteriores 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 Compaction, 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. Compaction solo cambia lo que el modelo ve en el siguiente turno.

​
Compaction automática

Compaction 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>.
Antes de compactar, OpenClaw recuerda automáticamente al agente que guarde notas importantes en archivos de memoria. Esto evita la pérdida de contexto.
OpenClaw detecta el desbordamiento de contexto a partir de estos patrones de error de 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

​
Compaction manual

Escribe /compact en cualquier chat para forzar una Compaction. Agrega instrucciones para guiar el resumen: 
/compact Focus on the API design decisions
Cuando agents.defaults.compaction.keepRecentTokens está configurado, la Compaction manual respeta ese punto de corte de Pi y mantiene la cola reciente en el contexto reconstruido. Sin un presupuesto explícito de conservación, la Compaction manual se comporta como un punto de control estricto y continúa solo desde el nuevo resumen.

​
Configuración

Configura Compaction bajo agents.defaults.compaction en tu openclaw.json. Los controles 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, Compaction 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 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 de Ollama dedicado al resumen: 
{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "ollama/llama3.1:8b"
      }
    }
  }
}
Cuando no está configurado, Compaction empieza con el modelo de sesión activo. Si el resumen falla con un error de proveedor apto para respaldo de modelo, OpenClaw reintenta ese intento de Compaction a través de la cadena de respaldo de modelo existente de la sesión. La elecció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.

​
Conservación de identificadores

El resumen de Compaction conserva identificadores opacos de forma predeterminada (identifierPolicy: "strict"). Anula con identifierPolicy: "off" para deshabilitarlo, o identifierPolicy: "custom" más identifierInstructions para orientación personalizada.

​
Guarda de bytes de transcripción activa

Cuando agents.defaults.compaction.maxActiveTranscriptBytes está configurado, OpenClaw desencadena la Compaction local normal antes de una ejecución si el JSONL activo alcanza ese tamaño. Esto resulta útil para sesiones de larga duración en las que la gestión de contexto del lado del proveedor puede mantener saludable el contexto del modelo mientras la transcripción local sigue creciendo. No divide bytes JSONL sin procesar; pide a la canalización normal de Compaction que cree un resumen semántico.
La guarda de bytes requiere truncateAfterCompaction: true. Sin rotación de transcripción, el archivo activo no se reduciría y la guarda permanecería inactiva.

​
Transcripciones sucesoras

Cuando agents.defaults.compaction.truncateAfterCompaction está habilitado, OpenClaw no reescribe la transcripción existente en el mismo archivo. Crea una nueva transcripción sucesora activa a partir del resumen de Compaction, el estado conservado y la cola sin resumir, y luego mantiene el JSONL anterior como origen archivado del punto de control. Las transcripciones sucesoras también descartan turnos largos de usuario duplicados exactos que llegan dentro de una ventana corta de reintento, para que las tormentas de reintentos del canal no se transfieran a la siguiente transcripción activa después de Compaction. Los puntos de control previos a Compaction se conservan solo mientras permanezcan por debajo del límite de tamaño de punto de control de OpenClaw; las transcripciones activas sobredimensionadas aún se compactan, pero OpenClaw omite la gran instantánea de depuración en lugar de duplicar el uso de disco.

​
Avisos de Compaction

De forma predeterminada, Compaction se ejecuta de forma silenciosa. Configura notifyUser para mostrar mensajes breves de estado cuando Compaction comienza y finaliza: 
{
  agents: {
    defaults: {
      compaction: {
        notifyUser: true,
      },
    },
  },
}

​
Vaciado de memoria

Antes de Compaction, OpenClaw puede ejecutar un turno de vaciado silencioso de memoria 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 Compaction conectables

Los plugins pueden registrar un proveedor de Compaction 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 integrada. 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 Compaction y la misma política de conservación de identificadores que la ruta integrada, y OpenClaw sigue conservando el contexto de sufijo de turnos recientes y turnos divididos después de la salida del proveedor.
Si el proveedor falla o devuelve un resultado vacío, OpenClaw recurre al resumen LLM integrado.

​
Compaction frente a poda

CompactionPoda
Qué haceResume la conversación anteriorRecorta resultados antiguos de herramientas
¿Guardado?Sí (en la transcripción de la sesión)No (solo en memoria, por solicitud)
AlcanceToda la conversaciónSolo resultados de herramientas
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 Compaction? Usa /compact Focus on <topic> para guiar el resumen, o habilita el vaciado de memoria para que las notas sobrevivan. ¿Necesitas empezar de cero? /new inicia una sesión nueva sin compactar. Para configuración avanzada (tokens reservados, conservación de identificadores, motores de contexto personalizados, Compaction 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 la sesión.
  • 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 Compaction (before_compaction, after_compaction).