> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WebChat

Status: a UI de chat SwiftUI para macOS/iOS fala diretamente com o WebSocket do Gateway.

## O que é

* Uma UI de chat nativa para o Gateway (sem navegador incorporado e sem servidor estático local).
* Usa as mesmas sessões e regras de roteamento que outros canais.
* Roteamento determinístico: as respostas sempre voltam para o WebChat.

## Início rápido

1. Inicie o Gateway.
2. Abra a UI do WebChat (app macOS/iOS) ou a aba de chat da Control UI.
3. Garanta que um caminho de autenticação válido do Gateway esteja configurado (segredo compartilhado por padrão,
   mesmo em loopback).

## Como funciona (comportamento)

* A UI se conecta ao WebSocket do Gateway e usa `chat.history`, `chat.send` e `chat.inject`.
* `chat.history` é limitado para estabilidade: o Gateway pode truncar campos de texto longos, omitir metadados pesados e substituir entradas grandes demais por `[chat.history omitted: message too large]`.
* Quando uma mensagem visível do assistente foi truncada em `chat.history`, a Control UI pode abrir um leitor lateral e buscar a entrada completa normalizada para exibição sob demanda por meio de `chat.message.get`, sem aumentar o payload padrão do histórico.
* `chat.history` segue o ramo ativo da transcrição para arquivos de sessão append-only modernos, portanto ramos de reescrita abandonados e cópias de prompts substituídas não são renderizados no WebChat.
* Entradas de Compaction são renderizadas como um divisor explícito de histórico compactado. O divisor explica que a transcrição compactada é preservada como um ponto de verificação e aponta para os controles de ponto de verificação de Sessões, onde operadores podem criar ramificações ou restaurar a partir dessa visualização compactada quando suas permissões permitirem.
* A Control UI lembra o `sessionId` do Gateway subjacente retornado por `chat.history` e o inclui em chamadas `chat.send` subsequentes, portanto reconexões e atualizações de página continuam a mesma conversa armazenada, a menos que o usuário inicie ou redefina uma sessão.
* A Control UI agrupa envios duplicados em andamento para a mesma sessão, mensagem e anexos antes de gerar um novo id de execução de `chat.send`; o Gateway ainda desduplica solicitações repetidas que reutilizam a mesma chave de idempotência.
* Arquivos de inicialização do workspace e instruções pendentes de `BOOTSTRAP.md` são fornecidos por meio do Project Context do prompt do sistema do agente, não copiados para a mensagem de usuário do WebChat. A truncagem do bootstrap adiciona apenas um aviso conciso de recuperação no prompt do sistema; contagens detalhadas e ajustes de configuração permanecem nas superfícies de diagnóstico.
* `chat.history` também é normalizado para exibição: contexto do OpenClaw apenas de runtime,
  wrappers de envelope de entrada, tags de diretiva de entrega inline
  como `[[reply_to_*]]` e `[[audio_as_voice]]`, payloads XML de chamadas de ferramenta em texto simples
  (incluindo `<tool_call>...</tool_call>`,
  `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
  `<function_calls>...</function_calls>` e blocos truncados de chamadas de ferramenta), e
  tokens de controle de modelo ASCII/largura total vazados são removidos do texto visível,
  e entradas do assistente cujo texto visível inteiro é apenas o token silencioso exato
  `NO_REPLY` / `no_reply` são omitidas.
* Payloads de resposta marcados como raciocínio (`isReasoning: true`) são excluídos do conteúdo do assistente do WebChat, do texto de replay da transcrição e dos blocos de conteúdo de áudio, para que payloads apenas de pensamento não apareçam como mensagens visíveis do assistente nem como áudio reproduzível.
* `chat.inject` acrescenta uma nota do assistente diretamente à transcrição e a transmite para a UI (sem execução de agente).
* Execuções abortadas podem manter saída parcial do assistente visível na UI.
* O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando há saída em buffer, e marca essas entradas com metadados de aborto.
* O histórico é sempre buscado no Gateway (sem observação de arquivos locais).
* Se o Gateway estiver inacessível, o WebChat fica somente leitura.

### Modelo de transcrição e entrega

O WebChat tem dois caminhos de dados separados:

* O arquivo JSONL da sessão é a transcrição durável do modelo/runtime. Para execuções normais de agente, o runtime OpenClaw incorporado persiste mensagens `user`, `assistant` e `toolResult` visíveis ao modelo por meio de seu gerenciador de sessão. O WebChat não grava texto arbitrário de entrega, status ou auxiliar nessa transcrição.
* Eventos `ReplyPayload` do Gateway são a projeção de entrega ao vivo. Eles podem ser normalizados para exibição no WebChat/canal, streaming de blocos, tags de diretiva, incorporação de mídia, flags de TTS/áudio e comportamento de fallback da UI. Eles próprios não são o log canônico da sessão.
* Harnesses que exigem respostas visíveis por meio de `tools.message` ainda usam o WebChat como um destino interno de resposta da execução atual. Um `message.send` sem destino dessa execução ativa do WebChat é projetado no mesmo chat e espelhado para a transcrição da sessão; o WebChat não se torna um canal de saída reutilizável e nunca herda `lastChannel`.
* O WebChat injeta entradas de transcrição do assistente apenas quando o Gateway é dono de uma mensagem exibida fora de uma rodada normal de agente incorporado: `chat.inject`, respostas de comandos sem agente, saída parcial abortada e suplementos de transcrição de mídia gerenciados pelo WebChat.
* `chat.history` lê a transcrição de sessão armazenada e aplica a projeção de exibição do WebChat. Se texto ao vivo do assistente aparecer durante uma execução, mas desaparecer após recarregar o histórico, primeiro verifique se o JSONL bruto contém o texto do assistente, depois se a projeção de `chat.history` o removeu, e então se a mesclagem otimista de cauda da Control UI substituiu o estado de entrega local pelo snapshot persistido.
* `chat.message.get` usa o mesmo ramo de transcrição e as mesmas regras de projeção de exibição que `chat.history`, incluindo escopo de agente ativo, mas mira uma entrada de transcrição por `messageId` e retorna um motivo honesto de indisponibilidade quando o conteúdo completo não pode mais ser retornado.

Respostas finais de execuções normais de agente devem ser duráveis porque o runtime incorporado grava o `message_end` do assistente. Qualquer fallback que espelhe um payload final entregue para a transcrição deve primeiro evitar duplicar uma rodada do assistente que o runtime incorporado já gravou.

## Painel de ferramentas dos agentes da Control UI

* O painel Ferramentas de `/agents` da Control UI tem duas visualizações separadas:
  * **Disponível agora** usa `tools.effective(sessionKey=...)` e mostra uma projeção
    somente leitura derivada do servidor do inventário da sessão atual, incluindo ferramentas principais, de Plugin, pertencentes a canais
    e de servidores MCP já descobertos.
  * **Configuração de ferramentas** usa `tools.catalog` e permanece focada em perfis, substituições e
    semântica do catálogo.
* A disponibilidade em runtime é escopada por sessão. Trocar sessões no mesmo agente pode alterar a lista
  **Disponível agora**. Se servidores MCP configurados não tiverem sido conectados ou tiverem sido alterados
  desde a última descoberta, o painel mostra um aviso em vez de iniciar silenciosamente transportes MCP
  a partir do caminho de leitura.
* O editor de configuração não implica disponibilidade em runtime; o acesso efetivo ainda segue a precedência de políticas
  (`allow`/`deny`, substituições por agente e por provedor/canal).

## Uso remoto

* O modo remoto tunela o WebSocket do Gateway por SSH/Tailscale.
* Você não precisa executar um servidor WebChat separado.

## Referência de configuração (WebChat)

Configuração completa: [Configuração](/pt-BR/gateway/configuration)

O WebChat não tem seção de configuração persistida. O Gateway usa o limite de exibição incorporado de `chat.history`; clientes de API podem enviar `maxChars` por solicitação para sobrescrevê-lo em uma única chamada `chat.history`. A configuração legada `channels.webchat` e `gateway.webchat` foi aposentada; execute `openclaw doctor --fix` para removê-la.

Opções globais relacionadas:

* `gateway.port`, `gateway.bind`: host/porta do WebSocket.
* `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`:
  autenticação WebSocket por segredo compartilhado.
* `gateway.auth.allowTailscale`: a aba de chat da Control UI no navegador pode usar cabeçalhos de identidade do Tailscale
  Serve quando habilitada.
* `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso para clientes de navegador atrás de uma origem de proxy **não loopback** com reconhecimento de identidade (veja [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth)).
* `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: destino remoto do Gateway.
* `session.*`: armazenamento de sessão e padrões da chave principal.

## Relacionado

* [Control UI](/pt-BR/web/control-ui)
* [Dashboard](/pt-BR/web/dashboard)