​

Gestión de sesiones y compactación (análisis profundo)

• Enrutamiento de sesiones (cómo los mensajes entrantes se asignan a un sessionKey)
• Almacén de sesiones (sessions.json) y qué rastrea
• Persistencia de transcripciones (*.jsonl) y su estructura
• Higiene de transcripciones (ajustes específicos del proveedor antes de las ejecuciones)
• Límites de contexto (ventana de contexto vs tokens rastreados)
• Compactación (compactación manual + automática) y dónde enganchar trabajo de pre-compactación
• Mantenimiento silencioso (p. ej., escrituras de memoria que no deberían producir salida visible para el usuario)

• /concepts/session
• /concepts/compaction
• /concepts/session-pruning
• /reference/transcript-hygiene

​

Fuente de la verdad: el Gateway

• Las UIs (app de macOS, UI de Control web, TUI) deben consultar al Gateway para obtener listas de sesiones y recuentos de tokens.
• En modo remoto, los archivos de sesión están en el host remoto; “revisar sus archivos locales del Mac” no reflejará lo que está usando el Gateway.

​

Dos capas de persistencia

1. Almacén de sesiones (sessions.json)
   • Mapa clave/valor: sessionKey -> SessionEntry
   • Pequeño, mutable, seguro de editar (o eliminar entradas)
   • Rastrea metadatos de sesión (ID de sesión actual, última actividad, interruptores, contadores de tokens, etc.)
2. Transcripción (<sessionId>.jsonl)
   • Transcripción de solo anexado con estructura de árbol (las entradas tienen id + parentId)
   • Almacena la conversación real + llamadas a herramientas + resúmenes de compactación
   • Se usa para reconstruir el contexto del modelo para turnos futuros

​

Ubicaciones en disco

• Almacén: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcripciones: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Sesiones de temas de Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

Claves de sesión (sessionKey)

• Chat principal/directo (por agente): agent:<agentId>:<mainKey> (predeterminado main)
• Grupo: agent:<agentId>:<channel>:group:<id>
• Sala/canal (Discord/Slack): agent:<agentId>:<channel>:channel:<id> o ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (a menos que se sobrescriba)

​

IDs de sesión (sessionId)

• Reinicio (/new, /reset) crea un nuevo sessionId para ese sessionKey.
• Reinicio diario (predeterminado a las 4:00 a. m. hora local en el host del Gateway) crea un nuevo sessionId en el siguiente mensaje después del límite de reinicio.
• Expiración por inactividad (session.reset.idleMinutes o legado session.idleMinutes) crea un nuevo sessionId cuando llega un mensaje después de la ventana de inactividad. Cuando se configuran tanto el reinicio diario como la inactividad, gana el que expire primero.

​

Esquema del almacén de sesiones (sessions.json)

• sessionId: ID de transcripción actual (el nombre del archivo se deriva de esto a menos que se establezca sessionFile)
• updatedAt: marca de tiempo de la última actividad
• sessionFile: anulación opcional explícita de la ruta de la transcripción
• chatType: direct | group | room (ayuda a las UIs y a la política de envío)
• provider, subject, room, space, displayName: metadatos para etiquetado de grupos/canales
• Interruptores:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (anulación por sesión)
• Selección de modelo:
  • providerOverride, modelOverride, authProfileOverride
• Contadores de tokens (mejor esfuerzo / dependiente del proveedor):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: con qué frecuencia se completó la auto-compactación para esta clave de sesión
• memoryFlushAt: marca de tiempo del último vaciado de memoria previo a la compactación
• memoryFlushCompactionCount: recuento de compactaciones cuando se ejecutó el último vaciado

​

Estructura de la transcripción (*.jsonl)

• Primera línea: encabezado de sesión (type: "session", incluye id, cwd, timestamp, parentSession opcional)
• Luego: entradas de sesión con id + parentId (árbol)

• message: mensajes de usuario/asistente/resultado de herramienta
• custom_message: mensajes inyectados por extensiones que sí entran en el contexto del modelo (pueden ocultarse de la UI)
• custom: estado de extensión que no entra en el contexto del modelo
• compaction: resumen de compactación persistido con firstKeptEntryId y tokensBefore
• branch_summary: resumen persistido al navegar una rama del árbol

​

Ventanas de contexto vs tokens rastreados

1. Ventana de contexto del modelo: límite rígido por modelo (tokens visibles para el modelo)
2. Contadores del almacén de sesiones: estadísticas acumuladas escritas en sessions.json (usadas para /status y paneles)

• La ventana de contexto proviene del catálogo de modelos (y puede anularse vía configuración).
• contextTokens en el almacén es un valor de estimación/reporte en tiempo de ejecución; no lo trate como una garantía estricta.

​

Compactación: qué es

• El resumen de compactación
• Mensajes posteriores a firstKeptEntryId

​

Cuándo ocurre la auto-compactación (runtime de Pi)

1. Recuperación por desbordamiento: el modelo devuelve un error de desbordamiento de contexto → compactar → reintentar.
2. Mantenimiento por umbral: después de un turno exitoso, cuando:

• contextWindow es la ventana de contexto del modelo
• reserveTokens es el margen reservado para prompts + la siguiente salida del modelo

​

Ajustes de compactación (reserveTokens, keepRecentTokens)

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

• Si compaction.reserveTokens < reserveTokensFloor, OpenClaw lo eleva.
• El piso predeterminado es 20000 tokens.
• Establezca agents.defaults.compaction.reserveTokensFloor: 0 para desactivar el piso.
• Si ya es más alto, OpenClaw lo deja intacto.

​

Superficies visibles para el usuario

• /status (en cualquier sesión de chat)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Modo detallado: 🧹 Auto-compaction complete + recuento de compactaciones

​

Mantenimiento silencioso (NO_REPLY)

• El asistente inicia su salida con NO_REPLY para indicar “no entregar una respuesta al usuario”.
• OpenClaw elimina/suprime esto en la capa de entrega.

​

“Vaciado de memoria” previo a la compactación (implementado)

1. Monitorear el uso de contexto de la sesión.
2. Cuando cruza un “umbral suave” (por debajo del umbral de compactación de Pi), ejecutar una directiva silenciosa de “escribir memoria ahora” al agente.
3. Usar NO_REPLY para que el usuario no vea nada.

• enabled (predeterminado: true)
• softThresholdTokens (predeterminado: 4000)
• prompt (mensaje del usuario para el turno de vaciado)
• systemPrompt (prompt de sistema adicional anexado para el turno de vaciado)

• El prompt predeterminado/el prompt del sistema incluyen una pista NO_REPLY para suprimir la entrega.
• El vaciado se ejecuta una vez por ciclo de compactación (rastreado en sessions.json).
• El vaciado solo se ejecuta para sesiones Pi embebidas (los backends de CLI lo omiten).
• El vaciado se omite cuando el espacio de trabajo de la sesión es de solo lectura (workspaceAccess: "ro" o "none").
• Vea Memory para el diseño de archivos del espacio de trabajo y los patrones de escritura.

​

Lista de verificación de solución de problemas

• ¿Clave de sesión incorrecta? Comience con /concepts/session y confirme el sessionKey en /status.
• ¿Desajuste entre almacén y transcripción? Confirme el host del Gateway y la ruta del almacén desde openclaw status.
• ¿Spam de compactación? Verifique:
  • ventana de contexto del modelo (demasiado pequeña)
  • ajustes de compactación (reserveTokens demasiado alto para la ventana del modelo puede causar compactación más temprana)
  • inflación de resultados de herramientas: habilite/ajuste la poda de sesiones
• ¿Se filtran turnos silenciosos? Confirme que la respuesta comience con NO_REPLY (token exacto) y que esté en una versión que incluya la corrección de supresión de streaming.