Interfaz de Compactación v2.1.0
Sistema de compactación de memoria para la Interfaz de Control OpenClaw: ejecución en segundo plano con notificaciones toast, activación automática en umbrales de tokens configurables, párrafo de resumen de conversación en la salida compactada, pestaña de configuración dedicada con selector de modelo e historial de resultados.
Estado: ✅ Activo
| Componente | Estado |
|---|---|
| Botón de Indicador de Contexto | ✅ Funcionando |
| Compactación en Segundo Plano (toast) | ✅ Funcionando |
| Activación Automática de Compactación | ✅ Funcionando |
| Párrafo de Resumen de Conversación | ✅ Funcionando |
| Pestaña de Configuración (registrada como plugin) | ✅ Funcionando |
| Selector de Modelo | ✅ Funcionando |
| Almacenamiento y Visualizador del Último Resultado | ✅ Funcionando |
| Persistencia y Recarga de Configuración | ✅ Funcionando |
| Jerarquía de Autenticación (OAuth > API > Respaldo) | ✅ Funcionando |
| Filtros de Historial de Chat | ✅ Funcionando |
| Aislamiento Total en Segundo Plano (sin interferencia en el chat) | ✅ Funcionando |
Funcionalidades
1. Botón de Indicador de Contexto (app-render.helpers.ts)
Un anillo de progreso SVG circular en la barra de herramientas del chat que también sirve como activador manual de compactación.
- Ubicación: Después del selector de sesión en
renderChatControls() - Fuente de datos:
sessionsResult.sessions[].totalTokensycontextTokensde las filas de sesión - Colores: Verde (<60%), Amarillo (60-85%), Rojo (≥85%)
- Deshabilitado: Cuando la utilización es <20% o durante una compactación activa
- Tooltip: Muestra "Contexto: XK / YK tokens (Z%)"
2. Compactación en Segundo Plano (Toast)
Al hacer clic (o activación automática), la compactación se ejecuta en segundo plano usando el sistema estándar de toast en la esquina inferior derecha — sin modal bloqueante. La interfaz de usuario permanece completamente interactiva.
- Toast en ejecución: Muestra "Compactación de Memoria" con un spinner
- Toast completado: Muestra "Compactado: XK → YK" con una marca de verificación (se descarta automáticamente después de 5s)
- Toast de error: Muestra el mensaje de fallo (se descarta automáticamente después de 5s)
- Utiliza el sistema
backgroundJobToastsconsistente con todos los demás procesos en segundo plano (cron, extracción de conocimiento, etc.)
3. Compactación Automática
Después de cada respuesta del chat (evento final), la interfaz verifica el uso de tokens contra el umbral configurado. Si se supera:
- La compactación en segundo plano se activa automáticamente
- El toast muestra "Auto-Compactando (X%)" con la utilización actual
- Un debounce de 5 minutos evita activaciones repetidas
- El chat se actualiza automáticamente después de una compactación exitosa
- Eliminación silenciosa del toast si no se compactó nada
4. Párrafo de Resumen de Conversación
Cada salida de compactación ahora comienza con una sección ## Resumen de Conversación antes de la sección estructurada ## Objetivo. Es un párrafo en lenguaje natural de 3 a 6 oraciones que:
- Describe el tema o temas generales de la conversación
- Explica el flujo de la discusión y las transiciones clave
- Resume cómo progresó la conversación
- Está escrito en tiempo pasado como una visión narrativa general
Implementación: Se inyectan instrucciones personalizadas en la llamada LLM de compactación upstream a través de compact.ts. La instrucción se antepone a cualquier instrucción personalizada proporcionada por el usuario (de /compact [instrucciones]), por lo que ambas coexisten.
Ejemplo de salida:
## Resumen de Conversación
La conversación comenzó con el usuario solicitando mejoras en el sistema de
compactación, específicamente pasar de un modal bloqueante a toasts en segundo
plano. Luego, la discusión se centró en agregar una pestaña de configuración con
controles de compactación automática. Después de implementar y probar esas
funcionalidades, el usuario notó que la configuración no persistía entre
navegaciones de pestañas, lo que llevó a una corrección de la caché de estado
a nivel de módulo. Finalmente, el usuario solicitó agregar un párrafo de resumen
narrativo a la salida de compactación para un mejor contexto.
## Objetivo
...
5. Pestaña de Configuración (Registrada como Plugin)
Una pestaña de Compactación dedicada bajo el grupo de navegación Agente, registrada a través de la arquitectura de Plugin UI.
Registro: plugins-ui.ts → BUILTIN_UI_VIEWS con id: "compaction", group: "agent", position: 7, icon: "archive"
Tarjetas:
Tarjeta de Compactación Automática
- Alternar: Activar/desactivar la compactación automática
- Control deslizante de umbral: 10% a 95% (por defecto: 60%)
- Codificado por colores: Verde (<60%), Amarillo (60-85%), Rojo (≥85%)
Tarjeta de Modelo
- Desplegable: Seleccionar un modelo específico para la compactación o usar el predeterminado de la sesión
- Agrupado por proveedor con tamaños de ventana de contexto mostrados
- Aviso de advertencia cuando se selecciona un modelo personalizado (recordatorio de clave API)
- Respaldo: Si el modelo personalizado falla, vuelve automáticamente al predeterminado de la sesión
Tarjeta de Almacenamiento de Resultados
- Alternar: Optar por guardar el texto de resumen compactado para su revisión
Tarjeta de Última Compactación
- Antes/Después: Grandes conteos de tokens con estilo en una cuadrícula de 2 columnas
- Estadísticas: Tokens ahorrados, porcentaje de reducción, tipo de activación, marca de tiempo, clave de sesión
- Ver Resultados: Visor de resumen expandible (cuando el almacenamiento está habilitado)
- Limpiar: Restablecer el resultado almacenado
- Pista: Muestra el mensaje "Habilitar Almacenar Resultados" cuando el almacenamiento está desactivado
Gestión de Estado:
- El estado a nivel de módulo persiste entre renderizados dentro de una sesión
- La configuración se recarga desde el backend cada vez que se visita la pestaña (umbral de caducidad de 2 segundos)
resetCompactionSettingsState()está exportada para pruebas y cambios de pestaña
6. Jerarquía de Autenticación
La compactación usa resolveApiKeyForProvider a través de getApiKeyForModel — la misma cadena de autenticación que el chat:
OAuth → Clave API → Respaldo
No se necesita configuración separada. Si OAuth (Claude Max) está configurado como el perfil de autenticación principal, la compactación lo usa automáticamente. La selección de modelo personalizado usa esta misma cadena de autenticación de forma independiente.
7. Almacenamiento de Resultados
Cuando está habilitado, el resultado de compactación más reciente se persiste en {agentDir}/compaction-config.json:
{
"settings": {
"autoEnabled": true,
"autoThresholdPercent": 60,
"storeLastResult": true,
"compactionModel": "anthropic/claude-sonnet-4-6"
},
"lastResult": {
"timestamp": 1709283600000,
"trigger": "manual",
"tokensBefore": 50614,
"tokensAfter": 4766,
"tokensSaved": 45848,
"percentReduction": 91,
"sessionKey": "agent:main:main",
"summary": "## Resumen de Conversación\nLa conversación se centró en...\n\n## Objetivo\n..."
}
}
Cuando el almacenamiento está desactivado, los metadatos (marcas de tiempo, conteos de tokens) aún se guardan, pero el texto de resumen se omite.
8. Filtros de Historial de Chat
- Filtrado de NO_REPLY/HEARTBEAT_OK: Omite los mensajes del asistente que contienen exactamente estos textos
- Divisor de compactación: Renderiza una línea divisoria etiquetada para mensajes con
__openclaw.kind === "compaction"
Arquitectura
RPCs del Backend
| Método | Descripción |
|---|---|
sessions.compact | Ejecutar compactación (registra el resultado después de completarse) |
compaction.getSettings | Leer configuración desde el archivo de configuración |
compaction.saveSettings | Actualizar configuración (umbral se ajusta automáticamente entre 10-95%) |
compaction.getLastResult | Obtener el último resultado de compactación almacenado |
compaction.clearLastResult | Limpiar el resultado almacenado |
Archivos Modificados
| Archivo | Propósito |
|---|---|
src/gateway/server-methods/compaction.ts | RPCs de configuración, E/S de configuración, registro de resultados |
src/gateway/server-methods/sessions.ts | RPC sessions.compact (registra el resultado después de la compactación) |
src/gateway/server-methods/plugins-ui.ts | Registro de vistas de plugin |
src/gateway/server-methods.ts | Cableado de handlers |
src/gateway/server-methods-list.ts | Registro de métodos |
src/gateway/method-scopes.ts | Registro de ámbitos |
src/agents/pi-embedded-runner/compact.ts | Inyección de instrucciones de resumen de chat |
ui/src/ui/app-render.helpers.ts | Indicador de contexto + activador de toast en segundo plano |
ui/src/ui/app-gateway.ts | Verificación de compactación automática después del evento final |
ui/src/ui/views/compaction-settings.ts | Vista de pestaña de configuración |
ui/src/ui/app-render.ts | Cableado e importación de vistas |
ui/src/ui/views/chat.ts | Filtros de historial de chat |
Archivo de Configuración
{agentDir}/compaction-config.json — por agente, creado en el primer guardado de configuración.
Registro del Plugin
La pestaña de compactación se registra como una vista de plugin integrada en plugins-ui.ts:
{
id: "compaction",
label: "Compactación",
subtitle: "Gestión de Memoria",
icon: "archive",
group: "agent",
position: 7,
pluginId: "compaction-ui",
}
Problemas Conocidos
- La configuración no persiste entre visitas a la pestaña: Corregido en v2.1.0. La bandera
_state.loadeda nivel de módulo impedía las recargas. Ahora se recarga cada 2 segundos al volver a la pestaña. - El selector de modelo requiere claves API: Si seleccionas un modelo personalizado, asegúrate de que la clave API del proveedor esté configurada. La interfaz muestra un aviso de advertencia.
- Formato del modelo de compactación: Debe ser formato
"proveedor/modelo"(ej."anthropic/claude-sonnet-4-6"). Los formatos no válidos se ignoran silenciosamente y se recurre al predeterminado de la sesión. - La propagación del skip set de parentId debe ser solo de mensajes: Al filtrar mensajes de vaciado de memoria de
readSessionMessages, el skip set SOLO debe propagarse a través de entradas con un campomessage. Las entradas de protocolo que no son mensajes (type:"custom") actúan como puente entre turnos lógicos — si sus IDs entran en el skip set, toda la conversación restante se oculta. La corrección: solo verificar las entradasparsed?.messagecontra el skip set, y solo agregar sus IDs a este. - Sin modal bloqueante — nunca: El botón indicador en
app-render.helpers.tsNUNCA debe renderizar un overlay modal de pantalla completa. La compactación es un proceso en segundo plano; todo el estado se comunica a través del sistema de toast en la esquina inferior derecha. Elimina cualquierposition:fixed; inset:0overlay condicionado acompactState.phase. El botón puede mostrar un ícono de spinner mientras se ejecuta, pero no debe bloquear la interfaz.
Registro de Cambios
v2.1.0
- Párrafo de resumen de conversación: La salida de compactación ahora comienza con un párrafo narrativo
## Resumen de Conversaciónantes de las secciones estructuradas - Selector de modelo: Elige un modelo específico para la compactación o usa el predeterminado de la sesión, con desplegable agrupado por proveedor
- Corrección de recarga de configuración: La pestaña ahora recarga la configuración desde el backend cada 2s en lugar de almacenarla en caché para siempre
- Archivos de referencia actualizados: Sincronizados
references/con el código fuente actual
v2.0.0
- Compactación en segundo plano: Reemplazó el modal bloqueante de pantalla completa por un toast de trabajo en segundo plano
- Compactación automática: Se activa después de la respuesta del chat cuando el uso de tokens supera el umbral (configurable, predeterminado 60%, debounce de 5 minutos)
- Pestaña de configuración: Pestaña de Compactación registrada como plugin bajo el grupo de navegación Agente
- Registro de resultados:
sessions.compactregistra conteos de tokens antes/después y resumen opcional - Jerarquía de autenticación: Misma cadena OAuth → API → Respaldo que el chat
- RPCs de configuración:
compaction.getSettings,compaction.saveSettings,compaction.getLastResult,compaction.clearLastResult
v1.0.0
- Versión inicial: Botón de indicador de contexto, modal bloqueante con fases animadas, RPC
sessions.compactcon resumen LLM, filtrado de historial de chat NO_REPLY/HEARTBEAT_OK, líneas divisorias de compactación