O aplicativo oficial para Android está disponível no Google Play e como um APK independente assinado nas versões do GitHub compatíveis. Ele é um Node complementar e requer um Gateway OpenClaw em execução. Código-fonte: apps/android (instruções de compilação).
Visão geral do suporte
- Função: aplicativo de Node complementar (o Android não hospeda o Gateway).
- Gateway necessário: sim (execute-o no macOS, Linux ou Windows via WSL2).
- Instalação: Google Play ou
OpenClaw-Android.apkde uma versão do GitHub compatível, Primeiros passos para o Gateway e, em seguida, Emparelhamento. - Gateway: Guia operacional + Configuração.
- Protocolos: protocolo do Gateway (Nodes + plano de controle).
Instalação fora do Google Play
As versões finais e de correção regulares do GitHub incluem umOpenClaw-Android.apk universal e OpenClaw-Android-SHA256SUMS.txt. O APK é compilado a partir da tag da versão, assinado com a chave de versão do OpenClaw para Android e inclui a procedência do GitHub Actions.
Escolha uma versão que liste ambos os artefatos e, em seguida, baixe e verifique essa tag exata antes da instalação manual:
Espelhamento e controle do Android a partir de um Mac remoto
O scrcpy espelha a tela de um Android em uma janela do macOS e encaminha a entrada do teclado e do ponteiro pelo Android Debug Bridge (ADB). Esse é um fluxo de trabalho do operador, separado da conexão do Node OpenClaw. Ele é útil quando o dispositivo Android e o Mac estão em locais diferentes, mas compartilham uma rede Tailscale privada.Antes de começar
- Instale o Tailscale no dispositivo Android e no Mac e conecte ambos à mesma tailnet.
- No Android, ative Developer options e USB debugging. O Android 16 coloca Wireless debugging em Settings > System > Developer options. Consulte as opções de desenvolvedor do Android.
-
Instale o scrcpy e o ADB no Mac:
- Mantenha o dispositivo Android disponível para a primeira conexão. O Android deve aprovar a chave ADB de cada Mac antes que ele possa controlar o dispositivo.
Ativar o ADB sobre TCP
Para a configuração inicial, conecte o dispositivo Android via USB a um computador confiável e aprove a solicitação de depuração. Em seguida, execute:adb pair.
Permitir somente o Mac controlador
Tailnets com permissões restritivas devem permitir explicitamente que o Mac controlador acesse a porta TCP 5555 no dispositivo Android. Adicione uma regra restrita à política da tailnet, substituindo os endereços de exemplo pelos IPs estáveis do Tailscale dos dois dispositivos:Conectar e iniciar o espelhamento
No Mac remoto:adb connect desse Mac exibe uma caixa de diálogo de autorização no Android. Desbloqueie o dispositivo,
confirme a impressão digital da chave e selecione Always allow from this computer somente se o Mac for
confiável. Uma entrada adb devices bem-sucedida termina em device; unauthorized significa que a solicitação no dispositivo
não foi aprovada.
Quando a janela do scrcpy for aberta, use-a diretamente ou direcione a ela uma ferramenta de automação de tela do macOS, como
o Peekaboo. O scrcpy transmite a tela e a entrada; o Tailscale fornece somente o
caminho de rede privado.
Solução de problemas
Connection timed out: verifique a permissão da tailnet para a porta TCP 5555. Umtailscale pingbem-sucedido comprova a conectividade entre os pares, não que a política permita essa porta TCP. Teste comnc -vz <android-tailnet-ip> 5555no Mac.unauthorized: desbloqueie o Android e aprove a chave ADB do Mac remoto ou remova a estação de trabalho obsoleta em Wireless debugging > Paired devices e emparelhe-a novamente.Connection refused: reconecte localmente e executeadb tcpip 5555novamente.- Mais de um dispositivo listado: mantenha o argumento
--serial <android-tailnet-ip>:5555explícito.
Guia operacional de conexão
Aplicativo de Node Android ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway O Android se conecta diretamente ao WebSocket do Gateway e usa o emparelhamento de dispositivos (role: node).
Para hosts públicos ou via Tailscale, o Android requer um endpoint seguro:
- Preferencial: Tailscale Serve/Funnel com
https://<magicdns>/wss://<magicdns> - Também compatível: qualquer outra URL
wss://do Gateway com um endpoint TLS real - O
ws://sem criptografia continua compatível em endereços de LAN privada/hosts.local, além delocalhost,127.0.0.1e da ponte do emulador Android (10.0.2.2); a configuração sem loopback usa automaticamente acesso limitado de operador
Pré-requisitos
- Gateway em execução em outra máquina (ou acessível via SSH).
- O dispositivo/emulador Android consegue acessar o WebSocket do Gateway:
- Mesma LAN com mDNS/NSD, ou
- Mesma tailnet do Tailscale usando Wide-Area Bonjour/DNS-SD unicast (veja abaixo), ou
- Host/porta do Gateway definidos manualmente (alternativa)
- O emparelhamento móvel por tailnet/rede pública não usa endpoints
ws://de IP bruto da tailnet. Em vez disso, use o Tailscale Serve ou outra URLwss://. - A CLI
openclawdisponível na máquina do Gateway (ou via SSH) para aprovar solicitações de emparelhamento.
1. Iniciar o Gateway
listening on ws://0.0.0.0:18789
wss:///https://. Uma configuração simples de gateway.bind: "tailnet" não é suficiente para o primeiro emparelhamento remoto do Android, a menos que você também encerre o TLS separadamente.
2. Verificar a descoberta (opcional)
Na máquina do Gateway:local. e o domínio de longa distância configurado em uma única execução, usando o endpoint de serviço resolvido em vez de apenas dicas TXT.
Descoberta entre redes via DNS-SD unicast
A descoberta NSD/mDNS do Android não atravessa redes. Se o Node Android e o Gateway estiverem em redes diferentes, mas conectados pelo Tailscale, use o Wide-Area Bonjour/DNS-SD unicast. A descoberta por si só não é suficiente para o emparelhamento do Android por tailnet/rede pública — a rota descoberta ainda precisa de um endpoint seguro (wss:// ou Tailscale Serve):
- Configure uma zona DNS-SD (por exemplo,
openclaw.internal.) no host do Gateway e publique registros_openclaw-gw._tcp. - Configure o DNS dividido do Tailscale para que o domínio escolhido aponte para esse servidor DNS.
3. Conectar pelo Android
No aplicativo Android:- O aplicativo mantém a conexão com o Gateway ativa por meio de um serviço em primeiro plano (notificação persistente).
- Abra a guia Connect.
- Use o modo Setup Code ou Manual.
- Se a descoberta estiver bloqueada, use o host/porta manual em Advanced controls. Para hosts em LAN privada,
ws://ainda funciona. Para hosts públicos ou via Tailscale, ative o TLS e use um endpointwss:///Tailscale Serve.
wss://. A configuração ws:// sem criptografia e sem loopback
usa automaticamente acesso limitado para proteger o token de portador. Settings → Gateway
mostra o acesso Full ou Limited. Para uma conexão limitada, configure
wss:// ou o Tailscale Serve, gere um novo código de acesso completo na Control UI ou
com openclaw qr, depois escaneie-o ou cole-o nessa página e reconecte. Os operadores
que desejam o perfil reduzido podem selecionar Limited access na Control UI ou executar
openclaw qr --limited.
Vários Gateways
O aplicativo mantém um registro de todos os Gateways com os quais foi emparelhado, permitindo alternar entre eles sem emparelhar novamente:- Settings -> Gateways lista os Gateways emparelhados e marca o ativo. Toque em uma entrada para alternar; o aplicativo encerra as sessões atuais e se reconecta ao Gateway selecionado.
- A guia Connect mostra um seletor rápido quando há mais de um Gateway emparelhado.
- Credenciais, tokens de dispositivo, confiança TLS, histórico de conversas e mensagens offline enfileiradas são armazenados por Gateway. A alternância nunca mistura o estado entre Gateways, e as mensagens enfileiradas enquanto offline são entregues somente ao Gateway para o qual foram escritas.
- Forget remove a entrada do Gateway no registro, juntamente com suas credenciais, tokens de dispositivo, fixação TLS e conversas armazenadas em cache.
Sinais de presença ativa
Depois que a sessão autenticada do Node se conecta e quando o aplicativo passa para segundo plano enquanto o serviço em primeiro plano ainda está conectado, o Android chamanode.event com event: "node.presence.alive". O Gateway registra isso como lastSeenAtMs/lastSeenReason nos metadados do Node/dispositivo emparelhado somente depois que a identidade autenticada do dispositivo Node é conhecida.
O aplicativo considera o sinal 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 persistente da última atividade.
4. Aprovar o emparelhamento (CLI)
Na máquina do Gateway:role: node novos, sem escopos solicitados. O 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 Node está conectado
6. Chat + histórico
A aba Chat do Android permite selecionar a sessão (por padrão,main, além de outras sessões existentes):
- Histórico:
chat.history(normalizado para exibição — tags de diretivas em linha, cargas XML de chamadas de ferramenta em texto simples (<tool_call>,<function_call>,<tool_calls>,<function_calls>e variantes truncadas) e tokens de controle do modelo ASCII/de largura completa vazados são removidos; linhas do assistente com tokens silenciosos, comoNO_REPLY/no_replyexatos, são omitidas; linhas grandes demais podem ser substituídas por espaços reservados) - Envio:
chat.send - Envio durável: cada envio (texto, imagens selecionadas e mensagens de voz) é registrado em uma caixa de saída no dispositivo, específica de cada Gateway, antes de qualquer tentativa de rede; assim, o encerramento do aplicativo não pode causar a perda da entrada enviada. Envios enfileirados enquanto estiver offline são entregues em ordem após a reconexão, com chaves de idempotência estáveis, e um envio só é removido depois que o turno fica visível no
chat.historycanônico — uma confirmação isolada não é tratada como prova de entrega. Resultados ambíguos (confirmação perdida, aplicativo encerrado durante o envio, reinicialização do Gateway antes da gravação da transcrição) aparecem como linhas visíveis com Tentar novamente/Excluir explícitos, em vez de serem reenviados automaticamente. Comandos de barra nunca são repetidos automaticamente após uma reconexão; ficam suspensos para uma nova tentativa explícita. A fila é limitada (50 mensagens e 48 MB de bytes de anexos por Gateway), e linhas não enviadas expiram após 48 horas. Rascunhos do compositor que nunca foram enviados não persistem entre processos. - Atualizações push (melhor esforço):
chat.subscribe->event:"chat" - Ouvir: mantenha pressionada uma mensagem do assistente e escolha Ouvir para escutá-la; o áudio é renderizado pelo
tts.speakdo Gateway usando a cadeia de provedores de TTS configurada, e o TTS do sistema no dispositivo é usado quando o Gateway não consegue renderizar o áudio. A reprodução é interrompida ao trocar de sessão, iniciar um novo chat, colocar o aplicativo em segundo plano ou fechar o chat.
7. Canvas + câmera
Host de Canvas do Gateway (recomendado para conteúdo da Web)
Para que o Node mostre HTML/CSS/JS reais que o agente possa editar no disco, aponte o Node para o host de Canvas do Gateway.Os Nodes carregam o Canvas do servidor HTTP do Gateway (a mesma porta de
gateway.port, por padrão 18789).- Crie
~/.openclaw/workspace/canvas/index.htmlno host do Gateway. - Navegue até ele no Node (LAN):
.local, por exemplo, http://<gateway-magicdns>:18789/__openclaw__/canvas/.
Esse servidor injeta um cliente de recarregamento em tempo real no HTML e recarrega quando os arquivos são alterados. O Gateway também disponibiliza /__openclaw__/a2ui/, mas o aplicativo Android trata páginas A2UI remotas apenas como conteúdo para renderização. Comandos A2UI compatíveis com ações usam a página A2UI integrada e pertencente ao aplicativo.
Comandos do Canvas (somente em primeiro plano):
canvas.eval,canvas.snapshot,canvas.navigate(use{"url":""}ou{"url":"/"}para retornar à estrutura padrão).canvas.snapshotretorna{ format, base64 }(por padrão,format="jpeg").- A2UI:
canvas.a2ui.push,canvas.a2ui.reset(alias legadocanvas.a2ui.pushJSONL). Esses comandos usam a página A2UI integrada e pertencente ao aplicativo para renderização compatível com ações.
camera.snap (jpg), camera.clip (mp4). Consulte Node de câmera para ver parâmetros e auxiliares da CLI.
8. Voz + superfície expandida de comandos do 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 um turno de chat e é interrompida quando o aplicativo sai do primeiro plano ou quando o usuário sai da aba Voz. Conversar é o Modo de Conversa contínuo e continua ouvindo até ser desativado ou até o Node se desconectar.
- O Modo de Conversa promove o serviço em primeiro plano existente de
connectedDeviceparaconnectedDevice|microphoneantes do início da captura e o rebaixa quando o Modo de Conversa é interrompido. O serviço do Node declaraFOREGROUND_SERVICE_CONNECTED_DEVICEcomCHANGE_NETWORK_STATE; o Android 14+ também exige a declaraçãoFOREGROUND_SERVICE_MICROPHONE, a concessão em tempo de execuçãoRECORD_AUDIOe o tipo de serviço de microfone em tempo de execução. - Por padrão, o recurso Conversar do Android usa reconhecimento de fala nativo, o chat do Gateway e
talk.speakpor meio do provedor de Conversa configurado no Gateway. O TTS do sistema local é usado somente quandotalk.speaknão está disponível. - O recurso Conversar do Android usa a retransmissão em tempo real do Gateway somente quando
talk.realtime.modeérealtimeetalk.realtime.transportégateway-relay. - O Android não anuncia o recurso
voiceWake. Use Microfone ou Conversar para entrada de voz. - Famílias adicionais de comandos do Android (a disponibilidade depende do dispositivo, das permissões e das configurações do usuário):
device.status,device.info,device.permissions,device.healthdevice.appssomente quando Settings > Phone Capabilities > Installed Apps está habilitado; por padrão, lista os aplicativos visíveis no inicializador (passeincludeNonLaunchablepara obter a lista completa).notifications.list,notifications.actions(consulte Encaminhamento de notificações abaixo)photos.latestcontacts.search,contacts.addcalendar.events,calendar.addcallLog.searchsms.searchmotion.activity,motion.pedometer
9. Arquivos do espaço de trabalho (somente leitura)
A visão geral da tela inicial inclui um cartão Arquivos que permite navegar pelo espaço de trabalho do agente ativo por meio dos RPCs somente leituraagents.workspace.list / agents.workspace.get do Gateway: navegação em diretórios, pré-visualizações de texto e imagem e exportação pela folha de compartilhamento do Android. Não há operações de gravação, e o tamanho das pré-visualizações é limitado pelo Gateway.
Revisar aprovações de comandos
Uma conexão de operador comoperator.admin, ou uma conexão
operator.approvals pareada e explicitamente direcionada pelo Gateway, pode revisar
solicitações de execução pendentes em Configurações -> Aprovações. O aplicativo carrega o
registro de aprovação sanitizado do Gateway antes de habilitar os botões, mostra qualquer
aviso de segurança e as decisões exatas oferecidas pela solicitação e envia
o ID da aprovação e o tipo de proprietário de volta ao Gateway.
O estado da aprovação é compartilhado com a UI de Controle e as superfícies de chat compatíveis. A
primeira resposta confirmada prevalece; o Android exibe esse resultado canônico mesmo quando
outra superfície responde primeiro. Se uma resposta de resolução for perdida ou o Gateway
se desconectar, o aplicativo mantém a ação bloqueada e lê novamente a aprovação
antes de oferecer outra decisão.
Gateways anteriores aos métodos unificados de aprovação recorrem aos métodos
específicos de execução já disponibilizados. A revisão pendente continua funcionando, mas o estado
retido do terminal e o resultado mais completo entre superfícies exigem um Gateway atualizado.
Pontos de entrada do assistente
O Android permite iniciar o OpenClaw pelo acionador do assistente do sistema (Google Assistente). Manter pressionado o botão inicial (ou outro acionadorACTION_ASSIST) abre o aplicativo; dizer “Hey Google, ask OpenClaw <prompt>” corresponde ao padrão de consulta de App Actions declarado pelo aplicativo e transfere o prompt para o compositor de chat sem enviá-lo automaticamente.
Isso usa App Actions do Android (recurso shortcuts.xml) declarado no manifesto do aplicativo. Nenhuma configuração no Gateway é necessária — a intenção do assistente é processada inteiramente pelo aplicativo Android.
A disponibilidade de App Actions depende do dispositivo, da versão do Google Play Services e de o usuário ter definido o OpenClaw como aplicativo de assistente padrão.
Encaminhamento de notificações
O Android pode encaminhar notificações do dispositivo ao Gateway como itensnode.event. Isso é configurado no dispositivo, na folha de Configurações do aplicativo — não na configuração gateway/openclaw.json.
O encaminhamento de notificações exige a permissão de ouvinte de notificações do Android. O aplicativo solicita essa permissão durante a configuração.