Canal WebChat do OpenClaw

O WebChat se comunica com o OpenClaw Gateway através de uma conexão WebSocket utilizando três operações principais: • chat.history — Recupera o histórico da conversa do Gateway • chat.send — Transmite mensagens do usuário para o assistente de IA • chat.inject — Adiciona notas do assistente diretamente às transcrições e transmite para a interface sem acionar uma execução do agente Diferente de outros canais que dependem de serviços externos e webhooks, o WebChat é totalmente nativo do Gateway. As mensagens nunca saem da sua infraestrutura — a conexão WebSocket é direta entre o cliente da interface e o processo do Gateway. O roteamento é determinístico: as respostas da IA sempre retornam à sessão WebChat que iniciou a conversa.

A autenticação é obrigatória para todas as conexões WebChat, mesmo em loopback (localhost). Isso impede o acesso não autorizado ao seu assistente de IA. O OpenClaw suporta dois modos de autenticação: • token — Um token secreto compartilhado passado no handshake do WebSocket. Ideal para acesso programático e configurações de usuário único. • password — Autenticação baseada em senha. Adequado para ambientes multiusuário onde cada usuário tem suas próprias credenciais. Pelo menos um dos modos, token ou password, deve ser configurado para que o WebChat aceite conexões. Configure esses parâmetros nas definições de gateway.auth do seu openclaw.json.

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "a-strong-random-token-here"
    }
  }
}

O WebChat suporta conectividade remota sem executar um servidor web separado. Duas abordagens são recomendadas: • Túnel SSH — Encaminhe a porta do Gateway via SSH: ssh -L 3000:localhost:3000 user@remote-host. Isso permite acessar o WebChat localmente enquanto o Gateway está em execução em uma máquina remota. • Tailscale — Conecte seus dispositivos através da VPN mesh do Tailscale. O Gateway fica acessível pelo endereço IP do Tailscale sem necessidade de encaminhamento de porta ou configuração de firewall. Para conexões remotas, configure as definições de gateway.remote com a URL do WebSocket de destino e as credenciais de autenticação. O cliente nativo gerencia a reconexão automaticamente quando as condições da rede mudam.

{
  "gateway": {
    "remote": {
      "url": "wss://your-remote-host:3000",
      "token": "YOUR_REMOTE_TOKEN"
    }
  }
}

O WebChat utiliza sessões gerenciadas pelo Gateway para manter o contexto da conversa. Cada conexão WebChat é associada a uma sessão que armazena o histórico da conversa e o contexto da IA. As sessões são persistentes entre reconexões — se o WebSocket cair e reconectar, a conversa continua de onde parou. A operação chat.history recupera a conversa completa do Gateway ao reconectar. A configuração de sessão é gerenciada através das definições session.* no openclaw.json, incluindo o backend de armazenamento e as chaves de sessão padrão.

Quando o Gateway fica inacessível, o WebChat entra automaticamente no modo somente leitura. Nesse estado: • O histórico anterior da conversa permanece visível • Novas mensagens não podem ser enviadas • A interface indica o status desconectado • Tentativas automáticas de reconexão ocorrem em segundo plano Assim que o Gateway voltar a ficar online, o WebChat reconecta automaticamente e restaura a funcionalidade completa. Nenhuma mensagem é perdida do histórico da conversa, pois todo o histórico é obtido do Gateway.

O WebChat é implementado como uma aplicação nativa SwiftUI nas plataformas Apple: • macOS — Experiência desktop completa com atalhos de teclado, notificações do sistema e integração com a barra de menus • iOS — Interface otimizada para dispositivos móveis com notificações push e atualização em segundo plano A implementação nativa proporciona uma experiência responsiva e específica da plataforma, sem a sobrecarga de um navegador embutido ou wrapper Electron. A renderização de texto, rolagem e manipulação de entrada utilizam componentes nativos da plataforma. Para outras plataformas (Windows, Linux, Android), acesse o WebChat pela aba de chat do Control UI em qualquer navegador web moderno.

O WebChat gerencia a entrega de mensagens através da conexão WebSocket com fragmentação configurável para respostas longas da IA: • textChunkLimit — Máximo de caracteres por fragmento de mensagem (padrão: 2000). Respostas longas são divididas automaticamente. • blockStreaming — Quando ativado, as respostas são enviadas em fragmentos baseados em blocos conforme são geradas, proporcionando feedback em tempo real. As mensagens são entregues instantaneamente através do WebSocket — sem polling ou atraso de webhook. A conexão WebSocket bidirecional permite que tanto o envio quanto o recebimento aconteçam em tempo real.

{
  "channels": {
    "webchat": {
      "textChunkLimit": 2000,
      "blockStreaming": true
    }
  }
}

A segurança do WebChat é construída em torno da camada de autenticação do Gateway. Siga estas melhores práticas para implantações seguras: • Sempre configure a autenticação — Acesso anônimo não é permitido • Use criptografia TLS — Conecte via wss:// (WebSocket Secure) para todas as conexões remotas • Restrinja o endereço de bind — Use gateway.bind: "127.0.0.1" para acesso apenas local; evite vincular a 0.0.0.0 a menos que esteja atrás de um proxy reverso • Use credenciais fortes — Gere tokens aleatórios ou senhas fortes • Proxy reverso — Para implantações em produção, coloque o Gateway atrás de um proxy reverso (nginx, Caddy) com terminação TLS Se estiver usando um proxy reverso na mesma máquina, configure gateway.trustedProxies para garantir a detecção correta do IP do cliente.