Mensajes

Esta página conecta cómo OpenClaw maneja los mensajes entrantes, las sesiones, el encolamiento, el streaming y la visibilidad del razonamiento.

Flujo de mensajes (alto nivel)

Mensaje entrante
  -> enrutamiento/bindings -> clave de sesión
  -> cola (si hay una ejecución activa)
  -> ejecución del agente (streaming + herramientas)
  -> respuestas salientes (límites del canal + chunking)

Los controles principales viven en la configuración:

• messages.* para prefijos, encolamiento y comportamiento grupal.
• agents.defaults.* para streaming por bloques y valores por defecto de chunking.
• Sobrescrituras por canal (channels.whatsapp.*, channels.telegram.*, etc.) para límites y toggles de streaming.

Consulta Configuración para el esquema completo.

Deduplicación de entrada

Los canales pueden re-entregar el mismo mensaje después de reconexiones. OpenClaw mantiene una caché de corta duración indexada por canal/cuenta/peer/sesión/ID de mensaje para que entregas duplicadas no activen otra ejecución del agente.

Debounce de entrada

Mensajes consecutivos rápidos del mismo remitente pueden agruparse en un solo turno del agente vía messages.inbound. El debounce tiene alcance por canal + conversación y usa el mensaje más reciente para el threading/IDs de respuesta.

Configuración (valor global por defecto + sobrescrituras por canal):

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

Notas:

• El debounce aplica a mensajes solo de texto; los medios/adjuntos se envían de inmediato.
• Los comandos de control evitan el debounce para que permanezcan independientes.

Sesiones y dispositivos

Las sesiones son propiedad del gateway, no de los clientes.

• Los chats directos se consolidan en la clave de sesión principal del agente.
• Los grupos/canales obtienen sus propias claves de sesión.
• El almacén de sesión y las transcripciones residen en el host del gateway.

Múltiples dispositivos/canales pueden mapear a la misma sesión, pero el historial no se sincroniza completamente de vuelta a cada cliente. Recomendación: usa un dispositivo principal para conversaciones largas para evitar contexto divergente. La UI de Control y la TUI siempre muestran la transcripción de sesión respaldada por el gateway, así que son la fuente de verdad.

Detalles: Gestión de sesiones.

Cuerpos de entrada y contexto de historial

OpenClaw separa el cuerpo del prompt del cuerpo del comando:

• Body: texto del prompt enviado al agente. Puede incluir envoltorios del canal y envoltorios opcionales de historial.
• CommandBody: texto crudo del usuario para el parseo de directivas/comandos.
• RawBody: alias heredado de CommandBody (mantenido por compatibilidad).

Cuando un canal proporciona historial, usa un envoltorio compartido:

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

Para chats no directos (grupos/canales/salas), el cuerpo del mensaje actual se prefija con la etiqueta del remitente (mismo estilo usado para las entradas de historial). Esto mantiene los mensajes en tiempo real y los mensajes en cola/historial consistentes en el prompt del agente.

Los buffers de historial son solo pendientes: incluyen mensajes de grupo que no activaron una ejecución (por ejemplo, mensajes con gate de mención) y excluyen mensajes que ya están en la transcripción de la sesión.

La eliminación de directivas solo aplica a la sección del mensaje actual para que el historial permanezca intacto. Los canales que envuelven historial deben configurar CommandBody (o RawBody) con el texto original del mensaje y mantener Body como el prompt combinado. Los buffers de historial se configuran vía messages.groupChat.historyLimit (valor global por defecto) y sobrescrituras por canal como channels.slack.historyLimit o channels.telegram.accounts.<id>.historyLimit (configura 0 para desactivar).

Encolamiento y seguimientos

Si una ejecución ya está activa, los mensajes entrantes pueden encolarse, dirigirse a la ejecución actual o recolectarse para un turno de seguimiento.

• Configura vía messages.queue (y messages.queue.byChannel).
• Modos: interrupt, steer, followup, collect, más variantes de backlog.

Detalles: Encolamiento.

Streaming, chunking y batching

El streaming por bloques envía respuestas parciales mientras el modelo produce bloques de texto. El chunking respeta los límites de texto del canal y evita dividir código delimitado.

Configuraciones clave:

• agents.defaults.blockStreamingDefault (on|off, por defecto off)
• agents.defaults.blockStreamingBreak (text_end|message_end)
• agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
• agents.defaults.blockStreamingCoalesce (batching basado en inactividad)
• agents.defaults.humanDelay (pausa tipo humano entre respuestas por bloques)
• Sobrescrituras de canal: *.blockStreaming y *.blockStreamingCoalesce (canales no-Telegram requieren *.blockStreaming: true explícito)

Detalles: Streaming + chunking.

Visibilidad del razonamiento y tokens

OpenClaw puede exponer u ocultar el razonamiento del modelo:

• /reasoning on|off|stream controla la visibilidad.
• El contenido del razonamiento sigue contando para el uso de tokens cuando lo produce el modelo.
• Telegram soporta el streaming del razonamiento en la burbuja de borrador.

Detalles: Directivas de thinking + razonamiento y Uso de tokens.

Prefijos, threading y respuestas

El formato de mensajes salientes se centraliza en messages:

• messages.responsePrefix, channels.<channel>.responsePrefix y channels.<channel>.accounts.<id>.responsePrefix (cascada de prefijo saliente), más channels.whatsapp.messagePrefix (prefijo entrante de WhatsApp)
• Threading de respuestas vía replyToMode y valores por defecto por canal

Detalles: Configuración y documentación de canales.