Gestión de Sesiones en OpenClaw

Gestionar el contexto en aplicaciones de chat suele ser un dolor de cabeza. Seguro que te ha pasado: el bot mezcla conversaciones de distintos usuarios o pierde el hilo porque no sabe separar un mensaje privado de uno grupal. Mantener la continuidad sin comprometer la privacidad es un reto técnico que OpenClaw resuelve de forma directa.

En esta guía te explico cómo OpenClaw organiza las sesiones y cómo puedes evitar que la información se filtre entre usuarios.

Requisitos previos

• OpenClaw instalado y funcionando.
• Un agentId configurado.
• Acceso al archivo de configuración ~/.openclaw/openclaw.json.

Inicio rápido

Por defecto, OpenClaw usa una sesión primaria por agent. Si vas a recibir mensajes de varias personas, te recomiendo activar el Secure DM mode. Esto evita que el modelo use el contexto de un usuario para responder a otro.

1. Abre tu archivo de configuración en ~/.openclaw/openclaw.json.
2. Configura el dmScope para aislar las sesiones por canal y remitente:

~/.openclaw/openclaw.json

{
  session: {
    // Secure DM mode: aísla el contexto de DM por canal + remitente.
    dmScope: "per-channel-peer",
  },
}

3. Guarda el archivo y reinicia tu Gateway.

Con esto, si Alice y Bob escriben por separado, cada uno tendrá su propia línea de tiempo y el modelo no mezclará sus datos privados.

Gateway: la fuente de verdad

Es fundamental que entiendas que el Gateway es el dueño de todo el estado. Las aplicaciones de UI (como la app de macOS o WebChat) no leen archivos locales para saber cuántos tokens llevas o qué sesiones existen; siempre le preguntan al Gateway.

• Si usas el modo remoto, las sesiones viven en el host del Gateway, no en tu máquina local.
• Los contadores de tokens (inputTokens, outputTokens, etc.) vienen directamente de los campos del store en el Gateway.
• Los archivos de sesión se guardan en ~/.openclaw/agents/<agentId>/sessions/sessions.json.

Configuración de Resets y Ciclo de Vida

OpenClaw reutiliza las sesiones hasta que expiran. Puedes controlar este comportamiento con varias políticas:

• Reset diario: Por defecto ocurre a las 4:00 AM (hora local del Gateway).
• Reset por inactividad: Puedes añadir idleMinutes para cerrar sesiones tras un tiempo sin mensajes.
• Comandos manuales: Envía /new o /reset en el chat para forzar una nueva sesión inmediatamente.
• Reset por tipo o canal: Puedes definir reglas específicas para group, direct o thread usando resetByType o resetByChannel.

Ejemplo de configuración avanzada:

{
  session: {
    dmScope: "main",
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
    },
    mainKey: "main",
  },
}

Solución de problemas

• ¿El bot mezcla información entre usuarios? Verifica tu dmScope. Si está en main, todos los DMs comparten el mismo contexto. Cámbialo a per-channel-peer.
• ¿Necesitas verificar tu configuración de seguridad? Ejecuta el comando openclaw security audit en tu terminal.
• ¿El modelo se queda “atascado” o quieres limpiar el contexto? Envía el mensaje /stop para abortar la ejecución actual o /compact para resumir el historial antiguo y liberar espacio en la ventana de contexto.
• ¿Las sesiones no aparecen correctamente en la UI? Asegúrate de que el cliente esté conectado al Gateway correcto. Recuerda que los clientes no parsean los archivos JSONL directamente.

Inspección de sesiones

Puedes usar estos comandos para ver qué está pasando bajo el capó:

• openclaw status: Muestra la ruta del store y sesiones recientes.
• openclaw sessions --json: Vuelca todas las entradas de sesión.
• /status: Envía esto como un mensaje al agente para ver el uso de contexto y estado de conectividad.

¿Necesitas ayuda para configurar tus sesiones? Prueba el AI Setup Assistant.

Próximos pasos

• Conceptos: Session Pruning
• Conceptos: Compaction
• CLI: Security Audit
• Conceptos: Memory