Saltar para o conteúdo principal

​
Mensagens

Esta página reúne como o OpenClaw lida com mensagens de entrada, sessões, enfileiramento, streaming e visibilidade do raciocínio.

​
Fluxo de mensagens (visão geral)

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)
Principais ajustes ficam na configuração:
  • messages.* para prefixos, enfileiramento e comportamento em grupos.
  • agents.defaults.* para streaming em blocos e padrões de fragmentação.
  • Substituições por canal (channels.whatsapp.*, channels.telegram.*, etc.) para limites e alternâncias de streaming.
Veja Configuração para o esquema completo.

​
Deduplicação de entrada

Canais podem reenviar a mesma mensagem após reconexões. O OpenClaw mantém um cache de curta duração com chave por canal/conta/par/sessão/id da mensagem para que entregas duplicadas não acionem outra execução do agente.

​
Debouncing de entrada

Mensagens rápidas e consecutivas do mesmo remetente podem ser agrupadas em um único turno do agente via messages.inbound. O debouncing é delimitado por canal + conversa e usa a mensagem mais recente para encadeamento/IDs de resposta. Configuração (padrão global + substituições por canal): 
{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}
Notas:
  • O debounce se aplica a mensagens somente de texto; mídia/anexos são enviados imediatamente.
  • Comandos de controle ignoram o debounce para permanecerem independentes.

​
Sessões e dispositivos

As sessões pertencem ao gateway, não aos clientes.
  • Conversas diretas colapsam na chave principal de sessão do agente.
  • Grupos/canais recebem suas próprias chaves de sessão.
  • O armazenamento de sessões e as transcrições ficam no host do Gateway.
Vários dispositivos/canais podem mapear para a mesma sessão, mas o histórico não é totalmente sincronizado de volta para todos os clientes. Recomendação: use um dispositivo principal para conversas longas para evitar contexto divergente. A UI de Controle e a TUI sempre exibem a transcrição da sessão mantida pelo gateway, portanto são a fonte de verdade. Detalhes: Gerenciamento de sessões.

​
Corpos de entrada e contexto de histórico

O OpenClaw separa o corpo do prompt do corpo do comando:
  • Body: texto do prompt enviado ao agente. Pode incluir envelopes do canal e wrappers opcionais de histórico.
  • CommandBody: texto bruto do usuário para análise de diretivas/comandos.
  • RawBody: alias legado para CommandBody (mantido por compatibilidade).
Quando um canal fornece histórico, ele usa um wrapper compartilhado:
  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
Para chats não diretos (grupos/canais/salas), o corpo da mensagem atual recebe um prefixo com o rótulo do remetente (mesmo estilo usado para entradas de histórico). Isso mantém consistentes as mensagens em tempo real e as enfileiradas/de histórico no prompt do agente. Os buffers de histórico são somente pendentes: incluem mensagens de grupo que não acionaram uma execução (por exemplo, mensagens com gatilho por menção) e excluem mensagens já presentes na transcrição da sessão. A remoção de diretivas se aplica apenas à seção da mensagem atual, para que o histórico permaneça intacto. Canais que encapsulam histórico devem definir CommandBody (ou RawBody) com o texto original da mensagem e manter Body como o prompt combinado. Os buffers de histórico são configuráveis via messages.groupChat.historyLimit (padrão global) e substituições por canal como channels.slack.historyLimit ou channels.telegram.accounts.<id>.historyLimit (defina 0 para desativar).

​
Enfileiramento e acompanhamentos

Se uma execução já estiver ativa, mensagens de entrada podem ser enfileiradas, direcionadas para a execução atual ou coletadas para um turno de acompanhamento.
  • Configure via messages.queue (e messages.queue.byChannel).
  • Modos: interrupt, steer, followup, collect, além de variantes com backlog.
Detalhes: Enfileiramento.

​
Streaming, fragmentação e agrupamento

O streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto. A fragmentação respeita os limites de texto do canal e evita dividir código delimitado. Principais configurações:
  • agents.defaults.blockStreamingDefault (on|off, desativado por padrão)
  • agents.defaults.blockStreamingBreak (text_end|message_end)
  • agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
  • agents.defaults.blockStreamingCoalesce (agrupamento baseado em inatividade)
  • agents.defaults.humanDelay (pausa semelhante à humana entre respostas em blocos)
  • Substituições por canal: *.blockStreaming e *.blockStreamingCoalesce (canais não Telegram exigem *.blockStreaming: true explícito)
Detalhes: Streaming + fragmentação.

​
Visibilidade do raciocínio e tokens

O OpenClaw pode expor ou ocultar o raciocínio do modelo:
  • /reasoning on|off|stream controla a visibilidade.
  • O conteúdo de raciocínio ainda conta para o uso de tokens quando produzido pelo modelo.
  • O Telegram oferece suporte ao streaming do raciocínio para o balão de rascunho.
Detalhes: Diretivas de pensamento + raciocínio e Uso de tokens.

​
Prefixos, encadeamento e respostas

A formatação de mensagens de saída é centralizada em messages:
  • messages.responsePrefix, channels.<channel>.responsePrefix e channels.<channel>.accounts.<id>.responsePrefix (cascata de prefixos de saída), além de channels.whatsapp.messagePrefix (prefixo de entrada do WhatsApp)
  • Encadeamento de respostas via replyToMode e padrões por canal
Detalhes: Configuração e documentação dos canais.