Aplicativo Android

Snapshot de suporte

• Função: app de nó complementar (Android não hospeda o Gateway).
• Gateway obrigatório: sim (execute-o no macOS, Linux ou Windows via WSL2).
• Instalação: Google Play para o app, Introdução para o Gateway e depois Pareamento.
• Gateway: Runbook + Configuração.
  • Protocolos: Protocolo do Gateway (nós + plano de controle).

Controle do sistema

O controle do sistema (launchd/systemd) fica no host do Gateway. Consulte Gateway.

Runbook de conexão

App de nó Android ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway

O Android se conecta diretamente ao WebSocket do Gateway e usa pareamento de dispositivo (role: node).

Para Tailscale ou hosts públicos, o Android requer um endpoint seguro:

• Preferencial: Tailscale Serve / Funnel com https://<magicdns> / wss://<magicdns>
• Também compatível: qualquer outra URL de Gateway wss:// com um endpoint TLS real
• ws:// em texto claro continua compatível em endereços de LAN privada / hosts .local, além de localhost, 127.0.0.1 e a ponte do emulador Android (10.0.2.2)

Pré-requisitos

• Você consegue executar o Gateway na máquina "mestre".
• O dispositivo/emulador Android consegue acessar o WebSocket do gateway:
  • Mesma LAN com mDNS/NSD, ou
  • Mesma tailnet Tailscale usando Wide-Area Bonjour / DNS-SD unicast (veja abaixo), ou
  • Host/porta do gateway manual (fallback)
• O pareamento móvel por tailnet/público não usa endpoints IP de tailnet brutos ws://. Use Tailscale Serve ou outra URL wss://.
• Você consegue executar a CLI (openclaw) na máquina do gateway (ou via SSH).

1) Inicie o Gateway

openclaw gateway --port 18789 --verbose

Confirme nos logs que você vê algo como:

• listening on ws://0.0.0.0:18789

Para acesso Android remoto via Tailscale, prefira Serve/Funnel em vez de vincular diretamente à tailnet:

openclaw gateway --tailscale serve

Isso dá ao Android um endpoint seguro wss:// / https://. Uma configuração simples gateway.bind: "tailnet" não é suficiente para o primeiro pareamento Android remoto, a menos que você também finalize TLS separadamente.

2) Verifique a descoberta (opcional)

Na máquina do gateway:

dns-sd -B _openclaw-gw._tcp local.

Mais notas de depuração: Bonjour.

Se você também configurou um domínio de descoberta de área ampla, compare com:

openclaw gateway discover --json

Isso mostra local. mais o domínio de área ampla configurado em uma só passagem e usa o endpoint de serviço resolvido em vez de dicas somente TXT.

Descoberta de tailnet (Viena ⇄ Londres) via DNS-SD unicast

A descoberta NSD/mDNS do Android não atravessa redes. Se o nó Android e o gateway estiverem em redes diferentes, mas conectados via Tailscale, use Wide-Area Bonjour / DNS-SD unicast.

A descoberta sozinha não é suficiente para pareamento Android por tailnet/público. A rota descoberta ainda precisa de um endpoint seguro (wss:// ou Tailscale Serve):

1. Configure uma zona DNS-SD (exemplo openclaw.internal.) no host do gateway e publique registros _openclaw-gw._tcp.
2. Configure o DNS dividido do Tailscale para o domínio escolhido apontando para esse servidor DNS.

Detalhes e exemplo de configuração do CoreDNS: Bonjour.

3) Conecte pelo Android

No app Android:

• O app mantém sua conexão com o gateway ativa por meio de um serviço em primeiro plano (notificação persistente).
• Abra a aba Conectar.
• Use o modo Código de configuração ou Manual.
• Se a descoberta estiver bloqueada, use host/porta manual em Controles avançados. Para hosts de LAN privada, ws:// ainda funciona. Para hosts Tailscale/públicos, ative TLS e use um endpoint wss:// / Tailscale Serve.

Após o primeiro pareamento bem-sucedido, o Android se reconecta automaticamente ao iniciar:

• Endpoint manual (se habilitado), caso contrário
• O último gateway descoberto (melhor esforço).

Beacons de presença ativa

Depois que a sessão de nó autenticada se conecta, e quando o app vai para o segundo plano enquanto o serviço em primeiro plano ainda está conectado, o Android chama node.event com event: "node.presence.alive". O gateway registra isso como lastSeenAtMs/lastSeenReason nos metadados do nó/dispositivo pareado somente depois que a identidade autenticada do dispositivo de nó é conhecida.

O app conta o beacon como registrado com sucesso somente quando a resposta do gateway inclui handled: true. Gateways mais antigos podem confirmar node.event com { "ok": true }; essa resposta é compatível, mas não conta como uma atualização durável de último visto.

4) Aprove o pareamento (CLI)

Na máquina do gateway:

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

Detalhes de pareamento: Pareamento.

Opcional: se o nó Android sempre se conecta a partir de uma sub-rede rigidamente controlada, você pode optar pela aprovação automática de nó no primeiro pareamento com CIDRs explícitos ou IPs exatos:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Isso fica desabilitado por padrão. Aplica-se apenas a pareamentos novos com role: node sem escopos solicitados. Pareamento de operador/navegador e qualquer alteração de função, escopo, metadados ou chave pública ainda exigem aprovação manual.

5) Verifique se o nó está conectado

• Via status dos nós:

  openclaw nodes status

• Via Gateway:

  openclaw gateway call node.list --params "{}"

6) Chat + histórico

A aba Chat do Android oferece suporte à seleção de sessão (padrão main, além de outras sessões existentes):

• Histórico: chat.history (normalizado para exibição; tags de diretivas inline são removidas do texto visível, 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 de chamada de ferramenta truncados) e tokens de controle de modelo ASCII/largura completa vazados são removidos, linhas de assistente compostas apenas por token silencioso, como NO_REPLY / no_reply exatos, são omitidas, e linhas grandes demais podem ser substituídas por placeholders)
• Envio: chat.send
• Atualizações push (melhor esforço): chat.subscribe → event:"chat"

7) Canvas + câmera

Host Canvas do Gateway (recomendado para conteúdo web)

Se você quiser que o nó mostre HTML/CSS/JS real que o agente possa editar em disco, aponte o nó para o host Canvas do Gateway.

1. Crie ~/.openclaw/workspace/canvas/index.html no host do gateway.

2. Navegue o nó até ele (LAN):

openclaw nodes invoke --node "&lt;Android Node&gt;" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'

Tailnet (opcional): se ambos os dispositivos estiverem no Tailscale, use um nome MagicDNS ou IP da tailnet em vez de .local, por exemplo, http://<gateway-magicdns>:18789/__openclaw__/canvas/.

Esse servidor injeta um cliente de recarregamento ao vivo no HTML e recarrega quando arquivos mudam. O Gateway também serve /__openclaw__/a2ui/, mas o app Android trata páginas A2UI remotas como somente renderização. Comandos A2UI com ações usam a página A2UI empacotada e pertencente ao app antes de aplicar mensagens.

Comandos Canvas (somente em primeiro plano):

• canvas.eval, canvas.snapshot, canvas.navigate (use {"url":""} ou {"url":"/"} para retornar ao scaffold padrão). canvas.snapshot retorna { format, base64 } (padrão format="jpeg").
• A2UI: canvas.a2ui.push, canvas.a2ui.reset (alias legado canvas.a2ui.pushJSONL). Esses comandos usam a página A2UI empacotada e pertencente ao app para renderização com ações.

Comandos de câmera (somente em primeiro plano; protegidos por permissão):

• camera.snap (jpg)
• camera.clip (mp4)

Consulte Nó de câmera para parâmetros e auxiliares de CLI.

8) Voz + superfície expandida de comandos Android

• Aba Voz: o Android tem dois modos explícitos de captura. Microfone é uma sessão manual da aba Voz que envia cada pausa como uma rodada de chat e para quando o app sai do primeiro plano ou quando o usuário sai da aba Voz. Falar é o Modo Falar contínuo e continua ouvindo até ser desativado ou até o nó se desconectar.
• O Modo Falar promove o serviço em primeiro plano existente de connectedDevice para connectedDevice|microphone antes do início da captura e depois o rebaixa quando o Modo Falar para. O serviço de nó declara FOREGROUND_SERVICE_CONNECTED_DEVICE com CHANGE_NETWORK_STATE; Android 14+ também exige a declaração FOREGROUND_SERVICE_MICROPHONE, a concessão de runtime RECORD_AUDIO e o tipo de serviço de microfone em runtime.
• Por padrão, o Falar do Android usa reconhecimento de fala nativo, chat do Gateway e talk.speak pelo provedor Falar configurado do gateway. TTS local do sistema é usado somente quando talk.speak não está disponível.
• O Falar do Android usa relay em tempo real do Gateway somente quando talk.realtime.mode é realtime e talk.realtime.transport é gateway-relay.
• A ativação por voz permanece desabilitada na UX/runtime do Android.
• Famílias adicionais de comandos Android (a disponibilidade depende do dispositivo, permissões e configurações do usuário):
  • device.status, device.info, device.permissions, device.health
  • device.apps somente quando Configurações > Recursos do telefone > Apps instalados está habilitado; lista apps visíveis no iniciador por padrão.
  • notifications.list, notifications.actions (consulte Encaminhamento de notificações abaixo)
  • photos.latest
  • contacts.search, contacts.add
  • calendar.events, calendar.add
  • callLog.search
  • sms.search
  • motion.activity, motion.pedometer

Pontos de entrada do assistente

O Android oferece suporte à inicialização do OpenClaw pelo gatilho do assistente do sistema (Google Assistant). Quando configurado, segurar o botão de início ou dizer "Hey Google, ask OpenClaw..." abre o app e entrega o prompt ao compositor de chat.

Isso usa metadados de App Actions do Android declarados no manifesto do app. Nenhuma configuração extra é necessária no lado do gateway -- a intenção do assistente é tratada inteiramente pelo app Android e encaminhada como uma mensagem de chat normal.

Encaminhamento de notificações

O Android pode encaminhar notificações do dispositivo para o gateway como eventos. Vários controles permitem delimitar quais notificações são encaminhadas e quando.

O seletor de notificações também usa comportamento mais seguro para eventos de notificação encaminhados, evitando o encaminhamento acidental de notificações sensíveis do sistema.

Exemplo de configuração:

{  notifications: {    allowPackages: ["com.slack", "com.whatsapp"],    denyPackages: ["com.android.systemui"],    quietHours: {      start: "22:00",      end: "07:00",    },    rateLimit: 5,  },}

Relacionados

• App iOS
• Nós
• Solução de problemas de nó Android