Gateway - Neotask by Neotask Documentation | Neotask

Gateway

O Que E o Gateway?

O Gateway e o coracao do Open Claw -- um unico servico de longa execucao que gerencia todas as sessoes de agente, canais de mensagens, execucao de ferramentas e conexoes de dispositivos. Tudo flui atraves do Gateway.

E um servidor WebSocket que escuta conexoes de clientes (app desktop, apps moveis, dashboard web) e gerencia todo o ciclo de vida do assistente de IA.

Arquitetura

Componentes

  • Servidor WebSocket -- Aceita conexoes de clientes (porta padrao 18789)
  • Servidor HTTP -- Serve a UI de Controle, host do canvas e endpoints de saude
  • Adaptadores de Canal -- Mantem conexoes com plataformas de mensagens (WhatsApp, Telegram, Discord, etc.)
  • Gerenciador de Sessoes -- Persiste e gerencia o estado de conversa dos agentes
  • Agendador Cron -- Executa jobs agendados e despertares por heartbeat
  • Runtime de Plugins -- Carrega e gerencia o ciclo de vida de plugins
  • Servico de Navegador -- Controla instancias Chromium para automacao web

    • Modos de Vinculacao

    | Modo | Descricao | |------|-----------| | Loopback | Padrao. Acessivel apenas do localhost (127.0.0.1) | | LAN | Acessivel na sua rede local. Descoberta automatica via Bonjour/mDNS | | Tailnet | Acessivel atraves de VPN Tailscale com MagicDNS | | Personalizado | Vincule a um endereco especifico |

    Autenticacao

    | Metodo | Descricao | |--------|-----------| | Token | Token bearer WebSocket (UUID ou string personalizada) | | Senha | Autenticacao baseada em senha (hash bcrypt) | | Proxy Confiavel | Para proxies reversos com headers pre-autenticados | | Confianca Local | Conexoes loopback auto-aprovadas |

    Configuracao

    O Gateway e configurado via openclaw.json (formato JSON5). Secoes principais:

    | Secao | Controla | |-------|----------| | agents | Lista de agentes, padroes, workspaces | | gateway | Porta, modo de vinculacao, autenticacao, comportamento de reload | | channels | Configuracao por canal e credenciais | | tools | Permissoes de ferramentas, perfis, seguranca | | plugins | Carregamento de plugins, habilitacao, configuracao por plugin | | models | Autenticacao de provedores, fallbacks, configuracoes de provedores | | skills | Diretorios de skills, configuracao por skill | | browser | Perfis de navegador, portas, modo headless | | cron | Configuracao do agendador | | session | Regras de reset, limiares de compactacao | | messages | Configuracoes TTS, politicas de midia | | memory | Configuracao de indexacao de memoria | | security | Sandboxing, modo elevado, aprovacoes |

    Hot Reload

    Mudancas de configuracao podem ser aplicadas sem reiniciar:

    | Modo | Comportamento | |------|---------------| | Hibrido (padrao) | Aplica mudancas seguras a quente, reinicia para outras | | Hot | Aplica apenas mudancas seguras a quente, ignora outras | | Reiniciar | Reinicia em qualquer mudanca que requer reload | | Desligado | Sem reload automatico |

    Acesso Remoto

    Tailscale (Recomendado)

    Tailscale fornece acesso remoto seguro, sem configuracao:

  • Vincule o Gateway ao seu Tailnet
  • Acesse de qualquer dispositivo na mesma rede Tailscale
  • DNS automatico via MagicDNS
  • Tailscale Serve pode expor o dashboard com HTTPS

    • Tunel SSH

    Encaminhe a porta do Gateway atraves de SSH:

  • Simples, seguro, sem mudancas de configuracao necessarias
  • Funciona com qualquer maquina capaz de SSH
  • Suporta o protocolo WebSocket completo e a UI de Controle

    • Regras de Seguranca

  • Loopback + SSH/Tailscale e a combinacao mais segura
  • Vinculacao nao-loopback requer configuracao de token de autenticacao
  • Fixacao de fingerprint TLS disponivel para seguranca adicional
  • Controle de navegador e desabilitado para conexoes remotas por padrao

    • Monitoramento de Saude

    Endpoint de Saude

    O endpoint HTTP /health retorna:

  • Status do Gateway
  • Liveness RPC
  • Saude por canal (conectado, status de autenticacao, contagem de contas)
  • Prontidao do navegador
  • Agentes ativos e nodes conectados
  • Uptime

    • Probes

  • Liveness RPC -- Conexao WebSocket + teste de eco
  • Saude do canal -- Verificacao de autenticacao + ping de API por canal
  • Prontidao do navegador -- Verificacao de porta, verificacao de processo
  • Conectividade do node -- Timestamp do ultimo heartbeat

    • Descoberta

    Bonjour/mDNS

    Quando vinculado a LAN, o Gateway se anuncia via DNS multicast:

  • Tipo de servico: _openclaw-gw._tcp
  • Inclui porta, transporte, status TLS e info DNS do Tailscale
  • Apps companion descobrem o Gateway automaticamente

    • Descoberta de Area Ampla

    Descubra gateways pela sua rede com timeouts configuraveis. Suporta tanto Bonjour local quanto descoberta DNS do Tailscale.

    Multiplos Gateways

    Voce pode executar multiplas instancias de Gateway na mesma maquina usando perfis:

  • Cada perfil tem configuracao, workspace, sessoes e estado separados
  • Portas diferentes para cada Gateway
  • Util para isolamento (pessoal vs trabalho) ou testes

    • Diagnosticos

    Doctor

    A ferramenta de diagnostico integrada verifica:

  • Validade da configuracao
  • Permissoes de arquivo
  • Conectividade de canais
  • Status de autenticacao de modelos
  • Compatibilidade de versao do Node.js
  • Configuracoes incorretas comuns

    • Pode corrigir automaticamente muitos problemas quando dada permissao.

    Logging

    Logs do Gateway sao escritos em arquivos JSONL diarios:

  • Rastreamento de uso de tokens por completion
  • Logs de eventos de canal
  • Log de erros com contexto estruturado
  • Niveis de log configuraveis

    • View full documentation