Mensagens

As mensagens recebidas passam por roteamento, eliminação de duplicatas/debounce, uma execução do agente e entrega de saída:

Mensagem recebida  -> roteamento/vínculos -> chave da sessão  -> eliminação de duplicatas + debounce  -> fila (se uma execução já estiver ativa)  -> execução do agente (streaming + ferramentas)  -> respostas de saída (limites do canal + divisão em partes)

Principais superfícies de configuração:

• messages.* para prefixos, enfileiramento, debounce de entrada e comportamento de grupos.
• agents.defaults.* para streaming em blocos, divisão em partes e padrões de resposta silenciosa.
• Substituições específicas de canal (channels.telegram.*, channels.whatsapp.* etc.) para limites e opções de streaming por canal.

Consulte Configuração para ver o esquema completo.

Eliminação de duplicatas de entrada

Os canais podem entregar novamente a mesma mensagem após uma reconexão. O OpenClaw mantém um cache em memória indexado pelo escopo do agente, pela rota do canal (canal + par + conta + conversa) e pelo ID da mensagem, para que uma mensagem entregue novamente não acione uma segunda execução do agente. A entrada do cache expira após 20 minutos ou assim que 5000 entradas forem registradas, o que ocorrer primeiro.

Debounce de entrada

Mensagens de texto consecutivas enviadas rapidamente pelo mesmo remetente podem ser agrupadas em um único turno do agente por meio de messages.inbound. O debounce é delimitado por canal + conversa e usa a mensagem mais recente para o encadeamento/IDs da resposta.

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

• O debounce se aplica apenas a mensagens de texto; mídias/anexos são processados imediatamente.
• Comandos de controle (parar/abortar/status etc.) ignoram o debounce para serem despachados imediatamente.
• Desativado por padrão: messages.inbound.debounceMs não tem um valor padrão integrado, portanto o debounce só é ativado depois que você o configura (globalmente ou por canal).
• A opção coalesceSameSenderDms do iMessage é a única exceção: ela retém todos os textos de mensagens diretas do mesmo remetente (incluindo comandos) por tempo suficiente para que o envio separado de comando+URL da Apple chegue como um único turno. Conversas em grupo são sempre despachadas imediatamente, independentemente dessa configuração.

Sessões e dispositivos

As sessões pertencem ao Gateway, não aos clientes.

• Os chats diretos são agrupados na chave da sessão principal 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 ser mapeados para a mesma sessão, mas o histórico não é sincronizado integralmente de volta para todos os clientes. Use um dispositivo principal para conversas longas a fim de evitar contextos divergentes. A interface de controle e a TUI sempre mostram a transcrição da sessão armazenada no Gateway, portanto são a fonte oficial.

Detalhes: Gerenciamento de sessões.

Corpos de prompt e contexto do histórico

Os plugins de canal preenchem vários campos de texto no contexto de entrada, do mais ao menos preferido:

Quando um canal fornece o histórico, ele o envolve com:

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

Para conversas não diretas (grupos/canais/salas), o corpo da mensagem atual recebe como prefixo o rótulo do remetente, seguindo o estilo usado nas entradas do histórico. A remoção de diretivas aplica-se apenas à seção da mensagem atual, portanto o histórico permanece intacto. Os canais que encapsulam o histórico devem definir BodyForCommands (ou os campos legados CommandBody / RawBody) como o texto original da mensagem e manter Body como o prompt combinado.

Os buffers de histórico contêm apenas itens pendentes: eles incluem mensagens de grupo que não acionaram uma execução (por exemplo, mensagens sujeitas à exigência de menção) e excluem mensagens que já estão na transcrição da sessão. Metadados estruturados de histórico, resposta, encaminhamento e canal são renderizados como blocos de contexto não confiável com a função de usuário durante a montagem do prompt.

Configure o tamanho do histórico com messages.groupChat.historyLimit (padrão global) ou com substituições específicas por canal, como channels.slack.historyLimit e channels.telegram.accounts.<id>.historyLimit (defina como 0 para desativar).

Metadados de resultado da ferramenta

O content do resultado da ferramenta é o resultado visível para o modelo; details são metadados de runtime usados para renderização da interface, diagnóstico, entrega de mídia e plugins.

• toolResult.details é removido antes da reprodução pelo provedor e antes da entrada de compaction.
• As transcrições de sessão persistidas mantêm apenas details dentro dos limites; metadados grandes demais são substituídos por um resumo compacto marcado com persistedDetailsTruncated: true.
• Plugins e ferramentas devem colocar o texto que o modelo precisa ler em content, não apenas em details.

Enfileiramento e acompanhamentos

Quando uma execução já está ativa, as mensagens recebidas são direcionadas a ela por padrão. messages.queue controla o modo:

Padrões: messages.queue.debounceMs é 500ms (aplica-se igualmente ao agrupamento de steer, followup e collect), messages.queue.cap é de 20 mensagens enfileiradas e messages.queue.drop é summarize (old e new também estão disponíveis). Configure substituições por canal usando messages.queue.byChannel e messages.queue.debounceMsByChannel.

Detalhes: Fila de comandos e Fila de direcionamento.

Propriedade da execução do canal

Os plugins de canal podem preservar a ordem, aplicar debounce à entrada e controlar a contrapressão do transporte antes que uma mensagem entre na fila da sessão. Eles não devem impor um tempo limite separado ao próprio turno do agente. Depois que uma mensagem é encaminhada para uma sessão, os ciclos de vida da sessão, das ferramentas e do runtime regem trabalhos de longa duração, para que todos os canais relatem e se recuperem de turnos lentos de maneira consistente.

Streaming, divisão em blocos e agrupamento

O streaming em blocos envia respostas parciais à medida que o modelo produz blocos de texto; a divisão respeita os limites de texto do canal e evita dividir código cercado por delimitadores.

• agents.defaults.blockStreamingDefault (on|off, padrão off)
• 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: *.streaming.block.enabled e *.streaming.block.coalesce em canais com configuração de streaming aninhada (Telegram, Discord, Slack, iMessage, Microsoft Teams); *.blockStreaming / *.blockStreamingCoalesce no nível superior em canais sem uma configuração de streaming aninhada. O streaming em blocos fica desativado, a menos que seja explicitamente habilitado, em todos os canais, incluindo o Telegram.

Detalhes: Streaming + divisão em blocos.

Visibilidade do raciocínio e tokens

• /reasoning on|off|stream controla a visibilidade.
• O conteúdo do raciocínio ainda conta para o uso de tokens quando o modelo o produz.
• O Telegram permite transmitir o raciocínio por streaming para um balão de rascunho temporário, que é excluído após a entrega final; use /reasoning on para uma saída de raciocínio persistente.

Detalhes: Diretivas de pensamento + raciocínio e Uso de tokens.

Prefixos, encadeamento e respostas

• Cascata de prefixos de saída: messages.responsePrefix, channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix. O WhatsApp também tem channels.whatsapp.messagePrefix para um prefixo de entrada.
• Encadeamento de respostas por meio de replyToMode e padrões por canal.

Detalhes: Configuração e documentação dos canais.

Respostas silenciosas

O token silencioso NO_REPLY (sem distinção entre maiúsculas e minúsculas, portanto no_reply também corresponde) significa "não entregar uma resposta visível ao usuário". Quando um turno também tem mídia de ferramenta pendente, como áudio TTS gerado, o OpenClaw remove o texto silencioso, mas ainda entrega o anexo de mídia.

A política de silêncio é definida pelo tipo de conversa:

• Conversas diretas nunca recebem orientação de prompt sobre NO_REPLY. Se uma execução direta retornar acidentalmente apenas um token silencioso, o OpenClaw o suprime em vez de reescrevê-lo ou entregá-lo.
• Grupos/canais permitem silêncio por padrão. No modo de resposta visível message_tool, silêncio significa que o modelo não chama message(action=send).
• A orquestração interna permite silêncio por padrão.

Os padrões ficam em agents.defaults.silentReply; surfaces.<id>.silentReply pode substituir a política de grupo/interna por superfície.

O OpenClaw também usa respostas silenciosas para falhas genéricas do executor interno em conversas não diretas, para que grupos/canais não vejam textos padronizados de erro do gateway. Falhas classificadas com texto de recuperação voltado ao usuário, como avisos de autenticação ausente, limite de taxa ou sobrecarga, ainda podem ser entregues. Conversas diretas exibem um texto compacto de falha por padrão; detalhes brutos do executor são exibidos apenas quando /verbose full está habilitado.

Respostas contendo apenas o token silencioso são descartadas em todas as superfícies, para que as sessões principais permaneçam silenciosas em vez de reescrever o texto sentinela como conversa de fallback.

Relacionados

• Refatoração do ciclo de vida das mensagens - projeto-alvo durável de envio e recebimento
• Streaming - entrega de mensagens em tempo real
• Nova tentativa - comportamento de nova tentativa de entrega de mensagens
• Fila - fila de processamento de mensagens
• Canais - integrações com plataformas de mensagens