Resposta rápida: a maioria dos erros do Claude Code no Windows tem uma de três causas: o comando não entrou no PATH (feche e reabra o terminal), o Node.js/npm está desatualizado ou ausente, ou houve falha de permissão na instalação. O primeiro diagnóstico é sempre rodar claude doctor, que aponta o que está errado no ambiente.
Se você instalou o Claude Code e algo não funcionou, este guia resolve os problemas mais comuns no Windows, um por um, com a causa e a solução.
A boa notícia: quase todos os erros são de ambiente (terminal, PATH, Node), não do Claude Code em si. Ou seja, dá para resolver rápido.
- Primeiro passo: feche e reabra o terminal, depois rode
claude doctor. - Erro mais comum: “claude não é reconhecido” — quase sempre é PATH.
- Segundo suspeito: Node.js/npm desatualizado ou ausente.
- Quando nada resolve: reinstalar do zero costuma limpar o problema.
Antes de tudo: rode claude doctor
O claude doctor é o diagnóstico oficial do Claude Code. Ele verifica a instalação, a versão e o ambiente, e aponta problemas.
claude doctor
Se o claude doctor nem roda porque o comando não é reconhecido, o problema é de PATH ou instalação — e é o primeiro caso abaixo. Para a lista completa de comandos, veja o guia do comando claude.
Erro: "claude não é reconhecido como comando"
Esse é o erro mais comum no Windows. O terminal responde algo como "claude não é reconhecido como um comando interno ou externo".
Causas e soluções, em ordem:
- Terminal aberto antes da instalação. A instalação só entra no PATH em terminais novos. Feche e reabra o PowerShell ou CMD.
- Instalação não concluiu. Rode a instalação de novo e confirme com
claude --version. - PATH não atualizado. Se instalou via npm, confirme que a pasta global do npm está no PATH do Windows.
Na maioria dos casos, só fechar e reabrir o terminal já resolve. Se você ainda não instalou ou quer refazer, veja o passo a passo em como instalar Claude Code no Windows.
Erro: Node.js ou npm desatualizado
Se você instalou pelo npm, o Claude Code precisa de uma versão recente do Node.js. Versões antigas causam erro na instalação ou na execução.
Como verificar:
node --version npm --version
Se o Node estiver muito antigo, atualize para uma versão LTS recente e reinstale o Claude Code. Se o comando node não for reconhecido, o Node.js não está instalado — instale primeiro e tente de novo.
node --version. É o check que resolve boa parte dos casos.
Erro: permissão na instalação (EACCES)
Ao instalar pelo npm, você pode ver erros de permissão, como EACCES ou "permission denied".
O que fazer:
- evite resolver com permissões elevadas de forma insegura;
- prefira o instalador oficial do Claude Code quando possível;
- se usar npm, ajuste as permissões da pasta global do npm conforme a documentação do Node.
Reinstalar pelo caminho oficial costuma eliminar esse tipo de erro de permissão de uma vez.
Erro: login ou autenticação falha
Depois de instalar, a primeira execução pede login. Se o navegador não abre ou o login não completa:
- confirme que você tem uma conta Claude válida (Pro ou Max) ou uma chave de API;
- tente rodar
claudede novo para reabrir o fluxo de login; - em rede corporativa, proxy ou firewall podem bloquear a autenticação.
Se o login por navegador não funcionar no seu ambiente, a autenticação por chave de API costuma ser a alternativa mais estável.
Erro: Git não encontrado
O Claude Code funciona no Windows nativo, mas alguns recursos, como o Bash tool, dependem do Git for Windows.
Se você vê avisos sobre Git ausente ou o Bash tool não funciona, instale o Git for Windows. Ele não é obrigatório para começar, mas habilita mais recursos e evita alguns avisos.
Erro: Claude Code lento ou travando
Se o Claude Code está lento ou travando no Windows:
- verifique se não é o antivírus escaneando cada operação de arquivo;
- em projetos muito grandes, tarefas complexas naturalmente demoram mais;
- confirme sua conexão, já que o agente depende de chamadas de rede.
Se você usa WSL, lembre que rodar em disco do Windows por dentro do WSL pode ficar lento. Para a maioria dos usuários Windows, começar nativo no PowerShell é mais simples e rápido.
Quando reinstalar do zero
Se você já tentou o básico e nada resolve, reinstalar costuma limpar o problema. O fluxo seguro é:
- rodar
claude doctorpara registrar o estado atual; - desinstalar a versão atual;
- reinstalar pelo caminho oficial, seguindo o guia de instalação no Windows;
- abrir um terminal novo e confirmar com
claude --version.
Se você é novo na ferramenta, vale também entender o que é o Claude e como usar antes de investir tempo na configuração.
Perguntas frequentes
Por que o comando claude não é reconhecido no Windows?
Quase sempre é PATH. A instalação só entra no PATH em terminais novos, então feche e reabra o PowerShell ou CMD. Se persistir, refaça a instalação e confirme com claude --version.
Como resolver erro de instalação do Claude Code?
Comece verificando o Node.js com node --version, porque versões antigas causam falhas. Prefira o instalador oficial para evitar erros de permissão do npm. Depois, abra um terminal novo e teste com claude doctor.
O Claude Code precisa de Node.js?
Se você instala pelo npm, sim, e em uma versão recente. Também existe o instalador oficial. Se o node --version mostrar uma versão antiga, atualize antes de reinstalar.
Como diagnosticar problemas no Claude Code?
Rode claude doctor. Ele verifica instalação, versão e ambiente e aponta o que está errado. É sempre o primeiro passo antes de reinstalar.
Preciso de WSL para rodar o Claude Code no Windows?
Não. O Claude Code funciona nativo no Windows com PowerShell ou CMD. O WSL é útil quando o projeto precisa de ambiente Linux, mas não é obrigatório para começar.