Gestión de sesiones y compactación (inmersión profunda)

Este documento explica cómo OpenClaw gestiona las sesiones de extremo a extremo:

• Enrutamiento de sesiones (cómo los mensajes entrantes se mapean a un sessionKey)
• Almacén de sesiones (sessions.json) y qué rastrea
• Persistencia de transcripciones (*.jsonl) y su estructura
• Higiene de transcripciones (correcciones específicas del proveedor antes de ejecuciones)
• Límites de contexto (ventana de contexto vs tokens rastreados)
• Compactación (manual + auto-compactación) y dónde conectar trabajo pre-compactación
• Tareas silenciosas (ej. escrituras de memoria que no deberían producir salida visible para el usuario)

Si quieres una visión general de alto nivel primero, empieza con:

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

Fuente de verdad: el Gateway

OpenClaw está diseñado alrededor de un único proceso Gateway que posee el estado de sesión.

Dos capas de persistencia

1. Almacén de sesiones (sessions.json): mapa clave/valor de metadatos de sesión.
2. Transcripción (<sessionId>.jsonl): transcripción append-only con estructura de árbol.

Claves de sesión (sessionKey)

Un sessionKey identifica qué bucket de conversación estás usando (enrutamiento + aislamiento).

Patrones comunes:

• Chat principal/directo (por agente): agent:<agentId>:<mainKey> (por defecto 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 sobreescriba)

Compactación: qué es

La compactación resume la conversación más antigua en una entrada compaction persistida en la transcripción y mantiene los mensajes recientes intactos.

Auto-compactación

En el agente Pi embebido, la auto-compactación se dispara en dos casos:

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 contextTokens > contextWindow - reserveTokens.

”Flush de memoria” pre-compactación (implementado)

Objetivo: antes de que ocurra la auto-compactación, ejecutar un turno silencioso con agente que escriba estado duradero en disco (ej. memory/YYYY-MM-DD.md en el workspace del agente).

Lista de verificación de solución de problemas

• ¿Clave de sesión incorrecta? Empieza con /concepts/session y confirma el sessionKey en /status.
• ¿Desajuste almacén vs transcripción? Confirma el host del Gateway y la ruta del almacén.
• ¿Spam de compactación? Verifica la ventana de contexto del modelo y los ajustes de compactación.
• ¿Turnos silenciosos que se filtran? Confirma que la respuesta empieza con NO_REPLY.