Solução de problemas de desconexão remota no Claude Code: sintomas, critérios e soluções para seis tipos de queda

Executar o Claude Code remotamente, o pior não é não conseguir conectar, mas sim conectar e depois cair — e cada vez a queda tem um motivo diferente.

A palavra "desconexão" na verdade cobre seis falhas completamente diferentes. Cada uma tem sintomas característicos e soluções independentes — tratar uma conexão de longa duração derrubada pela troca de rede como se fosse suspensão da máquina não adianta nada; desativar a hibernação não resolve. Tratar uma conexão semi-morta como se fosse rede ruim e ficar esperando também não adianta; ela não se recupera sozinha, nem de manhã.

Este artigo parte do que você realmente observa para chegar à causa: para cada tipo de desconexão, apresentamos os sintomas, como confirmar o diagnóstico e a solução correspondente. Se quiser ir direto à ação, pule para a lista de verificação na última seção.

Este artigo aborda apenas solução de problemas de desconexão. Para saber como montar o acesso remoto, veja Acesso remoto ao Claude Code: controle a sessão de qualquer lugar sem o computador local. Para o uso no celular, veja Claude Code no celular: visualize sessões e aprove ferramentas no iOS a qualquer momento.

Primeiro, identifique os sintomas: qual deles você está vendo

A conexão remota tem dois lados: a máquina de desenvolvimento que executa o Claude Code ←→ o dispositivo de visualização na sua mão. Qualquer problema em um dos dois lados se manifesta como "caiu", mas os sintomas são diferentes:

O que você observa	Provável causa	Ir para
A sessão congela de repente; ao reconectar, o progresso continua parado naquele momento	Suspensão / bloqueio de tela da máquina de desenvolvimento	§1
Cai no momento em que você entra no elevador, troca para 4G ou muda de WiFi	Conexão de longa duração interrompida	§2
Ao fechar o terminal local, ou ao suspender a máquina local, a conexão remota cai imediatamente	Limitação do esquema de espelhamento de tela	§3
Mostra online, mas as mensagens desaparecem sem deixar rastro e sem nenhum erro	Conexão semi-morta	§4
Reconecta, mas a sessão está vazia / as mensagens do período de queda sumiram	A reconexão não retomou a sessão original	§5
Ao conectar depois de horas, a sessão não existe mais	Processo reciclado, sem recuperação a frio	§6

A mais fácil de diagnosticar errado é a quarta: ela não gera erros. O status da conexão está verde, as mensagens são enviadas, mas nunca há resposta — é mais difícil de investigar do que uma queda direta, porque todos os indicadores dizem que "está tudo normal".

1. Suspensão / bloqueio de tela / tampa fechada da máquina de desenvolvimento

Sintomas: a sessão congela completamente em determinado momento. Ao reconectar, o progresso continua parado no instante da queda, sem avançar nenhum passo.

Por quê: muita gente acha que "minha máquina de desenvolvimento está sempre ligada", mas a suspensão do sistema, a suspensão ao fechar a tampa e o bloqueio programado de tela suspendem ou matam o processo do Claude Code. No dispositivo de visualização, o que se vê é "parou de repente".

Como confirmar: volte à máquina de desenvolvimento e verifique se o processo ainda existe e se há registros de suspensão nos logs do sistema. Se o processo continua lá, mas o timestamp está parado no momento da queda, é isso.

Solução: configure o plano de energia da máquina de desenvolvimento como "nunca suspender / não suspender ao fechar a tampa". Essa é a única correção definitiva — nenhuma solução remota consegue salvar uma máquina que já dormiu.

2. Conexão de longa duração interrompida pela troca de rede

Sintomas: a queda ocorre em um instante bem definido — ao entrar no elevador, ao trocar de WiFi para 4G, ou quando a banda larga de casa refaz a conexão no meio da noite.

Por quê: a sincronização remota em tempo real depende de uma conexão de longa duração (WebSocket / SSH). Quando o IP muda, essa conexão é invalidada na hora, sem negociação possível.

Como confirmar: se o momento da queda coincide com o momento em que você trocou de rede, é isso.

Solução: esse tipo não tem como evitar; só é possível mitigar com reconexão automática + backoff (1s→2s→5s…, evitando tentativas agressivas logo após a queda). SSH puro não tem essa capacidade — se caiu, caiu, e é preciso reconectar manualmente. Esse é um requisito obrigatório na escolha da solução.

3. Esquema de espelhamento de tela: a máquina local precisa ficar aberta em primeiro plano

Sintomas: ao fechar o terminal da máquina local, ou ao suspender a máquina local, o celular imediatamente cai junto. Não é um timeout gradual; é a sincronização que se perde.

Por quê: o Remote Control oficial da Anthropic projeta a sessão que está rodando na sua máquina local para o celular/navegador. O pré-requisito é que o Claude Code local fique aberto em primeiro plano e a máquina local continue online. Quando a máquina local cai, o lado remoto não tem um ciclo de vida independente ao qual se agarrar.

Como confirmar: feche a janela do terminal local e veja se a conexão remota cai no mesmo segundo. Se cair, você está usando um esquema de espelhamento de tela.

Solução: migre para uma arquitetura com serviço daemon residente na máquina de desenvolvimento — o lado que executa a sessão vira um serviço de fundo com inicialização automática, que vive independentemente do seu dispositivo de visualização. Mesmo que o dispositivo de visualização seja fechado, trocado ou caia, ele continua rodando normalmente na máquina de desenvolvimento. Essa é a diferença essencial entre "espelhamento de tela" e "serviço residente" — não é algo que se resolve ajustando parâmetros.

4. Conexão semi-morta (half-open): a mais difícil de detectar

Sintomas: mostra online, mas as mensagens não têm resposta e também não há erros. Pode ficar travado por alguns minutos, ou até você reconectar manualmente.

Por quê: quando a rede é interrompida silenciosamente (timeout de entradas NAT, dispositivos intermediários perdendo estado, ou sinal fraco a ponto de só perder pacotes sem derrubar a conexão), os dois lados do TCP podem achar que ainda estão conectados, mas os dados não passam mais. Sem heartbeat, os dois lados mantêm essa ilusão indefinidamente.

Como confirmar: o status da conexão mostra normal, mas as mensagens enviadas não têm confirmação de entrega nem erros; ao desconectar e reconectar manualmente, tudo volta na hora — é isso.

Solução: a conexão precisa ter heartbeat (keepalive ping): se nenhuma resposta do outro lado chegar dentro do prazo estipulado, considere que é uma conexão semi-morta e reconecte proativamente, em vez de ficar esperando. O critério deve ser "não recebeu resposta", não "não houve erro" — conexões semi-mortas nunca geram erros.

5. A reconexão não retoma a sessão original / mensagens perdidas

Sintomas: após a queda, é possível reconectar, mas ao voltar a sessão está vazia ou as mensagens enviadas durante a queda desapareceram.

Por quê: a reconexão apenas cria uma nova conexão, sem assinar de volta a sessão original; as mensagens do período de queda também não ficaram em cache para você.

Como confirmar: após reconectar, o ID da sessão mudou ou o histórico só começa a partir do momento da reconexão.

Solução: escolha uma solução que reassine automaticamente a sessão original após a reconexão e reproduza o histórico do período de queda. Reconectar sem retomar a sessão é o mesmo que não ter reconectado.

6. Processo da sessão reciclado, sem recuperação a frio

Sintomas: desconexões curtas e reconexões funcionam normalmente, mas ao voltar depois de algumas horas, a sessão não existe mais.

Por quê: o processo da sessão pode ser reciclado depois de ficar muito tempo ocioso, e o próprio daemon pode ter sido reiniciado (atualização ou reinicialização após falha). O estado da sessão na memória desaparece junto.

Como confirmar: só ocorre com quedas longas; quedas curtas não reproduzem o problema.

Solução: é necessária a capacidade de recuperação a frio — o estado da sessão é persistido em disco e, mesmo que o processo desapareça, o contexto pode ser restaurado do disco. No cenário ideal, você envia uma mensagem e ele se recupera automaticamente, sem que você perceba.

Lista de verificação (aplicável a qualquer solução)

Percorra na ordem; cada etapa pode ser verificada de forma independente:

1. A máquina que executa a sessão suspendeu / bloqueou a tela? → Desative a suspensão automática e a suspensão ao fechar a tampa. (§1)
2. O momento da queda coincide com o momento da troca de rede? → É necessária uma solução com reconexão automática + backoff; não conte com SSH puro. (§2)
3. Ao fechar o terminal local, a conexão remota cai imediatamente? → É a limitação do esquema de espelhamento de tela; é preciso migrar para uma arquitetura com daemon residente. (§3)
4. Está travado em "mostra online, mas as mensagens não têm resposta"? → Conexão semi-morta; só a detecção por heartbeat consegue recuperar automaticamente. (§4)
5. Após reconectar, a sessão está vazia / faltam mensagens? → É preciso "retomar a sessão original + reprodução do histórico". (§5)
6. Só perde a sessão quando a queda é longa? → É preciso persistência em disco + recuperação a frio. (§6)

Aplicando a uma solução concreta

Das seis situações acima, apenas a nº 1 é um problema de configuração da sua própria máquina; as outras cinco são todas determinadas pela arquitetura — ficam definidas na escolha da solução, e nenhum ajuste de parâmetros resolve depois que o problema aparece.

Uma solução remota sem quedas precisa ter, simultaneamente: daemon residente na máquina de desenvolvimento (cobrindo o risco residual do §1 e o §3), reconexão automática + backoff (§2), detecção por heartbeat (§4), reconexão retomando a sessão original + reprodução do histórico (§5) e persistência em disco com recuperação a frio (§6).

O conjunto PandaNpc + pandapaw foi construído seguindo esses seis pontos, um a um: o pandapaw é registrado na máquina de desenvolvimento como um daemon residente com inicialização automática (não é uma janela de terminal que você precisa manter aberta; se cair, ele é reiniciado automaticamente); o dispositivo de visualização reconecta automaticamente com backoff após a queda; a conexão roda heartbeat e, se não houver resposta, é diagnosticada como semi-morta e reconecta proativamente; após a reconexão, reassina automaticamente a sessão original e reproduz o histórico do período de queda; mesmo que o processo da sessão seja reciclado, basta enviar uma mensagem para que ele se recupere a frio a partir do disco e continue.

Para detalhes de instalação e conexão, veja Acesso remoto ao Claude Code; para visualização de sessões e aprovação de ferramentas no celular, veja Claude Code no celular.

Uma armadilha extra: cuidado com a cobrança ao rodar remotamente

Ao investigar desconexões, é fácil trocar para claude -p (modo headless), mas a partir de 15 de junho de 2026 a Anthropic mudou a cobrança — o modo headless não usa mais a cota da assinatura; ele consome um pequeno crédito mensal de SDK e, quando acaba, passa a ser cobrado por API. Uso intenso estoura facilmente o limite. O modo interativo (claude REPL) continua usando a cota da assinatura. Ao trocar de solução para investigar desconexões, cuidado para não trocar também o modelo de cobrança sem perceber.