Análisis profundo de la gestión de sesiones

​

Dos capas de persistencia

1. Almacén de sesiones (sessions.json) - mapa clave/valor sessionKey -> SessionEntry. Pequeño, mutable, seguro para editar o eliminar entradas. Rastrea metadatos: id de sesión actual, última actividad, conmutadores, contadores de tokens.
2. Transcripción (<sessionId>.jsonl) - solo anexado, estructurada en árbol (las entradas tienen id + parentId). Almacena la conversación, las llamadas a herramientas y los resúmenes de compaction; reconstruye el contexto del modelo para turnos futuros. Los puntos de control de compaction son metadatos sobre la transcripción sucesora compactada: una nueva compaction no escribe una segunda copia .checkpoint.*.jsonl.

​

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

​

Mantenimiento del almacén y controles de disco

1. Eliminar primero los artefactos archivados más antiguos, de transcripción huérfana o de trayectoria huérfana.
2. Si aún se supera el objetivo, expulsar las entradas de sesión más antiguas y sus archivos de transcripción/trayectoria.
3. Repetir hasta que el uso esté en highWaterBytes o por debajo.

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

​

Sesiones Cron y registros de ejecución

• cron.sessionRetention (predeterminado "24h") depura las sesiones antiguas de ejecuciones cron aisladas del almacén; false lo desactiva.
• cron.runLog.keepLines depura las filas de historial de ejecución SQLite retenidas por trabajo cron (predeterminado 2000). cron.runLog.maxBytes se acepta solo por compatibilidad con registros de ejecución antiguos respaldados por archivos.

​

Claves de sesión (sessionKey)

​

Ids de sesión (sessionId)

• Restablecimiento (/new, /reset) crea un nuevo sessionId para esa sessionKey.
• Restablecimiento diario (predeterminado 4:00 AM hora local en el host del gateway) crea un nuevo sessionId en el siguiente mensaje después del límite de restablecimiento.
• Expiración por inactividad (session.reset.idleMinutes, o heredado session.idleMinutes) crea un nuevo sessionId cuando llega un mensaje después de la ventana de inactividad. Si tanto diario como inactividad están configurados, gana el que expire primero.
• Reanudación por reconexión de Control UI preserva la sesión actualmente visible para un envío de reconexión cuando el Gateway recibe el sessionId coincidente de un cliente de interfaz de operador. Esta es una señal de un solo uso; los envíos obsoletos ordinarios aún crean un nuevo sessionId.
• Eventos del sistema (heartbeat, despertares cron, notificaciones exec, contabilidad del gateway) pueden mutar la fila de sesión, pero nunca extienden la frescura del restablecimiento diario/por inactividad. El rollover de restablecimiento descarta los avisos de eventos del sistema en cola para la sesión anterior antes de construir el prompt nuevo.
• Política de bifurcación del padre usa la rama activa de OpenClaw al crear un hilo o una bifurcación de subagente. Si esa rama es demasiado grande (por encima de un límite interno fijo, actualmente 100K tokens), OpenClaw inicia el hijo con contexto aislado en lugar de fallar o heredar un historial inutilizable. El cálculo de tamaño es automático y no configurable; la configuración heredada session.parentForkMaxTokens se elimina mediante openclaw doctor --fix.
• Bifurcaciones de operador: sessions.create { parentSessionKey, fork: true } crea una nueva sesión cuya transcripción se ramifica desde el estado actual del padre (la misma maquinaria de bifurcación que los lanzamientos de subagentes, incluido el límite de tamaño anterior). La bifurcación se rechaza mientras el padre tiene una ejecución activa, hereda la selección de modelo del padre salvo que se pase una explícitamente, y marca el hijo como forkedFromParent con contadores de tokens nuevos.

​

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

• sessionId: id de la transcripción actual (el nombre de archivo deriva de esto salvo que sessionFile esté configurado)
• sessionStartedAt: marca de tiempo de inicio para el sessionId actual; la frescura del restablecimiento diario usa esto. Las filas heredadas pueden derivarlo del encabezado de sesión JSONL.
• lastInteractionAt: marca de tiempo de la última interacción real de usuario/canal; la frescura del restablecimiento por inactividad usa esto para que los eventos de Heartbeat, Cron y exec no mantengan vivas las sesiones. Las filas heredadas sin este campo recurren a la hora de inicio de sesión recuperada.
• updatedAt: marca de tiempo de la última mutación de fila del almacén, usada para listar/podar/contabilidad; no es la autoridad de frescura diaria/por inactividad.
• archivedAt: marca de tiempo de archivado opcional. Las sesiones archivadas permanecen en el almacén con su transcripción intacta y se excluyen de los listados activos normales.
• pinnedAt: marca de tiempo de fijado opcional. Las sesiones activas fijadas se ordenan antes que las sesiones sin fijar; archivar una sesión borra su fijado.
• Interoperabilidad de hilos de Codex: ambos campos siguen la forma de administración de hilos de Codex; los booleanos archived/pinned en el cable siempre se derivan de la marca de tiempo y se sellan del lado del servidor, coincidiendo con la semántica threads.archived_at de Codex y la serialización camelCase. Las marcas de tiempo de OpenClaw están en milisegundos desde epoch mientras que Codex usa segundos desde epoch, así que los puentes convierten en el límite del plugin de codex. Codex aún no tiene API de fijado (thread/archive/thread/unarchive solamente); el estado fijado permanece del lado de OpenClaw hasta que exista una, momento en el que la forma coincidente permite que las sesiones vinculadas hagan ida y vuelta del estado fijado de forma mecánica.
• lastReadAt / markedUnreadAt: marcas de tiempo de estado de lectura selladas del lado del servidor por sessions.patch { unread }; unread: false registra una lectura (establece lastReadAt, borra markedUnreadAt); unread: true marca la sesión como no leída hasta la siguiente lectura. Las filas de sesión exponen un booleano unread derivado: marcada explícitamente como no leída, o leída antes de la actividad más reciente. Las sesiones nunca marcadas como leídas permanecen con unread: false, así que las instalaciones existentes no se iluminan al actualizar.
• lastActivityAt: marca de tiempo de la última ejecución de agente completada que cuenta como actividad digna de no leído (ejecuciones de usuario, canal y Cron). Los turnos de Heartbeat y eventos internos, además de los parches de metadatos, no la actualizan; updatedAt no es una señal de actividad.
• sessionFile: anulación explícita opcional de ruta de transcripción
• chatType: direct | group | room
• provider, subject, room, space, displayName: metadatos de etiquetado de grupo/canal
• Alternadores: 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: cuántas veces se completó la autocompactación para esta clave de sesión
• memoryFlushAt / memoryFlushCompactionCount: marca de tiempo y conteo de compactaciones del último volcado de memoria previo a la compactación

​

Estructura de transcripción (*.jsonl)

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

• message: mensajes de usuario/asistente/toolResult
• custom_message: mensaje inyectado por extensión que sí entra en el contexto del modelo (se renderiza en la TUI cuando display: true, se oculta por completo cuando display: false)
• custom: estado de extensión que no entra en el contexto del modelo (para persistir estado de extensión entre recargas)
• compaction: resumen de compactación persistido con firstKeptEntryId y tokensBefore
• branch_summary: resumen persistido al navegar por una rama del árbol

​

Ventanas de contexto frente a tokens rastreados

1. Ventana de contexto del modelo: límite estricto por modelo (tokens visibles para el modelo). Proviene del catálogo de modelos y puede anularse mediante configuración.
2. Contadores del almacén de sesiones: estadísticas continuas escritas en sessions.json (usadas para /status y paneles). contextTokens es un valor de estimación/reporte en tiempo de ejecución; no lo trates como una garantía estricta.

​

Compaction: qué es

​

Límites de fragmentos y emparejamiento de herramientas

• Si la división por proporción de tokens caería entre una llamada a herramienta y su resultado, OpenClaw desplaza el límite al mensaje de llamada a herramienta del asistente en lugar de separar el par.
• Si un bloque final de resultado de herramienta empujaría el fragmento por encima del objetivo, OpenClaw conserva ese bloque de herramienta pendiente y mantiene intacta la cola sin resumir.
• Los bloques de llamadas a herramientas abortadas/con error no mantienen abierta una división pendiente.

​

Cuándo ocurre la autocompactación

1. Recuperación de desbordamiento: el modelo devuelve un error de desbordamiento de contexto (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 y otras variantes con forma de proveedor): compactar y luego reintentar. Cuando el proveedor reporta el conteo de tokens intentado, OpenClaw reenvía ese conteo observado a la compactación de recuperación de desbordamiento; si el proveedor confirma el desbordamiento pero no expone un conteo analizable, OpenClaw pasa un conteo sintético mínimamente por encima del presupuesto a los motores de compactación y diagnósticos. Si la recuperación de desbordamiento aún falla, OpenClaw muestra orientación explícita y conserva el mapeo de sesión actual en lugar de rotar silenciosamente a un id de sesión nuevo: reintenta el mensaje, ejecuta /compact o ejecuta /new.
2. Mantenimiento por umbral: después de un turno exitoso, cuando contextTokens > contextWindow - reserveTokens, donde contextWindow es la ventana de contexto del modelo y reserveTokens es el margen reservado para prompts más la siguiente salida del modelo.

• Compactación local de preflight: configura agents.defaults.compaction.maxActiveTranscriptBytes (bytes o una cadena como "20mb") para disparar compactación local antes de abrir la siguiente ejecución una vez que el archivo de transcripción activo alcance ese tamaño. Esta es una guarda de tamaño de archivo para el costo de reapertura local, no archivado sin procesar: la compactación semántica normal aún se ejecuta, y requiere truncateAfterCompaction para que el resumen compactado se convierta en una nueva transcripción sucesora.
• Precomprobación a mitad de turno: configura agents.defaults.compaction.midTurnPrecheck.enabled: true (predeterminado false) para añadir una guarda de bucle de herramientas. Después de anexar un resultado de herramienta y antes de la siguiente llamada al modelo, OpenClaw estima la presión del prompt usando la misma lógica de presupuesto de preflight que se usa al inicio del turno. Si el contexto ya no cabe, la guarda no compacta en línea: emite una señal estructurada de precomprobación a mitad de turno, detiene el envío del prompt actual y deja que el bucle externo de ejecución use la ruta de recuperación existente (truncar resultados de herramienta sobredimensionados cuando eso basta, o disparar el modo de compactación configurado y reintentar). Funciona con los modos de compactación default y safeguard, incluida la compactación safeguard respaldada por proveedor. Es independiente de maxActiveTranscriptBytes: la guarda de tamaño en bytes se ejecuta antes de que se abra un turno; la precomprobación a mitad de turno se ejecuta después, tras anexar nuevos resultados de herramienta.

​

Configuración de compactación

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

​

Proveedores de compactación conectables

• provider: id de un plugin de proveedor de compactación registrado. Déjalo sin configurar para el resumen LLM predeterminado. Configurar un provider fuerza mode: "safeguard".
• Los proveedores reciben las mismas instrucciones de compactación y política de preservación de identificadores que la ruta integrada, y safeguard aún conserva el contexto de sufijo de turnos recientes y turnos divididos después de la salida del proveedor.
• El resumen safeguard integrado redestila resúmenes previos con mensajes nuevos en lugar de preservar textualmente el resumen anterior completo.
• El modo safeguard habilita auditorías de calidad del resumen de forma predeterminada; configura qualityGuard.enabled: false para omitir el comportamiento de reintento ante salida mal formada.
• Si el proveedor falla o devuelve un resultado vacío, OpenClaw vuelve automáticamente al resumen LLM integrado. Las señales de abortar/tiempo de espera que el llamador activó explícitamente se relanzan, no se absorben, así que la cancelación siempre se respeta.

​

Superficies visibles para el usuario

• /status en cualquier sesión de chat
• openclaw status (CLI)
• openclaw sessions / openclaw sessions --json
• Registros del Gateway (pnpm gateway:watch u openclaw logs --follow): embedded run auto-compaction start + complete
• Modo detallado: 🧹 Auto-compaction complete más el conteo de compactaciones

​

Mantenimiento silencioso (NO_REPLY)

• El asistente inicia su salida con el token silencioso exacto NO_REPLY / no_reply para indicar “no entregar una respuesta al usuario”. OpenClaw lo elimina/suprime en la capa de entrega.
• La supresión exacta del token silencioso no distingue entre mayúsculas y minúsculas: NO_REPLY y no_reply cuentan ambos cuando toda la carga útil es solo el token silencioso.
• A partir de 2026.1.10, OpenClaw también suprime la transmisión de borrador/escritura cuando un fragmento parcial comienza con NO_REPLY, por lo que las operaciones silenciosas no filtran salida parcial a mitad del turno.
• Esto es solo para turnos verdaderamente en segundo plano/sin entrega; no es un atajo para solicitudes ordinarias accionables del usuario.

​

Vaciado de memoria previo a Compaction

• El prompt/prompt de sistema predeterminados incluyen una indicación NO_REPLY para suprimir la entrega.
• Cuando model está establecido, el turno de vaciado usa ese modelo sin heredar la cadena de reserva de la sesión activa, por lo que el mantenimiento solo local no recurre silenciosamente a un modelo de conversación de pago en caso de fallo.
• El vaciado se ejecuta una vez por ciclo de compactación (seguido en sessions.json).
• El vaciado se ejecuta solo para sesiones de OpenClaw incrustadas; los backends de CLI y los turnos de Heartbeat lo omiten.
• El vaciado se omite cuando el espacio de trabajo de la sesión es de solo lectura (workspaceAccess: "ro" o "none").
• Consulta Memoria para ver el diseño de archivos del espacio de trabajo y los patrones de escritura.

​

Lista de comprobación de solución de problemas

• ¿Clave de sesión incorrecta? Empieza por /concepts/session y confirma el sessionKey en /status.
• ¿Desajuste entre almacén y transcripción? Confirma el host del Gateway y la ruta del almacén desde openclaw status.
• ¿Spam de Compaction? Comprueba la ventana de contexto del modelo (si es demasiado pequeña, fuerza compactación frecuente), reserveTokens (si es demasiado alto para la ventana del modelo, causa compactación más temprana) y el exceso de resultados de herramientas (ajusta la poda de sesión).
• ¿Cada prompt parece desbordarse en un modelo local pequeño? Confirma que el proveedor informa la ventana de contexto correcta del modelo. OpenClaw puede limitar la reserva efectiva solo cuando se conoce esa ventana.
• ¿Turnos silenciosos con filtraciones? Confirma que la respuesta empieza con el token silencioso exacto NO_REPLY (sin distinción entre mayúsculas y minúsculas) y que estás en una compilación que incluye la corrección de supresión de transmisión (2026.1.10+).

​

Relacionado

• Gestión de sesiones
• Poda de sesiones
• Motor de contexto
• Referencia de configuración de agentes