Erros ao instalar o Claude Code: como corrigir Node antigo, permissão do npm, WSL e login que não abre

Fala aí, beleza? Instalar o Claude Code é rápido até a hora em que não é 😅

O comando roda, o terminal cospe umas linhas, tu digita claude e recebe um command not found

Ou pior: abre, e trava num login que nunca volta do navegador

A boa notícia é que isso quase sempre quebra em quatro pontos previsíveis: Node antigo, permissão do npm, WSL misturando o Node do Windows com o do Linux, e o navegador do login

Cada um desses tem sintoma e correção documentados, então não é caso de reinstalar no chute e torcer

Se o que tu quer é o caminho limpo, tem o guia de instalação passo a passo aqui do blog

Este post aqui é socorro pós-instalação: tu já rodou o comando, deu ruim, e agora precisa descobrir QUAL camada quebrou

Antes de reinstalar: os comandos que dizem onde está o problema

Antes do como, o porquê: reinstalar por cima é o reflexo mais comum e o mais inútil

Se tu não sabe se quebrou o Node, a permissão, o PATH ou o WSL, a reinstalação repete exatamente o mesmo problema, só que 5 minutos depois

Então a sequência é essa:

1. Peça a versão instalada no terminal. Uma instalação funcionando imprime um número de versão no formato 2.1.211 (Claude Code). Se em vez disso vier command not found ou outro erro, o problema é de instalação/PATH e a seção lá embaixo é sua
2. Rode claude doctor a partir do shell. Ele imprime diagnósticos read-only de instalação e de configurações SEM iniciar uma sessão: saúde da instalação, erros de validação do arquivo de settings e avisos com sugestões de correção
3. Use /doctor dentro do Claude Code quando a sessão até abre, mas alguma coisa se comporta estranho. Mesmo diagnóstico, só que de dentro da sessão
4. No WSL, rode which npm e which node. Esses dois caminhos precisam começar em /usr/. Se aparecer /mnt/c/, tu descobriu o problema antes de mexer em qualquer coisa

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

claude doctor
which npm
which node

O erro comum deste passo: pular direto pro npm install de novo sem ler a saída do claude doctor

O diagnóstico é read-only, não custa nada, e ele já aponta erro de settings que tu não ia achar no olho

Um mapa rápido pra tu já saber pra onde rolar a página:

Node antigo: o aviso EBADENGINE que assusta mas não quebra a instalação

Sintoma: durante o npm install aparece um aviso EBADENGINE gritando na tela, e tu já assume que a instalação foi pro brejo

Causa: a partir da v2.1.198, o pacote npm do Claude Code exige Node.js 22 ou superior

Solução: em versão antiga do Node, o npm imprime o aviso EBADENGINE em vez de falhar

A instalação conclui e o claude ainda roda, porque o pacote baixa um binário nativo que não usa o teu Node.js em tempo de execução

Ou seja: o aviso é feio, mas por si só ele não é o motivo de nada estar quebrado

Se tu quer sair do aviso, atualiza o Node ou migra pra instalação nativa

Como prevenir: usa a instalação nativa desde o começo, já que a via npm está marcada como depreciada na documentação oficial de setup

Erro de permissão no npm: por que sudo piora e qual é a correção certa

Sintoma: a instalação global via npm morre com erro de permissão

Causa: pacote global tentando gravar em diretório de sistema, que o teu usuário não tem permissão de escrever

Aí vem o reflexo clássico do dev cansado: joga um sudo na frente e segue a vida

Tome cuidado! A documentação é explícita: NÃO use sudo npm install -g, porque isso pode levar a problemas de permissão e a riscos de segurança

Tu troca um erro de hoje por um diretório com dono errado que vai te morder daqui a duas semanas

Solução documentada: dar ao npm um diretório global que é TEU

mkdir ~/.npm-global
npm config set prefix ~/.npm-global

Depois disso, adiciona esse diretório ao teu PATH no arquivo de perfil do shell que tu usa, e abre um terminal novo

Sem esse último passo o pacote instala bonitinho e o terminal continua sem achar o comando (spoiler da seção de command not found mais pra frente)

Como prevenir: instalar pelo método nativo, que nem passa pelo diretório global do npm

WSL: quando o Linux está usando o npm e o Node do Windows

Essa é a mais confusa de todas, porque são DOIS sintomas diferentes no mesmo ambiente

E a raiz é sempre a mesma: tu está dentro do Linux, mas quem atende o comando é o binário do Windows

Sintoma 1: erro durante a instalação, sem motivo aparente

Causa: o WSL pode estar usando o npm do Windows

Correção: avisa o npm em qual sistema ele está antes de instalar, e instala sem sudo

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check

Essa correção é pra quem já está na via npm e quer destravar a instalação agora

Se tu preferir não passar pelo npm, o comando oficial de instalação nativa também vale pro WSL (é o mesmo de macOS e Linux, lá na seção de migração)

Sintoma 2: tu roda claude e leva um exec: node: not found

Mas peraí, o Node não estava instalado? Estava… o do Windows

Causa: o ambiente WSL pode estar usando uma instalação de Node.js do Windows

Diagnóstico: confirma com which npm e which node

Os dois têm que apontar pra caminhos Linux começando em /usr/, e não em /mnt/c/

Se apareceu /mnt/c/, achou

Correção: instala o Node pelo gerenciador de pacotes da tua distribuição Linux, ou via nvm

Como prevenir: a documentação sugere considerar rodar o Claude Code nativamente no Windows em vez de pelo WSL, por melhor desempenho de sistema de arquivos

Windows: erro de sintaxe no comando de instalação é shell errado, não comando errado

Sintoma: o comando de instalação devolve um erro esquisito ANTES mesmo de baixar qualquer coisa

Causa: tu colou o comando no shell errado, e o Windows tem dois com cara parecida

A própria documentação ensina a ler o erro:

• The token '&&' is not a valid statement separator significa que tu está no PowerShell e não no CMD
• 'irm' is not recognized as an internal or external command significa que tu está no CMD e não no PowerShell

E dá pra confirmar sem rodar nada: o prompt mostra PS C:\ no PowerShell, e C:\ sem o PS no CMD

legal né? 😀 o erro já te diz onde tu está

Solução: roda o comando no shell certo

Este aqui é o comando oficial de instalação nativa no Windows via prompt de comando (CMD):

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Tem as variantes install.cmd latest pra versão mais recente e install.cmd <numero-da-versao> pra uma versão específica

E se o erro for de outra natureza, tipo syntax error near unexpected token '<', um 403 ou outro erro de curl, a documentação manda direto pra página Troubleshoot installation, que casa cada erro com a correção e ainda lista métodos alternativos de instalação

Ah, e pra referência de ambiente: os requisitos listados pra Windows são Windows 10 ou superior (com WSL 1, WSL 2 ou Git for Windows), 4GB+ de RAM e conexão com a internet

Nada de PC da Nasa aqui 😛

claude: command not found depois de instalar

Sintoma: a instalação terminou sem erro nenhum, tu digita claude e o terminal jura que esse comando não existe

Causa mais comum: o PATH

A documentação aponta ele como a causa número um desse erro, então é por aí que tu começa: se o claude ainda não é encontrado depois da instalação, confere o teu PATH

E tem dois casos que confundem MUITO:

Extensão de IDE não é CLI. Instalar a extensão não coloca o claude no PATH do shell

A extensão embute uma cópia privada da CLI pro painel de chat, mas digitar claude no terminal exige a instalação da CLI standalone

Ou seja, funciona dentro do editor e não funciona no terminal, e isso não é bug

JetBrains achando que não existe. Se o claude estiver instalado num local que a IDE não encontra, dá pra definir o caminho completo na configuração Claude command do plugin

Como prevenir: valida sempre pela saída de versão, no formato 2.1.211 (Claude Code)

Se imprimiu versão, o binário está no lugar e acessível

Login que não abre o navegador (e o que fazer quando ele mostra um código)

Essa etapa engana porque a instalação já deu certo, então o cara acha que instalou errado

Não instalou: o que quebrou foi o caminho de volta entre navegador e terminal

Sintoma 1: no primeiro início, o Claude Code deveria abrir uma janela do navegador pro login… e não abre nada

Solução: aperta c pra copiar a URL de login pra área de transferência e cola no navegador na mão

Sintoma 2: o navegador abre, tu faz o sign in, e em vez de voltar pro terminal ele te mostra um código na tela

Solução: cola esse código no terminal, no prompt Paste code here if prompted

Causa: o navegador não consegue alcançar o servidor de callback local do Claude Code

Isso é comum em WSL2, em sessões SSH e em containers, ou seja, exatamente nos ambientes onde "localhost" não é o localhost que tu imagina

Sintoma 3: com AWS SSO, as abas do navegador abrem repetidamente, num loop sem fim

Solução: remove a configuração awsAuthRefresh do arquivo de settings

Isso costuma acontecer quando VPNs corporativas ou proxies de inspeção TLS interrompem o fluxo SSO no navegador (se tu está numa máquina da empresa, olha pra esse lado primeiro)

Instalou, abre, mas o Claude Code não encontra seus arquivos ou não roda comandos

Aqui mora a cauda dos problemas que parecem bug de uso e são de ambiente

Sintoma: a ferramenta Search, as menções @arquivo, agentes customizados ou skills customizadas simplesmente não acham arquivo nenhum

Causa: o ripgrep normalmente vem incluído com o Claude Code, mas o binário embutido pode não rodar no teu sistema

Solução: a orientação é instalar o pacote de ripgrep da tua plataforma e dizer ao Claude Code pra usar ele

Sintoma: no Windows nativo, os comandos de shell não se comportam como tu espera

Causa e leitura: Git for Windows é recomendado no Windows nativo pra que o Claude Code possa usar a ferramenta Bash

Se o Git for Windows não estiver instalado, o Claude Code usa o PowerShell como ferramenta de shell

O shell padrão é o bash, ou PowerShell no Windows quando o Bash não está disponível

E dá pra controlar isso na mão: CLAUDE_CODE_USE_POWERSHELL_TOOL=1 ativa o PowerShell e 0 desativa

Sair do npm depreciado: migrar a instalação sem desinstalar tudo

Se tu chegou até aqui remendando, esse é o passo de manutenção que resolve a raiz

A via npm está marcada como depreciada e a instalação nativa é o método recomendado, então migrar é o movimento certo (e não precisa desinstalar tudo antes):

1. Saiu de uma instalação global via npm? Roda claude migrate-installer pra mover pra instalação local
2. Quer ir pra nativa? Roda claude install pra migrar uma instalação npm existente
3. Instalando do zero em macOS, Linux ou WSL? Usa o comando oficial de instalação nativa
4. Instalando do zero no Windows? Usa o install.cmd pelo prompt de comando, com as variantes latest ou o número da versão específica
5. Fecha e abre o terminal, e confere a saída de versão no formato 2.1.211 (Claude Code)

curl -fsSL https://claude.ai/install.sh | bash

O erro comum deste passo: manter duas instalações convivendo e continuar chamando a antiga pelo PATH

Tu migra, jura que está na nativa, e o terminal segue resolvendo o binário velho porque ele aparece primeiro na ordem do PATH… aí o comportamento estranho volta e ninguém entende 😅

Conclusão

Recapitulando o que dá pra tirar daqui: a maioria dos erros ao instalar Claude Code é de AMBIENTE, não do programa

Versão de Node, permissão de diretório, qual sistema está sendo usado por baixo no WSL, PATH e o caminho de volta do login

O programa em si costuma estar bem, quem está fora do lugar é a máquina embaixo dele

Então o próximo passo concreto é curto: roda claude doctor, confere a saída de versão, e se tu ainda está na via npm depreciada, migra pra instalação nativa com claude install

Com o ambiente redondo, o assunto passa a ser o que realmente importa, que é tirar resultado da ferramenta: dá uma olhada nas técnicas de prompt que funcionam pra não cair no modo 100% vibe coder

Se apareceu um erro que não está aqui, olha primeiro a saída do diagnóstico antes de reinstalar, quase sempre ela já entrega o culpado

até o próximo post! =)