Profundización en Gestión de Sesiones

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

- Enrutamiento de sesión (cómo los mensajes entrantes se mapean a un sessionKey)

- Almacenamiento de sesión (sessions.json) y qué rastrea

- Persistencia de transcripción (*.jsonl) y su estructura

- Higiene de transcripción (ajustes específicos de proveedor antes de ejecuciones)

- Límites de contexto (ventana de contexto vs tokens rastreados)

- Compactación (manual + auto-compactación) y dónde enganchar trabajo pre-compactación

- Mantenimiento silencioso (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

OpenClaw persiste sesiones en dos capas:

1. Almacenamiento de sesión (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, toggles, contadores de tokens, etc.)

2. Transcripción (<sessionId>.jsonl)

ReferenceOthersSessionManagementCompactionPage.steps.01.p7

ReferenceOthersSessionManagementCompactionPage.steps.01.p8

ReferenceOthersSessionManagementCompactionPage.steps.01.p9

A sessionKey identifies _which conversation bucket_ you're in (routing + isolation).

Patrones comunes:

- Main/direct chat (per agent): agent:<agentId>:<mainKey> (default main)

- Group: agent:<agentId>:<channel>:group:<id>

- Room/channel (Discord/Slack): agent:<agentId>:<channel>:channel:<id> or ...:room:<id>

- Cron: cron:<job.id>

- Webhook: hook:<uuid> (unless overridden)

Las reglas canónicas están documentadas en /concepts/session.

El tipo de valor del store es SessionEntry en src/config/sessions.ts.

Key fields (not exhaustive):

- sessionId: current transcript id (filename is derived from this unless sessionFile is set)

- updatedAt: last activity timestamp

- sessionFile: optional explicit transcript path override

- chatType: direct | group | room (helps UIs and send policy)

- provider, subject, room, space, displayName: metadata for group/channel labeling

Toggles:

- thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel

- sendPolicy (per-session override)

Model selection:

- providerOverride, modelOverride, authProfileOverride

Token counters (best-effort / provider-dependent):

- inputTokens, outputTokens, totalTokens, contextTokens

- compactionCount: how often auto-compaction completed for this session key

- memoryFlushAt: timestamp for last pre-compaction memory flush

- memoryFlushCompactionCount: compaction count when last flush ran

El store es seguro de editar, pero el Gateway es la autoridad: puede reescribir o rehidratar entradas mientras las sesiones se ejecutan.

Two different concepts matter:

1. Model context window: hard cap per model (tokens visible to model)

2. Session store counters: rolling stats written into sessions.json (used for /status and dashboards)

Si estás ajustando límites:

- The context window comes from model catalog (and can be overridden via config).

- contextTokens in store is a runtime estimate/reporting value; don't treat it as a strict guarantee.

Para más, ver /token-use.

In embedded Pi agent, auto-compaction triggers in two cases:

1. Overflow recovery: model returns a context overflow error → compact → retry.

2. Threshold maintenance: after a successful turn, when:

contextTokens > contextWindow - reserveTokens

Where:

- contextWindow is model's context window

- reserveTokens is headroom reserved for prompts + next model output

These are Pi runtime semantics (OpenClaw consumes events, but Pi decides when to compact).

Puedes observar compactación y estado de sesión vía:

- /status (en cualquier sesión de chat)

- openclaw status (CLI)

- openclaw sessions / sessions --json

- Modo verbose: 🧹 Auto-compaction complete + conteo de compactación

Objetivo: antes de que ocurra auto-compactación, ejecutar un turno agentic silencioso que escriba estado durable a disco (ej. memory/YYYY-MM-DD.md en workspace del agente) para que la compactación no pueda borrar contexto crítico.

OpenClaw usa enfoque de flush pre-umbral:

1. Monitorear uso de contexto de sesión.

2. Cuando cruza un "umbral suave" (debajo del umbral de compactación de Pi), ejecutar una directiva "escribir memoria ahora" silenciosa al agente.

3. Usar NO_REPLY para que el usuario no vea nada.

Config (agents.defaults.compaction.memoryFlush):

- enabled (predeterminado: true)

- softThresholdTokens (predeterminado: 4000)

- prompt (mensaje de usuario para el turno de flush)

- systemPrompt (system prompt extra adjunto para el turno de flush)

Notas:

- El prompt/system prompt predeterminado incluyen una pista NO_REPLY para suprimir entrega.

- El flush corre una vez por ciclo de compactación (rastreado en sessions.json).

- El flush corre solo para sesiones Pi embebidas (backends CLI lo saltan).

- El flush se salta cuando el workspace de sesión es solo lectura (workspaceAccess: "ro" o "none").

- Ver Memoria para el layout de archivos del workspace y patrones de escritura.

Pi también expone un hook session_before_compact en la API de extensión, pero la lógica de flush de OpenClaw vive en el lado del Gateway hoy.

- ¿Clave de sesión incorrecta? Empieza con /concepts/session y confirma el sessionKey en /status.

- ¿Desajuste store vs transcripción? Confirma el host del Gateway y la ruta del store desde openclaw status.

- ¿Spam de compactación? Revisa:

- ventana de contexto del modelo (muy pequeña)

- ajustes de compactación (reserveTokens muy alto para la ventana del modelo puede causar compactación más temprana)

- inflación de tool-result: habilita/ajusta pruning de sesión

- ¿Turnos silenciosos filtrando? Confirma que la respuesta empiece con NO_REPLY (token exacto) y que estés en un build que incluye el fix de supresión de streaming.