Pular para o conteúdo principal

​
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 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 nvm instalado tanto no WSL quanto no Windows, você 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 este problema por:
  • Executar which npm e which node - se apontarem para caminhos do Windows (começando com /mnt/c/), as versões do Windows estão sendo usadas
  • Experimentar funcionalidade quebrada após alternar versões do Node com nvm no WSL
Para resolver este problema, corrija seu PATH do Linux para garantir que as versões do node/npm do Linux tenham prioridade: Solução primária: Certifique-se de que nvm está carregado corretamente em seu shell A causa mais comum é que nvm não está carregado em shells não-interativos. Adicione o seguinte ao seu arquivo de configuração do shell (~/.bashrc, ~/.zshrc, etc.): 
# Load nvm if it exists
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: Ajuste a ordem do PATH Se nvm está carregado corretamente mas os caminhos do Windows ainda têm prioridade, você pode explicitamente adicionar seus caminhos 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 a partir do WSL. Da mesma forma, evite desinstalar o Node.js do Windows se você o usa para desenvolvimento do Windows.

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

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

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

Claude Code tem uma instalação nativa que não depende de 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: 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell: 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([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 symlink 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 Claude Code estiver funcionando, você pode migrar para uma instalação local: 
claude migrate-installer
Isso move Claude Code para ~/.claude/local/ e configura um alias em sua configuração do shell. Nenhum sudo é necessário para futuras atualizações. Após a migração, reinicie seu shell e verifique sua instalação: No macOS/Linux/WSL: 
which claude  # Should show an alias to ~/.claude/local/claude
No Windows: 
where claude  # Should show path to claude executable
Verifique a instalação: 
claude doctor # Check installation health

​
Permissões e autenticação

​
Prompts de permissão repetidos

Se você se encontrar repetidamente aprovando os mesmos comandos, você pode permitir que ferramentas específicas sejam executadas 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 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.

​
Desempenho e estabilidade

​
Alto uso de CPU ou memória

Claude Code foi projetado para funcionar com a maioria dos ambientes de desenvolvimento, mas pode consumir recursos significativos ao processar grandes bases de código. Se você está experimentando problemas de desempenho:
  1. Use /compact regularmente para reduzir o tamanho do contexto
  2. Feche e reinicie Claude Code entre tarefas principais
  3. Considere adicionar grandes diretórios de compilação ao seu arquivo .gitignore

​
Comando trava ou congela

Se 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 em seu ambiente.

​
Resultados de busca lentos ou incompletos no WSL

Penalidades de desempenho de leitura de disco ao trabalhar entre sistemas de arquivos no WSL podem resultar em correspondências menores do que o esperado (mas não uma falta completa de funcionalidade de busca) ao usar Claude Code no WSL.
/doctor mostrará Search como OK neste caso.
Soluções:
  1. Envie buscas mais específicas: Reduza o número de arquivos pesquisados especificando diretórios ou tipos de arquivo: “Search for JWT validation logic in the auth-service package” ou “Find use of md5 hash in JS files”.
  2. Mova o projeto para o 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 do Windows (/mnt/c/).
  3. Use Windows nativo em vez disso: Considere executar Claude Code nativamente no Windows em vez de através do WSL, para melhor desempenho do sistema de arquivos.

​
Problemas de integração de IDE

​
IDE JetBrains não detectado no WSL2

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

​
Modos de rede do WSL2

WSL2 usa rede NAT por padrão, o que pode impedir a detecção de IDE. Você tem duas opções: Opção 1: Configurar Windows Firewall (recomendado)
  1. Encontre seu endereço IP do WSL2: 
    wsl hostname -I
# Example output: 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 o intervalo de IP com base em sua sub-rede WSL2 da etapa 1)
  3. Reinicie sua IDE e Claude Code
Opção 2: Alternar para rede espelhada Adicione ao .wslconfig em seu diretório de usuário do Windows: 
[wsl2]
networkingMode=mirrored
Então reinicie WSL com wsl --shutdown do PowerShell.
Esses problemas de rede afetam apenas WSL2. WSL1 usa a rede do host diretamente e não requer essas configurações.
Para dicas de configuração adicionais do JetBrains, veja nosso guia de integração de IDE.

​
Relatando problemas de integração de IDE do Windows (nativo e WSL)

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

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

Se você está usando 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 este 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 alterações
Isso permite que a tecla ESC interrompa adequadamente as operações do Claude Code.

​
Problemas de formatação Markdown

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 “Please add appropriate language tags to all code blocks in this markdown file.”
  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 “Fix spacing and formatting issues in this markdown file.”
  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 “properly formatted markdown with language-tagged code blocks”
  • 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 e corrigir automaticamente problemas de formatação comuns

​
Obtendo mais ajuda

Se você está experimentando problemas não cobertos aqui:
  1. Use o comando /bug dentro do Claude Code para relatar 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