Como usar o Claude Code no telemóvel via SSH

Claude Code no celular: como funciona na prática

Este guia usa um aplicativo de terminal no celular. O Claude Code é executado em um VPS (servidor virtual privado), dentro de uma sessão do tmux que permanece aberta, e o celular abre uma conexão SSH (shell seguro) para essa sessão enquanto você a consulta. Feche o aplicativo e o agente continuará trabalhando, porque o processo nunca foi executado no celular.

O Claude Code também oferece o Remote Control: execute /remote-control dentro de uma sessão para usá-lo pelo aplicativo móvel do Claude ou por um navegador, enquanto o processo permanece no servidor.

Essa separação é a base de todo o projeto. Um sistema operacional de celular suspende um aplicativo alguns segundos depois que você muda para outro, portanto qualquer tarefa longa iniciada no celular é interrompida. Além disso, o celular recebe um novo endereço de rede toda vez que você passa do Wi-Fi para a rede móvel. Os dois problemas desaparecem quando o processo é executado em um servidor e o celular apenas exibe a tela.

Você precisa de quatro coisas no servidor: tmux para manter a sessão, chaves SSH para acessar o servidor, mosh para lidar com mudanças de rede e o próprio Claude Code. No celular, basta um aplicativo de terminal com uma fileira de teclas de fácil acesso.

O que você precisa no VPS

Uma máquina Ubuntu 24.04 pequena é suficiente para as partes sobre SSH e tmux. O Claude Code exige mais. Os requisitos oficiais em outubro de 2026 são Ubuntu 20.04 ou mais recente em um processador x64 ou ARM64, com 4 GB ou mais de RAM. O Claude Code também exige uma conta paga do Claude (Pro, Max, Team ou Enterprise), uma conta do Console com acesso à API ou acesso por meio de um provedor de nuvem compatível, como Amazon Bedrock, porque o plano gratuito do Claude.ai não inclui esse acesso.

Configure o VPS com um usuário comum e sudo, não como root. Se o servidor for novo, siga primeiro os primeiros dez minutos em um VPS novo, porque as alterações de SSH descritas mais adiante neste guia são mais fáceis depois que o usuário e o firewall já existem.

sudo apt update && sudo apt install -y tmux mosh
curl -fsSL https://claude.ai/install.sh | bash
claude --version

O instalador coloca o binário em ~/.local/bin/claude, e claude --version exibe uma linha como 2.1.211 (Claude Code). Se ele exibir command not found, esse diretório ainda não está no seu PATH: saia da sessão, entre novamente e verifique com command -v claude. claude doctor exibe diagnósticos da instalação e das configurações sem iniciar uma sessão.

Faça login uma vez agora, a partir de um laptop, antes de depender do telefone. Execute claude em um diretório de projeto e siga o prompt de login. O fluxo pede que você abra uma URL no navegador e leve um código de volta ao terminal. Fazer isso alternando entre dois aplicativos na tela do telefone é demorado. Faça essa etapa uma vez em um teclado físico, e as credenciais permanecerão no servidor.

Inicie o Claude Code dentro do tmux para que uma ligação interrompida não o termine

tmux new -s claude
cd ~/projects/api
claude

Desanexe com Ctrl-b e depois com d. O tmux apresenta [detached (from session claude)] e devolve o controlo à shell. Agora pode fechar a aplicação, perder o sinal ou guardar o telefone no bolso. O painel continua a executar.

tmux ls
tmux attach -t claude

tmux ls apresenta uma linha por sessão, como claude: 1 windows (created Thu Jul 30 09:14:02 2026). tmux attach -t claude devolve-o exatamente ao ponto onde ficou, incluindo a edição incompleta.

Isto funciona porque o tmux executa o seu próprio processo de servidor, e a shell e o Claude Code são processos filhos desse servidor, e não de sshd. Quando a ligação SSH termina, o kernel envia o sinal de interrupção, SIGHUP, aos processos associados a essa ligação, e o servidor tmux não é um deles. Sem o tmux, o mesmo bloqueio do ecrã que interrompe a ligação também para o Claude Code a meio de uma chamada de ferramenta. Executar o Claude Code num VPS dentro do tmux aborda a organização da sessão com mais detalhe.

Execute o tmux no servidor, nunca no telefone. Introduzir tmux dentro de uma sessão à qual já está ligado apresenta sessions should be nested with care, unset $TMUX to force, e forçar a operação deixa dois prefixos de teclas em conflito.

Anexar automaticamente em cada login

Digitar o comando de anexação num teclado tátil torna-se cansativo. Adicione isto ao fim de ~/.profile no servidor:

if command -v tmux >/dev/null 2>&1 && [ -z "$TMUX" ] && [ -t 1 ]; then
  exec tmux new-session -A -s claude
fi

new-session -A -s claude anexa à sessão chamada claude se ela existir e cria-a se não existir, portanto um comando cobre os dois casos. exec substitui a shell de login pelo tmux, portanto sair do tmux fecha a ligação em vez de o deixar numa prompt vazia. Quando precisar de uma shell simples, ignore o ficheiro: ssh you@server -t "bash --noprofile".

Coloque isto em ~/.profile e não em ~/.bashrc. O Bash também lê ~/.bashrc para comandos SSH não interativos, mas a condição [ -t 1 ] acima impede que este bloco inicie o tmux durante uma transferência de ficheiros. Comandos de arranque sem essa condição que imprimam saída interrompem os protocolos de transferência com erros como Received message too long. ~/.profile é executado apenas para shells de login, que é o caso de uma sessão SSH interativa.

~/.profile também é onde o Ubuntu adiciona ~/.local/bin a PATH. Se claude funcionar logo depois do login, mas uma shell dentro do tmux indicar command not found, essa ordenação é a causa. Nesse caso, inicie o tmux a partir de uma shell de login, como acima, e não a partir de um script que ignore o profile.

iOS: Termius ou Blink Shell

Ambas as aplicações suportam SSH e mosh e armazenam as chaves na própria aplicação. A diferença está na interface.

O Blink Shell é orientado por comandos. Na linha de comandos, introduza ssh you@server ou mosh you@server, usando a mesma sintaxe de um terminal de computador. Abra as definições introduzindo config. A secção Keys cria um par de chaves por si.

O Termius é orientado por formulários. Preencha uma entrada de host e, nos detalhes desse host, altere o protocolo de SSH para Mosh. O Termius inclui a sua própria implementação de mosh e suporta mosh 1.3.0 e versões posteriores. Por isso, o servidor precisa igualmente de ter o pacote mosh instalado.

Em ambos os casos, gere a chave dentro da aplicação. Nunca copie uma chave privada existente para o telefone. A aplicação mostra a parte pública. Essa é a única linha que deve adicionar a ~/.ssh/authorized_keys no servidor. Chaves SSH por dispositivo e como revogar uma explica a convenção de nomes e o procedimento de revogação. Isto é mais importante num telefone do que num portátil.

Ative o bloqueio biométrico ou por código da própria aplicação de terminal. Sem esse bloqueio, um telefone desbloqueado dá acesso a uma shell aberta no servidor enquanto o ecrã permanecer ativo.

Android: Termux

pkg upgrade
pkg install openssh mosh
ssh-keygen -t ed25519 -C "pixel"
cat ~/.ssh/id_ed25519.pub

O Termux disponibiliza OpenSSH e mosh no seu próprio repositório, por isso ssh, ssh-keygen e mosh funcionam da mesma forma que num computador. Adicione a linha da chave pública apresentada a ~/.ssh/authorized_keys no servidor e, em seguida, ligue-se com mosh you@server.

O teclado no ecrã do Android não tem as teclas Esc e Ctrl, e o Claude Code precisa das duas. O Termux pode apresentar a sua própria linha de teclas. Adicione uma linha a ~/.termux/termux.properties:

extra-keys = [['ESC','|','/','HOME','UP','END','PGUP'],['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN']]

Depois execute termux-reload-settings e a linha aparece acima do teclado. O mesmo recarregamento deteta um tipo de letra TrueType monoespaçado colocado em ~/.termux/font.ttf.

O Android pode parar o Termux quando este fica em segundo plano. Neste caso, isso só exige uma nova ligação. A sessão e o agente estão no servidor.

Por que o terminal congela quando saio do wifi, e o que o mosh corrige?

Uma conexão SSH é uma conexão TCP (transmission control protocol), e uma conexão TCP é identificada pelos dois endereços e pelas duas portas. Saia do alcance do wifi e o telefone receberá um novo endereço da rede móvel, então a conexão antiga não corresponderá a nada em nenhuma das extremidades. Nada anuncia isso. O terminal simplesmente para de responder até que o TCP desista, e então o ssh imprime client_loop: send disconnect: Broken pipe. Para encerrar uma sessão congelada imediatamente, pressione Enter, depois ~ e depois ..

O mosh (mobile shell) elimina esse modo de falha. Ele usa o SSH uma vez para fazer login e iniciar um processo mosh-server, lê a porta UDP (user datagram protocol) escolhida pelo servidor e fecha a conexão SSH. Depois disso, os dois lados trocam datagramas UDP autenticados com uma chave de sessão compartilhada, então a sessão é identificada por essa chave, e não pelo seu endereço. Um novo endereço simplesmente dá continuidade à sessão. O mosh também exibe sua digitação localmente e redesenha a tela quando o servidor discorda, por isso continua utilizável em uma conexão móvel lenta.

O mosh usa uma porta UDP entre 60000 e 61000, então abra esse intervalo:

sudo ufw allow 60000:61000/udp
sudo ufw status

Abrindo portas com ufw mostra o restante da configuração do firewall. Se o seu provedor oferecer um firewall de rede separado no painel de controle, adicione o mesmo intervalo nele também, porque uma regra do ufw não pode afetar um filtro que esteja na frente da máquina.

Dois problemas do mosh são comuns. Um login que é bem-sucedido e depois trava, exibindo Nothing received from server on UDP port 60001., significa que mosh-server foi iniciado, mas o cliente não consegue alcançá-lo nessa porta UDP. Em geral, isso significa que um firewall em algum ponto entre o telefone e o servidor está bloqueando UDP no intervalo do mosh. Uma conexão que informa que mosh-server não foi encontrado significa que o pacote está ausente no servidor ou não está presente no PATH do login. Instale-o ou aponte diretamente para ele com mosh --server=/usr/bin/mosh-server you@server.

Se a localidade de login do servidor não for UTF-8, mosh-server tentará usar as configurações de localidade fornecidas pelo cliente e verificará novamente. Ele se recusará a executar somente se isso também não fornecer UTF-8, informando mosh-server needs a UTF-8 native locale to run.. Corrija primeiro a localidade no servidor.

locale
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8

As duas extremidades precisam de uma localidade UTF-8, e mosh-server também aplica as configurações de localidade enviadas pelo cliente. Se o erro continuar depois da correção no servidor, defina LANG com um valor UTF-8 também no aplicativo de terminal do telefone, pois a própria FAQ do mosh observa que mosh-client pode precisar disso.

Duas coisas que o mosh não faz. O README informa que o mosh não oferece suporte a X forwarding nem aos usos não interativos do SSH, incluindo encaminhamento de portas, portanto visualizar uma aplicação web que o Claude Code acabou de iniciar ainda exige o ssh -L 8080:127.0.0.1:8080 you@server simples. Ele também sincroniza somente a tela visível, então não tem seu próprio histórico de rolagem. Essa segunda limitação não causa problemas aqui, porque o tmux mantém o histórico: Ctrl-b e depois [ entram no modo de cópia, arrastar ou usar as teclas de seta faz a rolagem, e q sai do modo.

Torne a tela do celular utilizável

Quatro linhas em ~/.tmux.conf no servidor fazem a maior parte do trabalho:

set -g mouse on
set -g status-position top
set -g default-terminal "tmux-256color"
set -g history-limit 20000

mouse on transforma um arrasto de toque em rolagem e um toque em seleção de painel ou janela, substituindo a maior parte das teclas de prefixo difíceis de digitar. status-position top move a linha de status do tmux para longe da borda inferior, onde o teclado na tela e sua barra de sugestões a cobrem. default-terminal fixa o nome do terminal que o tmux anuncia para o Claude Code. Sem essa linha, o tmux anuncia qualquer nome escolhido pelo build. O script configure do tmux 3.4 começa em screen e testa screen-256color, tmux e tmux-256color nessa ordem; se um teste falhar, a escolha anterior é mantida. Um build que não encontrou a entrada de terminfo tmux-256color acaba usando tmux, screen-256color ou simplesmente screen, e as cores e o desenho de caixas podem ficar piores do que deveriam.

Aprenda quatro teclas e o restante fica confortável.

• Esc interrompe o Claude no meio da resposta e mantém o trabalho já realizado, por isso é a tecla que você deve deixar mais perto do polegar.
• Ctrl+C também interrompe uma operação em execução. Em um prompt ocioso, o primeiro pressionamento limpa a entrada e o segundo sai do Claude Code, portanto é uma ferramenta mais brusca.
• Esc duas vezes limpa um prompt em edição e, em um prompt vazio, abre o menu de rewind.
• Para um prompt com várias linhas, digite \ e pressione Enter. Essa forma funciona em qualquer terminal. Shift+Enter é nativo apenas em uma lista curta de terminais de desktop, e os clientes móveis não estão nela.

Evite painéis divididos. Um celular em modo retrato tem cerca de 40 colunas de largura, então uma divisão vertical deixa 20 colunas por painel e todo diff quebra linhas até virar ruído. Use janelas do tmux: Ctrl-b c cria uma e Ctrl-b n vai para a próxima. Se uma segunda janela acabar mantendo sua própria sessão do Claude Code, as duas sessões podem encaminhar trabalho diretamente entre si em vez de você copiar texto entre janelas em uma tela sensível ao toque. Vire o celular de lado quando precisar ler um diff corretamente.

Vale a pena definir deliberadamente quanto texto aparece nessa tela, porque um estilo de saída edita o prompt do sistema por trás de cada resposta e um estilo mais conciso significa menos telas para percorrer no celular.

Uma sessão longa em uma tela pequena é principalmente um problema de contexto, por isso vale ler como gerenciar a janela de contexto do Claude Code antes de tentar executar um dia inteiro de trabalho em um trem.

Bloqueie o acesso: apenas chaves, sem senhas

O celular agora tem uma chave para uma máquina que edita seu código e executa comandos. Desative a autenticação por senha. Um arquivo drop-in é mais seguro do que editar sshd_config diretamente, porque o sshd_config do Ubuntu inclui /etc/ssh/sshd_config.d/*.conf no início, e o primeiro valor encontrado para uma configuração é o que será usado.

sudo tee /etc/ssh/sshd_config.d/00-phone.conf >/dev/null <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
PermitRootLogin no
EOF
sudo sshd -t && sudo systemctl reload ssh

Os drop-ins são lidos na ordem dos nomes dos arquivos. Verifique sudo sshd -T em busca de passwordauthentication no, kbdinteractiveauthentication no, pubkeyauthentication yes e permitrootlogin no; um arquivo anterior que defina um desses valores tem precedência e precisa ser corrigido nesse arquivo.

sshd -t analisa a configuração e não exibe nada quando ela é válida. Se você ignorar essa etapa, um erro de digitação fará sshd falhar durante o reload. Mantenha sua sessão de trabalho aberta e teste a partir de uma segunda conexão antes de fechar qualquer coisa, porque uma chave incorreta agora resulta em Permission denied (publickey). e, com as senhas desativadas, não há fallback. Nesse ponto, o caminho de recuperação é o console do seu provedor. Se essa conexão de teste falhar, reconecte com ssh -v e corrija o problema enquanto a primeira sessão ainda estiver aberta, porque essa única mensagem de erro abrange cinco falhas distintas e a saída detalhada informa qual delas ocorreu.

Dê a cada dispositivo sua própria chave. Se você perder o celular, basta excluir uma linha de ~/.ssh/authorized_keys, e o laptop continuará funcionando. Uma chave compartilhada exige alterar a chave em todos os dispositivos que você possui.

Se você mudar o SSH para outra porta no Ubuntu 24.04, observe que o listener pertence a ssh.socket. Um gerador do systemd cria esse socket a partir da linha Port na configuração do SSH, portanto você não precisa de um override ListenStream, mas reiniciar ssh sozinho deixa o servidor escutando na porta 22. Coloque a linha Port em um drop-in, permita a nova porta no ufw e execute sudo systemctl daemon-reload seguido de sudo systemctl restart ssh.socket. Protegendo o SSH em um VPS aborda esse assunto e o restante da superfície exposta.

fail2ban para SSH acrescenta pouca segurança depois que as senhas são desativadas, porque uma senha adivinhada não pode ser aceita. O que ele acrescenta são logs mais silenciosos, o que facilita identificar uma tentativa real de login.

A opção mais segura é manter o SSH fora da internet pública. Coloque o servidor atrás de uma VPN WireGuard hospedada por você, ative o túnel no celular quando necessário e permita que o sshd tenha um ListenAddress apenas no túnel. O mosh funciona pelo túnel porque os dois lados usam UDP. Há uma ressalva: o túnel acrescenta overhead aos pacotes. Portanto, se transferências grandes travarem, reduza o MTU (maximum transmission unit) na configuração do WireGuard no celular.

Um último ponto sobre trabalhar dessa forma. No celular, você aprova prompts de permissão em uma tela que mostra poucas linhas do diff por vez. Isso é um motivo para manter as proteções, não para desativá-las. Verifique também em qual modo de permissão suas sessões iniciam, porque o modo automático agora é o modo inicial integrado para sessões interativas de terminal a partir do Claude Code v2.1.283, e ele aplica edições de arquivos no diretório de trabalho sem parar para pedir sua confirmação. Executando o Claude Code com segurança em um VPS aborda os limites de usuário e diretório que vale a pena definir antes que seu principal meio de acesso seja uma tela sensível ao toque.

Quando você se reconecta e algo está errado

tmux attach printing no server running on /tmp/tmux-1000/default significa que o tmux não encontrou um servidor nesse socket. Normalmente, o servidor foi encerrado, o que quase sempre significa que a máquina reiniciou. Verifique com uptime. Se a máquina não reiniciou e pgrep tmux ainda mostra um servidor, isso por si só não significa que o arquivo de socket foi excluído, porque as opções -L e -S permitem que um servidor escute em outro socket. Se você iniciou o tmux com uma delas, passe a mesma opção para tmux attach. Se o socket realmente foi removido por engano, pkill -USR1 tmux solicita que o servidor o recrie, mas o manual do tmux informa que isso falha se algum diretório pai estiver ausente. As atualizações do kernel provenientes de atualizações automáticas de segurança exigem uma reinicialização para entrar em vigor, mas unattended-upgrades reinicia automaticamente somente quando Unattended-Upgrade::Automatic-Reboot está habilitado; o valor padrão é false. Uma máquina reiniciada não tem uma sessão do tmux, portanto trate qualquer execução do Claude Code como algo que pode ser reiniciado.

can't find session: claude é diferente. O servidor do tmux está em execução, mas esse nome não existe. tmux ls mostra o que existe.

Se você se conectar e encontrar um prompt de shell comum onde antes estava o Claude Code, o processo terminou sem que a sessão terminasse. Procure em dmesg -T | tail uma linha como Out of memory: Killed process 4821 (claude), que confirma uma finalização por falta de memória. Verifique o scrollback do shell acima do prompt para encontrar outras mensagens de saída.

Uma janela que volta com o tamanho incorreto, cortada na borda ou com espaço não utilizado ao redor indica que dois clientes estão conectados com tamanhos diferentes. Por padrão, o tmux 3.4 ajusta o tamanho da janela ao cliente com a atividade mais recente (window-size latest), então o laptop, ainda conectado com 200 colunas de largura, e o telefone, com 40, redimensionam a janela alternadamente. Desconecte os outros clientes ao se conectar: tmux attach -d -t claude.

FAQ

Posso executar o Claude Code no próprio telefone em vez de executá-lo em um VPS?

A CLI de terminal não é compatível com Android ou iOS. As plataformas compatíveis em outubro de 2026 são macOS, Windows, Ubuntu 20.04 ou mais recente, Debian 10 ou mais recente e Alpine 3.19 ou mais recente, com 4 GB ou mais de RAM. Android e iOS não estão nessa lista. O telefone também suspende os aplicativos e altera o endereço de rede constantemente, o que uma execução longa de um agente não pode tolerar. Execute-o em um servidor e use o telefone como tela.

A sessão continua ativa se eu fechar o aplicativo ou perder o sinal?

Sim, e duas partes separadas cuidam disso. O tmux mantém o processo em execução no servidor, portanto nada é encerrado quando a conexão termina. O mosh mantém a própria conexão ativa durante uma mudança de endereço, portanto mudar de Wi-Fi para dados móveis nem sequer exige uma nova conexão. Com SSH puro e sem tmux, uma conexão interrompida envia SIGHUP e o Claude Code para no meio da tarefa.

Por que o mosh conecta e depois não mostra nada?

Um login que é bem-sucedido e depois fica travado com Nothing received from server on UDP port 60001. significa que o cliente não consegue alcançar mosh-server nessa porta UDP, o que geralmente indica que um firewall está bloqueando UDP 60000 a 61000. Adicione o intervalo ao ufw e adicione-o novamente ao firewall de rede do provedor, que é um controle separado na maioria dos painéis. Se o mosh informar que mosh-server não foi encontrado, o servidor não tem o pacote instalado ou o login PATH não o inclui: instale-o com sudo apt install mosh ou use mosh --server=/usr/bin/mosh-server you@server.

Como interromper o Claude Code pelo teclado quando não há uma tecla Esc?

Adicione uma linha de teclas. O Termux configura uma com extra-keys em ~/.termux/termux.properties, e o Termius e o Blink já incluem uma linha que pode ser editada nas configurações. Esc interrompe uma resposta em execução e preserva o trabalho já realizado. Ctrl+C também interrompe, mas pressioná-lo duas vezes em um prompt ocioso encerra o Claude Code; por isso, use Esc primeiro.

É seguro o suficiente expor o SSH à Internet?

Com a autenticação por senha desativada, a única credencial que pode funcionar é uma chave que nunca sai dos seus dispositivos, o que representa um risco razoável para uma máquina que você pode recriar. Dê a cada dispositivo a sua própria chave para que a perda do telefone exija apenas uma linha em authorized_keys. Se preferir não responder em uma porta pública, coloque a máquina atrás do WireGuard e faça o sshd escutar no endereço do túnel.