​
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.

Conflitos de versão do nvm: Se você tem o nvm instalado tanto no WSL quanto no Windows, pode experimentar conflitos de versão ao alternar versões do Node no WSL. Isso acontece porque o WSL importa o PATH do Windows por padrão, fazendo com que o nvm/npm do Windows tenha prioridade sobre a instalação do WSL.

Você pode identificar esse problema:

  • Executando which npm e which node - se eles apontarem para caminhos do Windows (começando com /mnt/c/), as versões do Windows estão sendo usadas
  • Experimentando funcionalidade quebrada após alternar versões do Node com nvm no WSL

Para resolver esse problema, corrija seu PATH do Linux para garantir que as versões do node/npm do Linux tenham prioridade:

Solução principal: Certifique-se de que o nvm está carregado adequadamente no seu shell

A causa mais comum é que o nvm não está carregado em shells não interativos. Adicione o seguinte ao seu arquivo de configuração do shell (~/.bashrc, ~/.zshrc, etc.):

# Carrega o nvm se ele existir
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Ou execute diretamente na sua sessão atual:

source ~/.nvm/nvm.sh

Alternativa: Ajustar ordem do PATH

Se o nvm está carregado adequadamente mas os caminhos do Windows ainda têm prioridade, você pode explicitamente adicionar seus caminhos do Linux ao início do PATH na sua configuração do shell:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Evite desabilitar a importação do PATH do Windows (appendWindowsPath = false) pois isso quebra a capacidade de chamar facilmente executáveis do Windows a partir do WSL. Da mesma forma, evite desinstalar o Node.js do Windows se você o usa para desenvolvimento no Windows.

​
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 build 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 do 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 caminho para o executável claude

Verificar instalação:

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

​
Permissões e autenticação

​
Solicitações repetidas de permissão

Se você se encontra aprovando repetidamente os mesmos comandos, 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á experimentando 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 trabalhar com a maioria dos ambientes de desenvolvimento, mas pode consumir recursos significativos ao processar bases de código grandes. Se você está experimentando 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

​
Problemas de busca e descoberta

Se a ferramenta de Busca, menções @file, agentes personalizados e comandos slash personalizados não estão funcionando, instale o ripgrep do sistema:

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

Então defina USE_BUILTIN_RIPGREP=0 no seu ambiente.

​
Resultados de busca lentos ou incompletos no WSL

Penalidades de performance de leitura de disco ao trabalhar através de sistemas de arquivos no WSL podem resultar em menos correspondências do que esperado (mas não uma falta completa de funcionalidade de busca) ao usar o Claude Code no WSL.

/doctor mostrará Busca como OK neste caso.

Soluções:

  1. Submeta buscas mais específicas: Reduza o número de arquivos pesquisados especificando diretórios ou tipos de arquivo: “Buscar por lógica de validação JWT no pacote auth-service” ou “Encontrar uso de hash md5 em arquivos JS”.

  2. Mova projeto para sistema de arquivos Linux: Se possível, certifique-se de que seu projeto está localizado no sistema de arquivos Linux (/home/) em vez do sistema de arquivos Windows (/mnt/c/).

  3. Use Windows nativo em vez disso: Considere executar o Claude Code nativamente no Windows em vez de através do WSL, para melhor performance do sistema de arquivos.

​
Problemas de integração com IDE

​
IDE JetBrains não detectado no WSL2

Se você está usando o Claude Code no WSL2 com IDEs JetBrains e recebendo erros “No available IDEs detected”, isso provavelmente é devido à configuração de rede do WSL2 ou Windows Firewall bloqueando a conexão.

​
Modos de rede do WSL2

O WSL2 usa rede NAT por padrão, que pode impedir a detecção do IDE. Você tem duas opções:

Opção 1: Configurar Windows Firewall (recomendado)

  1. Encontre seu endereço IP do WSL2:

    wsl hostname -I
# Exemplo de saída: 172.21.123.456

  2. Abra PowerShell como Administrador e crie uma regra de firewall:

    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

    (Ajuste a faixa de IP baseada na sua sub-rede WSL2 do passo 1)

  3. Reinicie tanto seu IDE quanto o Claude Code

Opção 2: Mudar para rede espelhada

Adicione ao .wslconfig no seu diretório de usuário Windows:

[wsl2]
networkingMode=mirrored

Então reinicie o WSL com wsl --shutdown do PowerShell.

Esses problemas de rede afetam apenas o WSL2. O WSL1 usa a rede do host diretamente e não requer essas configurações.

Para dicas adicionais de configuração do JetBrains, veja nosso guia de integração com IDE.

​
Relatando problemas de integração com IDE no Windows (tanto nativo quanto WSL)

Se você está experimentando problemas de integração com IDE no Windows, por favor crie um issue com as seguintes informações: se você está nativo (git bash), ou WSL1/WSL2, modo de rede WSL (NAT ou espelhado), nome/versão do IDE, versão da extensão/plugin do Claude Code, e tipo de shell (bash/zsh/etc)

​
Tecla ESC não funcionando 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 keybinding com os atalhos padrão do JetBrains.

Para corrigir esse problema:

  1. Vá para Settings → Tools → Terminal
  2. Ou:
    • Desmarque “Move focus to the editor with Escape”, ou
    • Clique em “Configure terminal keybindings” e delete o atalho “Switch focus to Editor”
  3. Aplique as mudanças

Isso permite que a tecla ESC interrompa adequadamente as operações do Claude Code.

​
Problemas de formatação de Markdown

O Claude Code às vezes gera arquivos markdown com tags de linguagem ausentes em cercas de código, o que pode afetar o destaque de sintaxe e legibilidade no GitHub, editores e ferramentas de documentação.

​
Tags de linguagem ausentes em blocos de código

Se você notar blocos de código como este em markdown gerado:

```
function example() {
  return "hello";
}
```

Em vez de blocos adequadamente marcados como:

```javascript
function example() {
  return "hello";
}
```

Soluções:

  1. Peça ao Claude para adicionar tags de linguagem: Simplesmente solicite “Por favor adicione tags de linguagem apropriadas a todos os blocos de código neste arquivo markdown.”

  2. Use hooks de pós-processamento: Configure hooks de formatação automática para detectar e adicionar tags de linguagem ausentes. Veja o exemplo de hook de formatação markdown para detalhes de implementação.

  3. Verificação manual: Após gerar arquivos markdown, revise-os para formatação adequada de blocos de código e solicite correções se necessário.

​
Espaçamento e formatação inconsistentes

Se o markdown gerado tem linhas em branco excessivas ou espaçamento inconsistente:

Soluções:

  1. Solicite correções de formatação: Peça ao Claude para “Corrigir problemas de espaçamento e formatação neste arquivo markdown.”

  2. Use ferramentas de formatação: Configure hooks para executar formatadores de markdown como prettier ou scripts de formatação personalizados em arquivos markdown gerados.

  3. Especifique preferências de formatação: Inclua requisitos de formatação nos seus prompts ou arquivos de memória do projeto.

​
Melhores práticas para geração de markdown

Para minimizar problemas de formatação:

  • Seja explícito nas solicitações: Peça por “markdown adequadamente formatado com blocos de código marcados com linguagem”
  • Use convenções do projeto: Documente seu estilo de markdown preferido no CLAUDE.md
  • Configure hooks de validação: Use hooks de pós-processamento para verificar e corrigir automaticamente problemas comuns de formatação

​
Obtendo mais ajuda

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

  1. Use o comando /bug dentro do Claude Code para reportar problemas diretamente à 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 ao Claude diretamente sobre suas capacidades e recursos - Claude tem acesso integrado à sua documentação