English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Messages and delivery

Mensagens

OpenClaw lida com mensagens de entrada por meio de um pipeline de resolução de sessão, enfileiramento, streaming, execução de ferramentas e visibilidade de raciocínio. Esta página mapeia o caminho da mensagem de entrada até a resposta.

Fluxo de mensagens (alto nível)

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)

Os principais controles ficam na configuração:

  • messages.* para prefixos, enfileiramento e comportamento de grupos.
  • agents.defaults.* para padrões de streaming em blocos e divisão em chunks.
  • Sobrescritas de canais (channels.whatsapp.*, channels.telegram.*, etc.) para limites e alternâncias de streaming.

Consulte Configuração para o esquema completo.

Deduplicação de entrada

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

Debounce de entrada

Mensagens consecutivas rápidas do mesmo remetente podem ser agrupadas em um único turno do agente via messages.inbound. O debounce é escopado por canal + conversa e usa a mensagem mais recente para encadeamento/IDs de resposta.

Configuração (padrão global + sobrescritas por canal):

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

Observações:

  • O debounce se aplica a mensagens somente de texto; mídias/anexos são liberados imediatamente.
  • Comandos de controle ignoram o debounce para permanecerem independentes — exceto quando um canal opta explicitamente por coalescência de DMs do mesmo remetente (por exemplo, BlueBubbles coalesceSameSenderDms), em que comandos de DM aguardam dentro da janela de debounce para que uma carga enviada em partes possa entrar no mesmo turno do agente.

Sessões e dispositivos

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

  • Conversas diretas são condensadas na chave de 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 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 mostram a transcrição da sessão respaldada pelo Gateway, portanto elas são a fonte da verdade.

Detalhes: Gerenciamento de sessões.

Metadados de resultado de ferramenta

O content do resultado da ferramenta é o resultado visível para o modelo. O details do resultado da ferramenta é metadado de runtime para renderização de UI, diagnósticos, entrega de mídia e Plugins.

O OpenClaw mantém esse limite explícito:

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

Corpos de entrada e contexto de histórico

O OpenClaw separa o corpo do prompt do corpo do comando:

  • BodyForAgent: texto primário voltado ao modelo para a mensagem atual. Plugins de canal devem mantê-lo focado no texto atual do remetente que contém o prompt.
  • Body: fallback legado de prompt. Ele pode incluir envelopes de canal e wrappers opcionais de histórico, mas os canais atuais não devem depender dele como a entrada primária do modelo quando BodyForAgent estiver disponível.
  • 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 conversas não diretas (grupos/canais/salas), o corpo da mensagem atual recebe como prefixo o rótulo do remetente (o mesmo estilo usado para entradas de histórico). Isso mantém mensagens em tempo real e enfileiradas/de histórico consistentes no prompt do agente.

Buffers de histórico são apenas pendentes: eles incluem mensagens de grupo que não acionaram uma execução (por exemplo, mensagens filtradas por menção) e excluem mensagens já presentes na transcrição da sessão.

A remoção de diretivas se aplica somente à seção da mensagem atual, para que o histórico permaneça intacto. Canais que encapsulam histórico devem definir CommandBody (ou RawBody) como o texto original da mensagem e manter Body como o prompt combinado. Histórico estruturado, resposta, encaminhamento e metadados de canal são renderizados como blocos de contexto não confiáveis com papel de usuário durante a montagem do prompt. Buffers de histórico são configuráveis via messages.groupChat.historyLimit (padrão global) e sobrescritas 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).
  • O modo padrão é steer, com um debounce de acompanhamento de 500 ms quando o direcionamento recai para entrega de acompanhamento enfileirada.
  • Modos: steer, followup, collect, steer-backlog, interrupt e o modo legado queue de uma por vez.

Detalhes: Fila de comandos e Fila de direcionamento.

Propriedade de execução do canal

Plugins de canal podem preservar ordenação, aplicar debounce à entrada e aplicar contrapressão de transporte antes que uma mensagem entre na fila da sessão. Eles não devem impor um timeout separado em torno do turno do agente em si. Depois que uma mensagem é roteada para uma sessão, trabalhos de longa duração são regidos pela sessão, ferramenta e ciclo de vida de runtime para que todos os canais relatem e se recuperem de turnos lentos de forma consistente.

Streaming, divisão em chunks e agrupamento

O streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto. A divisão em chunks respeita os limites de texto do canal e evita dividir código cercado por cercas.

Configurações principais:

  • 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 ociosidade)
  • agents.defaults.humanDelay (pausa semelhante à humana entre respostas em bloco)
  • Sobrescritas de canais: *.blockStreaming e *.blockStreamingCoalesce (canais que não são Telegram exigem *.blockStreaming: true explícito)

Detalhes: Streaming + divisão em chunks.

Visibilidade de 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 a stream de raciocínio em uma bolha de rascunho transitória que é excluída após a entrega final; use /reasoning on para saída persistente de raciocínio.

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 prefixo 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.

Respostas silenciosas

O token silencioso exato NO_REPLY / no_reply 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. O OpenClaw resolve esse comportamento por tipo de conversa:

  • Conversas diretas proíbem silêncio por padrão e reescrevem uma resposta silenciosa isolada para um fallback curto e visível.
  • Grupos/canais permitem silêncio por padrão.
  • Orquestração interna permite silêncio por padrão.

O OpenClaw também usa respostas silenciosas para falhas internas do executor que acontecem antes de qualquer resposta do assistente em conversas não diretas, para que grupos/canais não vejam texto padrão de erro do Gateway. Conversas diretas mostram texto compacto de falha por padrão; detalhes brutos do executor são mostrados apenas quando /verbose está on ou full.

Os padrões ficam em agents.defaults.silentReply e agents.defaults.silentReplyRewrite; surfaces.<id>.silentReply e surfaces.<id>.silentReplyRewrite podem sobrescrevê-los por superfície.

Quando a sessão pai tem uma ou mais execuções pendentes de subagentes gerados, respostas silenciosas isoladas são descartadas em todas as superfícies em vez de serem reescritas, para que o pai permaneça quieto até que o evento de conclusão do filho entregue a resposta real.

Relacionados