Gestión de Sesiones

OpenClaw trata ''una sesión de chat directo por agente'' como primaria. Los chats directos colapsan a ''agent:<agentId>:<mainKey>'' (predeterminado ''main''), mientras que los chats de grupo/canal obtienen sus propias claves. ''session.mainKey'' se respeta.

Usa ''session.dmScope'' para controlar cómo se agrupan los ''mensajes directos'':

- ''main'' (predeterminado): todos los DMs comparten la sesión principal para continuidad.

- ''per-peer'': aísla por id de remitente a través de canales.

- ''per-channel-peer'': aísla por canal + remitente (recomendado para bandejas multi-usuario).

- ''per-account-channel-peer'': aísla por cuenta + canal + remitente (recomendado para bandejas multi-cuenta).

Usa ''session.identityLinks'' para mapear ids de pares con prefijo de proveedor a una identidad canónica para que la misma persona comparta una sesión DM a través de canales cuando usa ''per-peer'', ''per-channel-peer'', o ''per-account-channel-peer''.

Todo el estado de sesión es propiedad del gateway (el OpenClaw "maestro"). Los clientes UI (app macOS, WebChat, etc.) deben consultar al gateway por listas de sesión y conteos de tokens en lugar de leer archivos locales.

- En modo remoto, el almacén de sesiones que te importa vive en el host del gateway remoto, no en tu Mac.

- Los conteos de tokens mostrados en UIs vienen de los campos del almacén del gateway (''inputTokens'', ''outputTokens'', ''totalTokens'', ''contextTokens''). Los clientes no analizan transcripciones JSONL para "corregir" totales.

- En el host del gateway:

- Archivo de almacén: ''~/.openclaw/agents/<agentId>/sessions/sessions.json'' (por agente).

- openclaw gateway call sessions.list --params {}' — obtiene sesiones del gateway en ejecución (usa --url/--token para acceso remoto al gateway).

- Envía ''/status'' como mensaje independiente en el chat para ver si el agente es alcanzable, cuánto del contexto de sesión se usa, estados actuales de thinking/verbose, y cuándo se refrescaron tus credenciales web de WhatsApp (ayuda a detectar necesidad de re-enlace).

- Envía ''/context list'' o ''/context detail'' para ver qué hay en el prompt del sistema y archivos inyectados del espacio de trabajo (y los mayores contribuyentes de contexto).

- Envía ''/stop'' como mensaje independiente para abortar la ejecución actual, limpiar seguimientos en cola para esa sesión, y detener cualquier ejecución de sub-agente generada desde ella (la respuesta incluye el conteo detenido).

- Envía ''/compact'' (instrucciones opcionales) como mensaje independiente para resumir contexto antiguo y liberar espacio de ventana. Ver [/concepts/compaction](/concepts/compaction).

Cada entrada de sesión registra de dónde vino (mejor esfuerzo) en ''origin'':

- ''label'': etiqueta humana (resuelta de etiqueta de conversación + asunto de grupo/canal)

Cuando una sesión se acerca a la auto-compactación, OpenClaw puede ejecutar un turno de ''vaciado de memoria silencioso'' que recuerda al modelo escribir notas duraderas en disco. Esto solo se ejecuta cuando el espacio de trabajo es escribible. Ver ''Memoria'' y ''Compactación''.

- Los chats directos siguen ''session.dmScope'' (predeterminado ''main'').

- ''main'': ''agent:<agentId>:<mainKey>'' (continuidad a través de dispositivos/canales).

- Múltiples números de teléfono y canales pueden mapear a la misma clave principal del agente; actúan como transportes hacia una conversación.

- ''per-peer''：''agent:<agentId>:dm:<peerId>''。

- ''per-channel-peer''：''agent:<agentId>:<channel>:dm:<peerId>''。

- ''per-account-channel-peer'': ''agent:<agentId>:<channel>:<accountId>:dm:<peerId>'' (''accountId'' por defecto es ''default'').

Si ''session.identityLinks'' coincide con un id de par con prefijo de proveedor (por ejemplo ''telegram:123''), la clave canónica reemplaza ''<peerId>'' para que la misma persona comparta una sesión a través de canales.

- Los chats de grupo aíslan estado: ''agent:<agentId>:<channel>:group:<id>'' (salas/canales usan ''agent:<agentId>:<channel>:channel:<id>'').

- Los temas de foro de Telegram añaden '':topic:<threadId>'' al id del grupo para aislamiento.

- Las claves legacy ''group:<id>'' aún se reconocen para migración.

- Los contextos entrantes pueden aún usar ''group:<id>''; el canal se infiere de ''Provider'' y se normaliza a la forma canónica ''agent:<agentId>:<channel>:group:<id>''.

- Otras fuentes:

- Cron Jobs：''cron:<job.id>''

- Política de reinicio: las sesiones se reutilizan hasta que expiran, y la expiración se evalúa en el próximo mensaje entrante.

- Reinicio diario: por defecto 4:00 AM hora local en el host del gateway. Una sesión está obsoleta una vez que su última actualización es anterior al tiempo de reinicio diario más reciente.

- Reinicio por inactividad (opcional): ''idleMinutes'' añade una ventana de inactividad deslizante. Cuando tanto el reinicio diario como por inactividad están configurados, ''el que expire primero'' fuerza una nueva sesión.

- Solo inactividad legacy: si configuras ''session.idleMinutes'' sin ninguna configuración ''session.reset''/''resetByType'', OpenClaw permanece en modo solo inactividad por compatibilidad hacia atrás.

- Sobrescrituras por tipo (opcional): ''resetByType'' te permite sobrescribir la política para sesiones ''dm'', ''group'', y ''thread'' (thread = hilos Slack/Discord, temas Telegram, hilos Matrix cuando el conector los proporciona).

- Sobrescrituras por canal (opcional): ''resetByChannel'' sobrescribe la política de reinicio para un canal (aplica a todos los tipos de sesión para ese canal y tiene precedencia sobre ''reset''/''resetByType'').

- Disparadores de reinicio: ''/new'' o ''/reset'' exactos (más cualquier extra en ''resetTriggers'') inician un id de sesión fresco y pasan el resto del mensaje. ''/new <model>'' acepta un alias de modelo, ''provider/model'', o nombre de proveedor (coincidencia difusa) para configurar el modelo de la nueva sesión. Si ''/new'' o ''/reset'' se envían solos, OpenClaw ejecuta un turno corto de saludo "hola" para confirmar el reinicio.

- Reinicio manual: elimina claves específicas del almacén o remueve la transcripción JSONL; el próximo mensaje las recrea.

- Los trabajos cron aislados siempre generan un ''sessionId'' fresco por ejecución (sin reuso por inactividad).

Bloquea entrega para tipos específicos de sesión sin listar ids individuales:

{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } }
      ],
      default: "allow"
    }
  }
}

Sobrescrituras en runtime (solo propietario):

- ''/send on'' → permitir para esta sesión

- ''/send off'' → denegar para esta sesión

- ''/send inherit'' → limpiar sobrescritura y usar reglas de configuración

Envía estos como mensajes independientes para que se registren.

- Mantén la clave principal dedicada a tráfico 1:1; deja que los grupos mantengan sus propias claves.

- Al automatizar limpieza, elimina claves individuales en lugar de todo el almacén para preservar contexto en otros lugares.

- openclaw gateway call sessions.list --params {}' — obtiene sesiones del gateway en ejecución (usa --url/--token para acceso remoto al gateway).

- Envía ''/status'' como mensaje independiente en el chat para ver si el agente es alcanzable, cuánto del contexto de sesión se usa, estados actuales de thinking/verbose, y cuándo se refrescaron tus credenciales web de WhatsApp (ayuda a detectar necesidad de re-enlace).

- Envía ''/context list'' o ''/context detail'' para ver qué hay en el prompt del sistema y archivos inyectados del espacio de trabajo (y los mayores contribuyentes de contexto).

- Envía ''/stop'' como mensaje independiente para abortar la ejecución actual, limpiar seguimientos en cola para esa sesión, y detener cualquier ejecución de sub-agente generada desde ella (la respuesta incluye el conteo detenido).

- Envía ''/compact'' (instrucciones opcionales) como mensaje independiente para resumir contexto antiguo y liberar espacio de ventana. Ver [/concepts/compaction](/concepts/compaction).

- Las transcripciones JSONL pueden abrirse directamente para revisar turnos completos.

Cada entrada de sesión registra de dónde vino (mejor esfuerzo) en ''origin'':

- ''label'': etiqueta humana (resuelta de etiqueta de conversación + asunto de grupo/canal)

Cada entrada de sesión registra de dónde vino (mejor esfuerzo) en ''origin'':

- ''label'': etiqueta humana (resuelta de etiqueta de conversación + asunto de grupo/canal)

- ''provider'': id de canal normalizado (incluyendo extensiones)

- ''from''/''to'': ids de enrutamiento crudos del sobre entrante

- ''accountId'': id de cuenta del proveedor (cuando multi-cuenta)

- ''threadId'': id de hilo/tema cuando el canal lo soporta