Como usar o Claude Code no telemóvel via SSH

Claude Code no telemóvel: como funciona na prática

O Claude Code no telemóvel não é uma aplicação móvel. O Claude Code é executado num VPS (servidor privado virtual), dentro de uma sessão tmux que permanece aberta, e o telemóvel abre uma ligação SSH (secure shell) a essa sessão enquanto a consulta. Se fechar a aplicação, o agente continua a trabalhar, porque o processo nunca foi executado no telemóvel.

Essa separação é a base de todo o desenho. Um sistema operativo móvel suspende uma aplicação alguns segundos depois de mudar para outra, pelo que qualquer tarefa longa iniciada no telemóvel é interrompida. O telemóvel também recebe um novo endereço de rede sempre que muda de wifi para dados móveis. Os dois problemas desaparecem quando o processo é executado num servidor e o telemóvel apenas mostra o ecrã.

No servidor, precisa de quatro componentes: tmux para manter a sessão, chaves SSH para aceder ao servidor, mosh para lidar com alterações de rede e o próprio Claude Code. No telemóvel, precisa apenas de uma aplicação de terminal com uma linha de teclas de acesso rápido.

O que é necessário no VPS

Um servidor Ubuntu 24.04 pequeno é suficiente para as partes sobre SSH e tmux. O Claude Code exige mais recursos. Os requisitos oficiais em julho de 2026 são Ubuntu 20.04 ou mais recente num processador x64 ou ARM64, com 4 GB ou mais de RAM. Um plano de 1 GB instala o programa, mas, sob carga, o kernel termina o processo. O Claude Code também exige uma conta Claude paga (Pro, Max, Team ou Enterprise) ou uma conta Console com acesso à API, porque o plano gratuito Claude.ai não o inclui.

Configure o servidor com um utilizador normal com sudo, não como root. Se o servidor for novo, siga primeiro os primeiros dez minutos num VPS novo, porque as alterações de SSH apresentadas mais à frente neste guia são mais simples depois de o utilizador e a firewall existirem.

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 imprime uma linha semelhante a 2.1.211 (Claude Code). Se imprimir command not found, esse diretório ainda não está no seu PATH: termine a sessão, inicie-a novamente e confirme com command -v claude. claude doctor imprime diagnósticos da instalação e das definições sem iniciar uma sessão.

Inicie sessão uma vez agora, a partir de um portátil, antes de depender do telefone. Execute claude num diretório de projeto e siga o pedido de início de sessão. O processo pede que abra um URL num navegador e devolva um código ao terminal. Alternar entre duas aplicações num ecrã de telefone para fazer isso é lento. Faça-o uma vez com um teclado físico. As credenciais ficam 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 final 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 sessão se ela não existir. Assim, um comando cobre os dois casos. exec substitui o shell de login pelo tmux. Por isso, sair do tmux fecha a ligação em vez de deixar um prompt vazio. Quando precisar de um shell normal, ignore o ficheiro: ssh you@server -t "bash --noprofile".

Coloque isto em ~/.profile, e não em ~/.bashrc. ~/.bashrc também é executado em sessões não interativas. Por isso, as transferências de ficheiros falham: scp e sftp interpretam a saída inesperada como dados do protocolo e falham com Received message too long. ~/.profile é executado apenas em shells de login, que é o caso de uma sessão SSH interativa.

~/.profile também é o local onde o Ubuntu adiciona ~/.local/bin a PATH. Se claude funcionar logo depois do login, mas um shell dentro do tmux indicar command not found, essa ordenação é a causa. Nesse caso, inicie o tmux a partir de um 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 bloqueia quando saio do Wi-Fi e o que o mosh corrige?

Uma ligação SSH é uma ligação TCP (transmission control protocol), e uma ligação TCP é identificada pelos dois endereços e pelas duas portas. Ao sair do alcance do Wi-Fi, o telefone recebe um novo endereço da rede móvel, por isso a ligação antiga deixa de corresponder a qualquer extremo. Nada sinaliza essa alteração. O terminal simplesmente deixa de responder até o TCP desistir; depois, o ssh apresenta client_loop: send disconnect: Broken pipe. Para terminar imediatamente uma sessão bloqueada, prima Enter, depois ~ e depois ..

O mosh (mobile shell) elimina esse modo de falha. Usa o SSH uma vez para iniciar sessão e arrancar um processo mosh-server, lê a porta UDP (user datagram protocol) escolhida pelo servidor e fecha a ligação SSH. Depois disso, os dois lados trocam datagramas UDP autenticados com uma chave de sessão partilhada. Assim, a sessão é identificada por essa chave, e não pelo seu endereço. Um novo endereço apenas permite continuar a sessão. O mosh também apresenta localmente o que escreve e redesenha o ecrã quando o servidor discorda. Por isso, continua utilizável numa ligação móvel lenta.

O mosh usa uma porta UDP entre 60000 e 61000. Abra esse intervalo:

sudo ufw allow 60000:61000/udp
sudo ufw status

Abrir portas com ufw explica o restante da configuração da firewall. Se o seu fornecedor disponibilizar uma firewall de rede separada no painel de controlo, adicione também esse intervalo aí. Uma regra do ufw não pode afetar um filtro colocado à frente da máquina.

São comuns duas falhas do mosh. Se o início de sessão for bem-sucedido e depois ficar bloqueado, apresentando Nothing received from server on UDP port 60001., o intervalo UDP está bloqueado em algum ponto entre o telefone e o servidor. Se a ligação indicar que mosh-server não foi encontrado, o pacote está em falta no servidor ou não está presente no PATH de início de sessão. Instale-o ou indique-o diretamente com mosh --server=/usr/bin/mosh-server you@server.

O mosh também recusa iniciar quando a localidade do início de sessão não usa UTF-8, e apresenta a mensagem: mosh-server needs a UTF-8 native locale to run. Corrija a localidade no servidor, não no telefone.

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

O mosh não faz duas coisas. O README indica que o mosh não suporta o encaminhamento X nem os usos não interativos do SSH, incluindo o encaminhamento de portas. Por isso, para pré-visualizar uma aplicação Web que o Claude Code acabou de iniciar, continua a ser necessário usar o ssh -L 8080:127.0.0.1:8080 you@server normal. O mosh também sincroniza apenas o ecrã visível, por isso não tem histórico de deslocamento próprio. Essa segunda limitação não tem impacto neste caso, porque o tmux mantém o histórico: Ctrl-b e depois [ ativa o modo de cópia; arrastar ou usar as teclas de seta permite deslocar o conteúdo; q sai desse modo.

Torne o ecrã do telemóvel utilizável

Quatro linhas em ~/.tmux.conf no servidor fazem quase todo o 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 gesto de arrastar no toque num deslocamento e um toque numa seleção de painel ou janela. Isto substitui a maior parte das teclas de prefixo difíceis de escrever. status-position top move a linha de estado do tmux para fora da margem inferior, onde o teclado no ecrã e a respetiva barra de sugestões a tapam. default-terminal é importante porque, caso contrário, o tmux anuncia um terminal screen ao Claude Code, e as cores e os caracteres de desenho de caixas ficam piores do que o necessário. Se o tmux depois se recusar a iniciar com missing or unsuitable terminal: tmux-256color, falta a entrada terminfo: sudo apt install ncurses-term.

Aprenda quatro teclas. O resto torna-se confortável.

• Esc interrompe o Claude a meio da resposta e mantém o trabalho já concluído. É a tecla que deve ficar mais próxima do polegar.
• Ctrl+C também interrompe uma operação em execução. Numa linha de comandos sem atividade, o primeiro toque limpa a entrada e o segundo sai do Claude Code. É, portanto, a opção mais brusca.
• Esc duas vezes limpa um rascunho de pedido. Numa linha de comandos vazia, abre o menu de retrocesso.
• Para um pedido com várias linhas, escreva \ e prima Enter. Esta forma funciona em qualquer terminal. Shift+Enter é suportado nativamente apenas por uma lista curta de terminais de desktop, e os clientes móveis não fazem parte dela.

Evite painéis divididos. Um telemóvel na orientação vertical tem cerca de 40 colunas de largura. Uma divisão vertical deixa 20 colunas por painel, e cada diff fica dividido em várias linhas sem legibilidade. Use janelas do tmux: Ctrl-b c cria uma e Ctrl-b n muda para a seguinte. Se uma segunda janela acabar por ter a sua própria sessão do Claude Code, as duas sessões podem trocar trabalho diretamente em vez de copiar texto entre janelas num ecrã tátil. Rode o telemóvel para a orientação horizontal quando precisar de ler um diff corretamente.

A quantidade de texto apresentada nessa janela deve ser definida deliberadamente, porque um estilo de saída edita o prompt do sistema por trás de cada resposta e um estilo mais conciso significa menos ecrãs para percorrer num telemóvel.

Uma sessão longa num ecrã pequeno é sobretudo um problema de contexto. Por isso, vale a pena ler gerir a janela de contexto do Claude Code antes de tentar trabalhar um dia inteiro a partir de um comboio.

Bloqueie o acesso: apenas chaves, sem palavras-passe

O telefone agora tem uma chave para uma máquina que edita o seu código e executa comandos. Desative a autenticação por palavra-passe. Um ficheiro 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 é usado o primeiro valor encontrado para uma definição.

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

sshd -t analisa a configuração e não imprime nada quando ela é válida. Se ignorar este passo, um erro de digitação faz com que sshd falhe ao recarregar. Mantenha a sessão de trabalho aberta e teste a partir de uma segunda ligação antes de fechar qualquer sessão, porque uma chave incorreta agora dá-lhe Permission denied (publickey). e, com as palavras-passe desativadas, não há alternativa. Nesse ponto, o caminho de recuperação é a consola do seu fornecedor. Se essa ligação de teste falhar, volte a ligar-se com ssh -v e corrija o problema enquanto a primeira sessão ainda está aberta, porque essa única mensagem de erro abrange cinco falhas distintas e o output detalhado indica qual delas ocorreu.

Dê a cada dispositivo a sua própria chave. Se perder o telefone, basta apagar uma linha de ~/.ssh/authorized_keys e o portátil continua a funcionar. Uma chave partilhada significa alterar a chave em todos os dispositivos que possui.

Se mudar o SSH para outra porta no Ubuntu 24.04, tenha em atenção que o listener pertence a ssh.socket, por isso uma linha Port isolada não altera nada. Execute sudo systemctl edit ssh.socket, limpe o valor predefinido com um ListenStream= vazio e defina a sua porta na linha seguinte. Proteção do SSH num VPS aborda este tema e o restante da superfície de ataque.

fail2ban para SSH acrescenta pouca segurança quando as palavras-passe estão desativadas, porque uma palavra-passe adivinhada nunca pode ser aceite. O que acrescenta são logs mais silenciosos, o que facilita identificar uma tentativa de início de sessão real.

A opção mais segura é manter o SSH fora da internet pública. Coloque o servidor atrás de uma VPN WireGuard alojada por si, ative o túnel no telefone quando necessário e atribua ao sshd um ListenAddress apenas no túnel. O mosh funciona através do túnel porque ambos os lados usam UDP. Há uma ressalva: o túnel acrescenta overhead aos pacotes. Se as transferências grandes ficarem bloqueadas, reduza o MTU (maximum transmission unit) na configuração WireGuard do telefone.

Há um último ponto sobre trabalhar desta forma. Num telefone, aprova pedidos de permissão num ecrã que mostra apenas algumas linhas do diff de cada vez. Isto é uma razão para manter as salvaguardas, não para as desativar. Verifique também em que modo de permissões as suas sessões iniciam, porque o modo automático passa a ser o predefinido do Claude Code em 14 August 2026 e aplica edições a ficheiros sem parar para lhe pedir confirmação. Executar o Claude Code com segurança num VPS aborda os limites de utilizador e diretório que deve definir antes de o seu principal ponto de acesso passar a ser um ecrã tátil.

Ao voltar a ligar-se e encontrar um problema

tmux attach a apresentar no server running on /tmp/tmux-1000/default significa que o servidor tmux terminou. Isto quase sempre significa que a máquina foi reiniciada. Confirme com uptime. As atualizações de segurança automáticas de atualizações de segurança automáticas reiniciam o sistema, e um sistema reiniciado não tem uma sessão tmux. Por isso, trate qualquer execução do Claude Code como algo que pode ser reiniciado.

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

Se se ligar e encontrar uma prompt de shell normal onde estava o Claude Code, o processo terminou sem a sessão terminar. Consulte dmesg -T | tail para encontrar uma linha como Out of memory: Killed process 4821 (claude). É isso que uma máquina abaixo do requisito de 4 GB faz durante uma edição grande. A ausência dessa linha significa que o Claude Code terminou por si próprio. O scrollback da shell acima da prompt contém o motivo.

Uma janela que volta com dimensões muito pequenas e espaço vazio à volta significa que dois clientes estão ligados com dimensões diferentes, porque o tmux dimensiona a janela para caber no cliente ligado mais pequeno. O portátil ainda mantém a sessão com 200 colunas de largura, enquanto o telefone pede 40. Desligue os outros clientes ao ligar-se: tmux attach -d -t claude.

FAQ

Posso executar o Claude Code no próprio telefone em vez de o executar num VPS?

Não. As plataformas suportadas em julho 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 fazem parte dessa lista. Um telefone também suspende as aplicações e altera constantemente o endereço de rede, algo que uma execução longa de um agente não tolera. Execute-o num servidor e use o telefone como ecrã.

A sessão continua ativa se eu fechar a aplicação ou perder o sinal?

Sim, e duas componentes distintas tratam disso. O tmux mantém o processo em execução no servidor, por isso nada termina quando a ligação é interrompida. O mosh mantém a própria ligação ativa durante uma alteração de endereço, por isso mudar de wifi para dados móveis nem sequer exige uma nova ligação. Com SSH simples e sem tmux, uma ligação interrompida envia SIGHUP e o Claude Code para a meio da tarefa.

Porque é que o mosh liga e depois não mostra nada?

Uma sessão de login que é estabelecida e depois fica bloqueada com Nothing received from server on UDP port 60001. significa que o UDP 60000 a 61000 não está aberto. Adicione o intervalo ao ufw e adicione-o novamente à firewall de rede do seu fornecedor, que é um controlo separado na maioria dos painéis. Se o mosh indicar que mosh-server não foi encontrado, falta o pacote no servidor: sudo apt install mosh.

Como posso interromper o Claude Code com um teclado sem tecla Esc?

Adicione uma linha de teclas. O Termux configura uma com extra-keys em ~/.termux/termux.properties, e o Termius e o Blink incluem uma linha que pode editar nas definições. Esc interrompe uma resposta em execução e mantém o trabalho já concluído. Ctrl+C também interrompe, mas premir essa tecla duas vezes numa linha de comandos inativa encerra o Claude Code, por isso use primeiro Esc.

É suficientemente seguro expor o SSH à Internet?

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