​
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ê vir 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 em 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 nvm se 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 em 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 antepor seus caminhos do Linux ao PATH em 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 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 em 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 em 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

​
Prompts de permissão repetidos

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

​
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 se deve a um conflito de vinculação de teclas com os atalhos padrão do JetBrains.

Para corrigir esse problema:

  1. Vá para Settings → Tools → Terminal
  2. Clique no hiperlink “Configure terminal keybindings” próximo a “Override IDE Shortcuts”
  3. Dentro das vinculações de teclas 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.

​
Problemas de busca e descoberta

Se a ferramenta Search, 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 em 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á Search 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. Mover 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. Usar 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 formatação 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 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 em 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 em solicitações: Peça por “markdown adequadamente formatado com blocos de código marcados com linguagem”
  • Use convenções do projeto: Documente seu estilo markdown preferido em CLAUDE.md
  • Configure hooks de validação: Use hooks de pós-processamento para verificar automaticamente e corrigir 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 de sua instalação do Claude Code
  4. Pergunte diretamente ao Claude sobre suas capacidades e recursos - Claude tem acesso integrado à sua documentação