Clawdbot Gateway

Visão Geral do Clawdbot Gateway

O Clawdbot Gateway é o processo sempre ativo que possui as conexões de mensagens (WhatsApp via Baileys, Telegram via grammY, Discord, Slack e mais) e o plano de controle/eventos. É o serviço central que mantém seu assistente de IA Clawdbot funcionando 24/7.

O que é o Gateway?

O Gateway é um daemon de longa duração que:

• Mantém todas as conexões de provedores de mensagens
• Expõe uma API WebSocket tipada para requisições, respostas e eventos push do servidor
• Valida frames de entrada contra JSON Schema
• Emite eventos como agent, chat, presence, health, heartbeat, cron

Princípio chave: Um Gateway por host; é o único lugar que abre sessões de mensagens (como WhatsApp).

Início Rápido

Iniciar o Gateway

clawdbot gateway --port 18789

Para logs completos de debug/trace:

clawdbot gateway --port 18789 --verbose

Se a porta estiver ocupada, termine os listeners e então inicie:

clawdbot gateway --force

Modo de Desenvolvimento

Para desenvolvimento com auto-reload em mudanças TypeScript:

pnpm gateway:watch

Arquitetura do Gateway

Componentes

Fluxo de Conexão

Client                    Gateway
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|
  |<------ event:agent ------|

Configuração do Gateway

Configuração Básica

Localização do arquivo de configuração: ~/.clawdbot/clawdbot.json

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

Configuração de Porta

Precedência da porta:

1. Flag CLI --port
2. Variável de ambiente CLAWDBOT_GATEWAY_PORT
3. gateway.port na configuração
4. Padrão: 18789

Autenticação

A autenticação do Gateway é obrigatória por padrão. Configure via:

• gateway.auth.token na configuração
• Variável de ambiente CLAWDBOT_GATEWAY_TOKEN
• gateway.auth.password para autenticação baseada em senha

Clientes devem enviar connect.params.auth.token ou connect.params.auth.password.

Hot Reload

Hot reload de configuração monitora ~/.clawdbot/clawdbot.json:

Serviços do Gateway

Endpoints HTTP

O Gateway serve múltiplos endpoints HTTP na mesma porta:

Canvas Host

Inicia por padrão na porta 18793, servindo:

http://<gateway-host>:18793/__clawdbot__/canvas/

De ~/.clawdbot/workspace/canvas. Desabilitar com:

• canvasHost.enabled: false
• CLAWDBOT_SKIP_CANVAS_HOST=1

Dashboard

Acesse a UI de Controle em:

http://127.0.0.1:18789/

Ou execute:

clawdbot dashboard

Acesso Remoto

Túnel SSH (Recomendado)

ssh -N -L 18789:127.0.0.1:18789 user@host

Clientes então conectam a ws://127.0.0.1:18789 através do túnel.

Tailscale/VPN

Preferido para acesso remoto em produção. O mesmo handshake + token de autenticação se aplica.

Gerenciamento do Gateway

Comandos de Serviço

# Verificar status
clawdbot gateway status

# Verificação de saúde
clawdbot health

# Auditoria de segurança
clawdbot security audit --deep

# Parar gateway
clawdbot gateway stop

Supervisão

macOS: Usa LaunchAgent (bot.molt.<profile>)

Linux: Usa serviço de usuário systemd (clawdbot-gateway-<profile>.service)

Windows: Usa Windows Service (Clawdbot Gateway (<profile>))

Múltiplos Gateways

Geralmente desnecessário—um Gateway pode servir múltiplos canais e agentes. Use múltiplos Gateways apenas para:

• Redundância
• Isolamento estrito (ex., bot de resgate)

Requisitos:

• Isolar estado + configuração
• Usar portas únicas

Protocolo Wire

Transporte

• WebSocket com frames de texto contendo payloads JSON
• Primeiro frame deve ser connect

Tipos de Mensagem

Requisições:

{"type": "req", "id": "...", "method": "...", "params": {...}}

Respostas:

{"type": "res", "id": "...", "ok": true, "payload": {...}}

Eventos:

{"type": "event", "event": "...", "payload": {...}, "seq": 1}

Idempotência

Chaves de idempotência são necessárias para métodos com efeitos colaterais (send, agent) para retry seguro.

Solução de Problemas

Gateway Não Inicia

1. Verifique se a porta está em uso: lsof -i :18789
2. Revise logs: cat /tmp/clawdbot/gateway.log
3. Use --force para terminar listeners existentes

Problemas de Conexão

1. Verifique se o token de autenticação corresponde
2. Verifique conectividade de rede
3. Revise logs de handshake WebSocket com --verbose

Problemas de Canal

1. Verifique status do canal: clawdbot channels status
2. Re-autentique canais: clawdbot channels login
3. Revise logs específicos do canal

Melhores Práticas

1. Use Tokens de Auth: Sempre configure gateway.auth.token para segurança
2. Monitore Saúde: Verifique regularmente clawdbot health
3. Use Supervisão: Deixe launchd/systemd gerenciar reinícios
4. Faça Backup da Configuração: Mantenha backups de ~/.clawdbot/clawdbot.json
5. Revise Logs: Verifique logs regularmente para problemas

Próximos Passos

• Guia de Configuração do Clawdbot - Guia completo de instalação
• Integração WhatsApp do Clawdbot - Conectar ao WhatsApp
• Integração Telegram do Clawdbot - Conectar ao Telegram