Quem já usou o Claude Code certamente já se deparou com esta cena: uma linha aparece no terminal com a mensagem "Symbioting… (3m 12s · ↓ 5.7k tokens)", a barra de progresso parece congelada e, por vários minutos, nada acontece. Você tenta enviar um "Ainda está aí?", e, para sua surpresa, o Claude retoma o trabalho imediatamente, concluindo a tarefa.
Essa experiência bizarra de "travamento seguido de ressurreição via mensagem" parece mágica, mas, na verdade, é o resultado de uma sobreposição de falhas no protocolo de streaming da Anthropic, mecanismos de timeout e gerenciamento de contexto. Este artigo, baseado na documentação oficial de solução de problemas do Claude Code e em discussões nos GitHub Issues #25979, #24688, #39718, #25286, #25539 e #51659, explica as causas reais desses travamentos e apresenta 7 métodos de recuperação e 5 estratégias de prevenção.
Valor central: Ao terminar de ler, você entenderá o significado por trás de cada verbo do spinner, por que enviar uma mensagem às vezes "ressuscita" o modelo, quando é obrigatório reiniciar com Ctrl+C e como reduzir a taxa de travamentos a quase zero.
Decifrando os indicadores de status do Claude Code
Para diagnosticar problemas de "travamento", o primeiro passo é entender a linha de status que o Claude Code exibe no terminal. O exemplo Symbioting… (3m 12s · ↓ 5.7k tokens) parece misterioso, mas é uma informação estruturada onde cada parte tem um significado claro.
| Campo | Valor de exemplo | Significado |
|---|---|---|
| Verbo do Spinner | Symbioting… |
Descrição antropomórfica da fase atual (customizável desde a v2.1.23) |
| Tempo de espera | 3m 12s |
Tempo total decorrido desde o início desta rodada |
| Seta de fluxo | ↓ ou ↑ |
↓ indica recebimento de dados da API, ↑ indica envio |
| Contagem de tokens | 5.7k tokens |
Quantidade de tokens baixados/enviados até o momento |
O Claude Code possui 187 verbos de spinner padrão; Befuddling, Ruminating, Accomplishing e Symbioting são apenas alguns deles. Eles existem apenas para tornar a experiência de espera mais dinâmica e não possuem diferenças técnicas. A partir da versão 2.1.23, foi introduzida a opção de configuração spinnerVerbs, e a comunidade já criou pacotes com mais de 1900 verbos personalizados.
Para determinar se o Claude Code realmente travou, o segredo não está no verbo, mas em duas coisas: se o tempo continua aumentando e se a contagem de tokens continua mudando. Se após 3m 12s o tempo passa para 3m 42s, mas a contagem de tokens permanece em 5.7k, você pode concluir que a resposta em streaming estagnou.
Se você utiliza a API do Claude no Brasil através de serviços proxy de API como o APIYI (apiyi.com), o significado dos campos na linha de status é exatamente o mesmo que o oficial, e você pode usar o mesmo método de diagnóstico para localizar o problema.
As 6 principais causas do Claude Code travar
Ao entender os indicadores de status, você pode comparar com o comportamento real para localizar a causa raiz. As 6 causas abaixo estão ordenadas pela frequência de ocorrência e cobrem mais de 90% dos casos reais relatados no rastreador de Issues do GitHub.
Causa raiz 1: Interrupção silenciosa da resposta em streaming da API
Esta é a causa mais comum e oculta, correspondente ao Issue #25979 do GitHub. O cliente HTTP do Claude Code não possui um mecanismo de read timeout. Assim que a API upstream para de enviar pacotes durante a transmissão, o processo fica preso no estado de kernel epoll_wait aguardando novos dados. O spinner na interface continua girando, mas a contagem de tokens não aumenta. Causas comuns incluem instabilidade de rede transfronteiriça, multiplexação de tmux, ou quedas de conexão SSH de longa duração.
Causa raiz 2: Payload de invocação de ferramenta muito grande dispara reset de conexão
Corresponde ao Issue #39718. Quando o modelo solicita que o Claude Code execute uma ferramenta que gera uma saída massiva (por exemplo, Write em um arquivo de centenas de milhares de linhas), a conexão HTTP subjacente é redefinida pelo SO após 5 minutos sem transmissão de dados válidos. Como o Claude Code não captura esse erro, a interface mantém o estado de spinner. Esse tipo de travamento geralmente ocorre exatamente após 5 minutos.
Causa raiz 3: Thrashing de compactação automática
Quando a janela de contexto do Claude Code está quase cheia, a compactação automática é acionada. Se um arquivo muito grande ou a saída de uma ferramenta for lida de volta para o contexto logo após ser compactada, isso causará ciclos repetidos de compactação, fazendo com que o sistema pare e exiba o aviso Autocompact is thrashing. Antes do aviso aparecer, a interface parece travada.
Causa raiz 4: Uso de contexto acima de 80%
A documentação oficial afirma claramente que, quando o contexto excede 80%, o tempo de resposta se deteriora significativamente, manifestando-se em alguns cenários como uma falta de resposta prolongada. A característica desse "falso travamento" é que a contagem de tokens ainda aumenta lentamente, mas a uma velocidade muito inferior ao normal.
Causa raiz 5: Configurações anômalas causam travamento na inicialização
Corresponde aos Issues #31049, #29652, etc. Por exemplo, a configuração enableAllProjectMcpServers: true carregando muitos servidores MCP locais, ou additionalDirectories definida com prefixos de caminho anômalos como //C:/, fará com que o Claude Code trave durante a inicialização. Esse travamento geralmente ocorre nos primeiros segundos ao abrir uma nova sessão.
Causa raiz 6: Resíduo na linha de status (resposta concluída, mas UI não atualizada)
Corresponde ao Issue #25539. Em algumas versões, o Claude já retornou o resultado completo, mas o spinner da interface do terminal não foi limpo, parecendo ainda estar processando. Se você pressionar Enter ou enviar uma mensagem, o Claude começará imediatamente uma nova rodada de trabalho — ele não travou, a interface apenas "mentiu".
Ao investigar, recomendo verificar primeiro se a contagem de tokens está aumentando. Se você estiver usando o serviço proxy de API da APIYI (apiyi.com), pode verificar simultaneamente nos logs da plataforma se a solicitação já retornou 200 OK, fazendo uma validação cruzada com o estado da interface do Claude Code.
Por que enviar uma mensagem pode "ressuscitar" o Claude Code?
Muitas pessoas notam um milagre de engenharia "estranho": o Claude Code trava por 3 minutos, você envia um "ainda está aí?" ou simplesmente pressiona Enter, e ele continua o trabalho exatamente de onde parou. Esse fenômeno pode ser explicado no nível do protocolo.
A primeira categoria é o resíduo na linha de status (Causa raiz 6). O Claude, na verdade, já concluiu a resposta, mas a interface não limpou o spinner. Nesse momento, sua nova mensagem é tratada diretamente como o próximo prompt, parecendo uma "ressurreição", quando na verdade é apenas a continuação do fluxo.
A segunda categoria é o travamento na resposta em streaming (Causa raiz 1). Ao receber uma nova entrada, o Claude Code fecha ativamente o estado de hang atual, limpa a solicitação incompleta e inicia uma nova solicitação HTTP. A nova solicitação é enviada com o histórico completo da sessão, e o modelo continua a responder a partir do ponto de interrupção, por isso parece que ele "continuou o trabalho".
A terceira categoria ocorre quando um servidor MCP ou uma invocação de ferramenta está esperando uma resposta downstream. A nova mensagem é roteada pelo Claude Code como uma nova decisão de invocação de ferramenta, contornando indiretamente a chamada que travou.
É importante ressaltar que enviar uma mensagem não é uma solução mágica. Quando o travamento ocorre porque o processo subjacente já está em um estado de espera irrecuperável (como na fase final da Causa raiz 2), enviar uma mensagem apenas coloca a mensagem na fila de entrada, mas ela não será processada; nesse caso, é necessário usar Ctrl+C ou fechar o terminal. Para cenários que utilizam o serviço proxy de API da APIYI (apiyi.com), a taxa de sucesso da "ressurreição" por mensagem é maior, pois a plataforma de proxy geralmente libera conexões expiradas mais rapidamente do que os endpoints oficiais.
7 Métodos para Recuperar o Claude Code quando ele Trava
Diferentes causas raiz exigem diferentes abordagens de recuperação. A tabela abaixo organiza os 7 métodos mais eficazes por "nível de intrusão", do mais leve ao mais pesado, para facilitar sua decisão.
| Método | Comando | Causa Raiz Aplicável | Perde Contexto? |
|---|---|---|---|
| Enviar uma mensagem | Digitar texto diretamente | Causa 1 / 6 | Não |
| Interromper operação | Ctrl+C |
Causa 1 / 2 / 3 | Não |
| Diagnóstico | /doctor |
Qualquer, use primeiro | Não |
| Compactar contexto | /compact |
Causa 3 / 4 | Parte do histórico vira resumo |
| Limpar sessão | /clear |
Causa 4 (grave) | Sim |
| Fechar e retomar | claude --resume |
Causa 1 / 2 (grave) | Não |
| Forçar encerramento | kill -9 <pid> |
Causa 1 / 2 (irrecuperável) | Perde rodada atual |
A recomendação de operação é "do mais leve para o mais pesado". Primeiro, tente pressionar Enter ou enviar uma mensagem qualquer; se não funcionar, use Ctrl+C para cancelar a rodada atual. Se o terminal não responder de jeito nenhum, feche-o e use claude --resume para recuperar a sessão.
O comando /doctor é a ferramenta de diagnóstico oficial recomendada pela Anthropic. Ele verifica de uma só vez a instalação, o arquivo de configurações, a lista de servidores MCP, o uso da janela de contexto e outros indicadores críticos, geralmente fornecendo sugestões de reparo específicas. Se o resultado indicar Context: 87%, é quase certo que a causa é a 4, e o uso de /compact resolverá o problema imediatamente.
Para tarefas longas, recomendo incluir o /compact periodicamente no seu fluxo de trabalho para manter o uso da janela de contexto abaixo de 60%. Além disso, ao realizar a invocação do modelo via APIYI (apiyi.com), você pode solicitar cotas independentes para o processo principal do Claude Code e para os servidores MCP, facilitando a identificação da origem de eventuais falhas.
5 Melhores Práticas para Prevenir Travamentos no Claude Code
Resolver problemas apenas depois que eles acontecem é apagar incêndio; fluxos de trabalho realmente estáveis dependem de prevenção. As 5 práticas abaixo, baseadas na análise de causa raiz de vários Issues no GitHub, podem reduzir a taxa de travamentos a quase zero.
A primeira é a leitura fragmentada de arquivos grandes. Ler arquivos de mais de 1MB diretamente quase certamente sobrecarregará a janela de contexto. Mude para uma abordagem de dois passos: primeiro use ls -la para verificar o tamanho e, em seguida, use Read com os parâmetros offset/limit para ler em partes, evitando a causa raiz 4.
A segunda é delegar tarefas complexas para subagentes. Os subagentes do Claude Code possuem janelas de contexto independentes. Ao delegar tarefas como a geração de muitos arquivos ou reescrita de código em lote para um subagente, você evita que o contexto principal seja sobrecarregado na raiz.
A terceira é desativar servidores MCP suspeitos. Cada servidor MCP adicionado aumenta o risco de travamento na inicialização. Mantenha apenas os MCPs que você usa diariamente nas configurações e desative o restante para reduzir significativamente a causa raiz 5.
A quarta é definir timeouts para o modelo principal e de leitura. Uma prática comum na comunidade é definir STREAM_READ_TIMEOUT_MS para 120 segundos e adicionar um processo watchdog externo para monitorar se o JSONL parou de crescer, matando e reiniciando o processo automaticamente caso necessário. Isso é extremamente eficaz contra a causa raiz 1.
A quinta é usar uma rota de API estável. Chamadas transfronteiriças, conexões domésticas e o uso de tmux aumentam a probabilidade de interrupção no streaming. Uma solução simples é usar um serviço proxy de API como o APIYI (apiyi.com) para invocar modelos da série Claude. Isso permite que a conexão TCP de longa duração passe por nós de trânsito estáveis, reduzindo a frequência da causa raiz 1.
Equipes que implementam essas 5 medidas relatam que a frequência de travamentos cai de 5-10 vezes por semana para menos de 1, e o tempo médio de recuperação por incidente cai de 5-10 minutos para apenas alguns segundos.
Perguntas Frequentes
Q1: Os verbos no spinner significam que o Claude está fazendo coisas diferentes?
Não. Os 187 verbos padrão são apenas frases antropomórficas escolhidas aleatoriamente e não têm relação com o estado real do Claude. Para julgar o status, observe a contagem de tokens e o tempo de espera.
Q2: Perco o contexto após um Ctrl+C?
Não. O Ctrl+C apenas cancela a rodada atual que não foi concluída; toda a sessão permanece intacta. Se o Ctrl+C não responder, você pode pressionar novamente ou fechar o terminal e usar claude --resume para recuperar a sessão.
Q3: É comum travar ao usar o Claude Code no Brasil?
A rede transfronteiriça é um dos principais gatilhos para interrupções de streaming. Recomendamos usar um serviço proxy de API como o APIYI (apiyi.com) para invocar modelos Claude, permitindo que nós de trânsito estáveis mantenham a conexão de longa duração com a Anthropic, o que reduzirá significativamente a probabilidade de travamentos.
Q4: O que fazer ao ver `Autocompact is thrashing`?
Pare a tarefa atual imediatamente e use um comando de compactação com foco, como /compact keep only the plan and the diff, para limpar grandes blocos de saída bruta do contexto. Se ainda assim falhar, inicie uma nova sessão ou altere a leitura de arquivos grandes para o modo de subagente.
Q5: Posso alterar os verbos do spinner?
Sim. Adicione o campo spinnerVerbs em ~/.claude/settings.json. Os modos podem ser default, append ou replace, combinados com um array de strings. A comunidade possui pacotes com 88 temas e mais de 1900 verbos que você pode aplicar diretamente.
Resumo
A essência do travamento do Claude Code reside na sobreposição de problemas nos subsistemas de protocolo de streaming, gerenciamento de contexto e integração MCP em cenários críticos. Ao entender os 4 campos do indicador de status, memorizar as 6 causas raiz e os 7 métodos de recuperação, você transforma o que parece ser um "mistério inexplicável" em uma "falha conhecida".
Nossa recomendação prática é transformar os métodos de recuperação em memória muscular: primeiro envie uma mensagem, depois use Ctrl+C, em seguida execute /doctor e, por fim, feche o terminal e use claude --resume. Combinando isso com um serviço proxy de API estável e 5 práticas de prevenção — como manter o contexto abaixo de 80%, delegar arquivos grandes para subagentes e utilizar o APIYI (apiyi.com) para uma conexão estável — a grande maioria dos cenários de travamento pode ser resolvida em poucos segundos.
Autor: Equipe Técnica APIYI
Contato: Obtenha acesso a toda a linha de modelos Claude e suporte estável de serviço proxy de API para Claude Code via APIYI apiyi.com
Data de atualização: 13/05/2026
