​
Problemas comuns de instalação

​
Problemas de instalação no Windows: erros no WSL

Você pode encontrar os seguintes problemas no WSL:

Problemas de detecção de SO/plataforma: Se você receber um erro durante a instalação, o WSL pode estar usando o npm do Windows. Tente:

  • Execute npm config set os linux antes da instalação
  • Instale com npm install -g @anthropic-ai/claude-code --force --no-os-check (NÃO use sudo)

Erros de Node não encontrado: Se você ver exec: node: not found ao executar claude, seu ambiente WSL pode estar usando uma instalação do Node.js do Windows. Você pode confirmar isso com which npm e which node, que devem apontar para caminhos do Linux começando com /usr/ em vez de /mnt/c/. Para corrigir isso, tente instalar o Node através do gerenciador de pacotes da sua distribuição Linux ou via nvm.

​
Problemas de instalação no Linux e Mac: erros de permissão ou comando não encontrado

Ao instalar o Claude Code com npm, problemas de PATH podem impedir o acesso ao claude. Você também pode encontrar erros de permissão se seu prefixo global do npm não for gravável pelo usuário (ex. /usr, ou /usr/local).

​
Solução recomendada: Instalação nativa do Claude Code

O Claude Code tem uma instalação nativa que não depende do npm ou Node.js.

O instalador nativo do Claude Code está atualmente em beta.

Use o seguinte comando para executar o instalador nativo.

macOS, Linux, WSL:

# Instalar versão estável (padrão)
curl -fsSL https://claude.ai/install.sh | bash

# Instalar versão mais recente
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Instalar número de versão específico
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

# Instalar versão estável (padrão)
irm https://claude.ai/install.ps1 | iex

# Instalar versão mais recente
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Instalar número de versão específico
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Este comando instala a compilação apropriada do Claude Code para seu sistema operacional e arquitetura e adiciona um link simbólico para a instalação em ~/.local/bin/claude.

Certifique-se de que você tem o diretório de instalação no seu PATH do sistema.

​
Solução alternativa: Migrar para instalação local

Alternativamente, se o Claude Code executar, você pode migrar para uma instalação local:

claude migrate-installer

Isso move o Claude Code para ~/.claude/local/ e configura um alias na sua configuração de shell. Nenhum sudo é necessário para atualizações futuras.

Após a migração, reinicie seu shell e então verifique sua instalação:

No macOS/Linux/WSL:

which claude  # Deve mostrar um alias para ~/.claude/local/claude

No Windows:

where claude  # Deve mostrar o caminho para o executável claude

Verificar instalação:

claude doctor # Verificar saúde da instalação

​
Permissões e autenticação

​
Solicitações de permissão repetidas

Se você se encontra aprovando repetidamente os mesmos comandos, você pode permitir que ferramentas específicas executem sem aprovação usando o comando /permissions. Veja documentação de Permissões.

​
Problemas de autenticação

Se você está enfrentando problemas de autenticação:

  1. Execute /logout para sair completamente
  2. Feche o Claude Code
  3. Reinicie com claude e complete o processo de autenticação novamente

Se os problemas persistirem, tente:

rm -rf ~/.config/claude-code/auth.json
claude

Isso remove suas informações de autenticação armazenadas e força um login limpo.

​
Performance e estabilidade

​
Alto uso de CPU ou memória

O Claude Code é projetado para funcionar com a maioria dos ambientes de desenvolvimento, mas pode consumir recursos significativos ao processar bases de código grandes. Se você está enfrentando problemas de performance:

  1. Use /compact regularmente para reduzir o tamanho do contexto
  2. Feche e reinicie o Claude Code entre tarefas principais
  3. Considere adicionar diretórios de build grandes ao seu arquivo .gitignore

​
Comando trava ou congela

Se o Claude Code parecer não responsivo:

  1. Pressione Ctrl+C para tentar cancelar a operação atual
  2. Se não responsivo, você pode precisar fechar o terminal e reiniciar

​
Tecla ESC não funciona em terminais JetBrains (IntelliJ, PyCharm, etc.)

Se você está usando o Claude Code em terminais JetBrains e a tecla ESC não interrompe o agente como esperado, isso provavelmente é devido a um conflito de atalho de teclado com os atalhos padrão do JetBrains.

Para corrigir este problema:

  1. Vá para Configurações → Ferramentas → Terminal
  2. Clique no hiperlink “Configure terminal keybindings” próximo a “Override IDE Shortcuts”
  3. Dentro dos atalhos de teclado do terminal, role para baixo até “Switch focus to Editor” e delete esse atalho

Isso permitirá que a tecla ESC funcione adequadamente para cancelar operações do Claude Code em vez de ser capturada pela ação “Switch focus to Editor” do PyCharm.

​
Obtendo mais ajuda

Se você está enfrentando problemas não cobertos aqui:

  1. Use o comando /bug dentro do Claude Code para reportar problemas diretamente para a Anthropic
  2. Verifique o repositório GitHub para problemas conhecidos
  3. Execute /doctor para verificar a saúde da sua instalação do Claude Code
  4. Pergunte diretamente ao Claude sobre suas capacidades e recursos - Claude tem acesso integrado à sua documentação