Pular para o conteúdo principal

​
Solucionar problemas de instalação

Se preferir pular o terminal completamente, o aplicativo Claude Code Desktop permite instalar e usar Claude Code através de uma interface gráfica. Baixe para macOS ou Windows e comece a codificar sem nenhuma configuração de linha de comando.
Encontre a mensagem de erro ou sintoma que você está vendo:
O que você vêSolução
command not found: claude ou 'claude' is not recognizedCorrija seu PATH
syntax error near unexpected token '<'O script de instalação retorna HTML
curl: (56) Failure writing output to destinationBaixe o script primeiro, depois execute-o
Killed durante a instalação no LinuxAdicione espaço de swap para servidores com pouca memória
TLS connect error ou SSL/TLS secure channelAtualize os certificados CA
Failed to fetch version ou não consegue alcançar o servidor de downloadVerifique a conectividade de rede e configurações de proxy
irm is not recognized ou && is not validUse o comando correto para seu shell
Claude Code on Windows requires git-bashInstale ou configure Git Bash
Error loading shared libraryVariante binária incorreta para seu sistema
Illegal instruction no LinuxIncompatibilidade de arquitetura
dyld: cannot load ou Abort trap no macOSIncompatibilidade binária
Invoke-Expression: Missing argument in parameter listO script de instalação retorna HTML
App unavailable in regionClaude Code não está disponível em seu país. Veja países suportados.
unable to get local issuer certificateConfigure certificados CA corporativos
OAuth error ou 403 ForbiddenCorrija a autenticação
Se seu problema não estiver listado, trabalhe através dessas etapas de diagnóstico.

​
Depurar problemas de instalação

​
Verificar conectividade de rede

O instalador baixa de storage.googleapis.com. Verifique se você consegue alcançá-lo: 
curl -sI https://storage.googleapis.com
Se isso falhar, sua rede pode estar bloqueando a conexão. Causas comuns:
  • Firewalls corporativos ou proxies bloqueando Google Cloud Storage
  • Restrições de rede regional: tente uma VPN ou rede alternativa
  • Problemas de TLS/SSL: atualize os certificados CA do seu sistema, ou verifique se HTTPS_PROXY está configurado
Se você estiver atrás de um proxy corporativo, defina HTTPS_PROXY e HTTP_PROXY para o endereço do seu proxy antes de instalar. Peça à sua equipe de TI a URL do proxy se você não souber, ou verifique as configurações de proxy do seu navegador. Este exemplo define ambas as variáveis de proxy e executa o instalador através do seu proxy: 
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

​
Verificar seu PATH

Se a instalação foi bem-sucedida, mas você recebe um erro command not found ou not recognized ao executar claude, o diretório de instalação não está em seu PATH. Seu shell procura por programas em diretórios listados em PATH, e o instalador coloca claude em ~/.local/bin/claude no macOS/Linux ou %USERPROFILE%\.local\bin\claude.exe no Windows. Verifique se o diretório de instalação está em seu PATH listando suas entradas de PATH e filtrando por local/bin: 
echo $PATH | tr ':' '\n' | grep local/bin
Se não houver saída, o diretório está faltando. Adicione-o à sua configuração de shell:
# Zsh (padrão do macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash (padrão do Linux)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Alternativamente, feche e reabra seu terminal.Verifique se a correção funcionou:
claude --version

​
Verificar instalações conflitantes

Múltiplas instalações do Claude Code podem causar incompatibilidades de versão ou comportamento inesperado. Verifique o que está instalado:
Liste todos os binários claude encontrados em seu PATH:
which -a claude
Verifique se o instalador nativo e as versões npm estão presentes:
ls -la ~/.local/bin/claude

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null
Se você encontrar múltiplas instalações, mantenha apenas uma. A instalação nativa em ~/.local/bin/claude é recomendada. Remova qualquer instalação extra: Desinstale uma instalação global npm: 
npm uninstall -g @anthropic-ai/claude-code
Remova uma instalação Homebrew no macOS: 
brew uninstall --cask claude-code

​
Verificar permissões de diretório

O instalador precisa de acesso de escrita a ~/.local/bin/ e ~/.claude/. Se a instalação falhar com erros de permissão, verifique se esses diretórios são graváveis: 
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"
Se algum diretório não for gravável, crie o diretório de instalação e defina seu usuário como proprietário: 
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

​
Verificar se o binário funciona

Se claude está instalado mas falha ou trava na inicialização, execute essas verificações para estreitar a causa. Confirme que o binário existe e é executável: 
ls -la $(which claude)
No Linux, verifique se há bibliotecas compartilhadas faltando. Se ldd mostrar bibliotecas faltando, você pode precisar instalar pacotes do sistema. No Alpine Linux e outras distribuições baseadas em musl, veja configuração do Alpine Linux. 
ldd $(which claude) | grep "not found"
Execute uma verificação rápida de sanidade de que o binário pode executar: 
claude --version

​
Problemas comuns de instalação

Estes são os problemas de instalação mais frequentemente encontrados e suas soluções.

​
O script de instalação retorna HTML em vez de um script de shell

Ao executar o comando de instalação, você pode ver um desses erros: 
bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'
No PowerShell, o mesmo problema aparece como: 
Invoke-Expression: Missing argument in parameter list.
Isso significa que a URL de instalação retornou uma página HTML em vez do script de instalação. Se a página HTML disser “App unavailable in region”, Claude Code não está disponível em seu país. Veja países suportados. Caso contrário, isso pode acontecer devido a problemas de rede, roteamento regional ou uma interrupção temporária do serviço. Soluções:
  1. Use um método de instalação alternativo: No macOS ou Linux, instale via Homebrew: 
    brew install --cask claude-code
    No Windows, instale via WinGet: 
    winget install Anthropic.ClaudeCode
  2. Tente novamente após alguns minutos: o problema geralmente é temporário. Aguarde e tente o comando original novamente.

​
command not found: claude após a instalação

A instalação terminou, mas claude não funciona. A mensagem de erro exata varia por plataforma:
PlataformaMensagem de erro
macOSzsh: command not found: claude
Linuxbash: claude: command not found
Windows CMD'claude' is not recognized as an internal or external command
PowerShellclaude : The term 'claude' is not recognized as the name of a cmdlet
Isso significa que o diretório de instalação não está no caminho de pesquisa do seu shell. Veja Verificar seu PATH para a correção em cada plataforma.

​
curl: (56) Failure writing output to destination

O comando curl ... | bash baixa o script e o passa diretamente para Bash para execução usando um pipe (|). Este erro significa que a conexão foi interrompida antes do script terminar de baixar. Causas comuns incluem interrupções de rede, o download sendo bloqueado no meio do caminho ou limites de recursos do sistema. Soluções:
  1. Verifique a estabilidade da rede: Os binários do Claude Code são hospedados no Google Cloud Storage. Teste se você consegue alcançá-lo: 
    curl -fsSL https://storage.googleapis.com -o /dev/null
    Se o comando for concluído silenciosamente, sua conexão está bem e o problema provavelmente é intermitente. Tente novamente o comando de instalação. Se você vir um erro, sua rede pode estar bloqueando o download.
  2. Tente um método de instalação alternativo: No macOS ou Linux: 
    brew install --cask claude-code
    No Windows: 
    winget install Anthropic.ClaudeCode

​
Erros de conexão TLS ou SSL

Erros como curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed ou Could not establish trust relationship for the SSL/TLS secure channel do PowerShell indicam falhas no handshake TLS. Soluções:
  1. Atualize seus certificados CA do sistema: No Ubuntu/Debian: 
    sudo apt-get update && sudo apt-get install ca-certificates
    No macOS via Homebrew: 
    brew install ca-certificates
  2. No Windows, ative TLS 1.2 no PowerShell antes de executar o instalador: 
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex
  3. Verifique se há interferência de proxy ou firewall: proxies corporativos que realizam inspeção TLS podem causar esses erros, incluindo unable to get local issuer certificate. Defina NODE_EXTRA_CA_CERTS para seu pacote de certificados CA corporativo: 
    export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
    Peça à sua equipe de TI o arquivo de certificado se você não tiver. Você também pode tentar em uma conexão direta para confirmar que o proxy é a causa.

​
Failed to fetch version from storage.googleapis.com

O instalador não conseguiu alcançar o servidor de download. Isso geralmente significa que storage.googleapis.com está bloqueado em sua rede. Soluções:
  1. Teste a conectividade diretamente: 
    curl -sI https://storage.googleapis.com
  2. Se atrás de um proxy, defina HTTPS_PROXY para que o instalador possa rotear através dele. Veja configuração de proxy para detalhes. 
    export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
  3. Se em uma rede restrita, tente uma rede diferente ou VPN, ou use um método de instalação alternativo: No macOS ou Linux: 
    brew install --cask claude-code
    No Windows: 
    winget install Anthropic.ClaudeCode

​
Windows: irm ou && não reconhecido

Se você vir 'irm' is not recognized ou The token '&&' is not valid, você está executando o comando errado para seu shell.
  • irm não reconhecido: você está em CMD, não PowerShell. Você tem duas opções: Abra PowerShell procurando por “PowerShell” no menu Iniciar e execute o comando de instalação original: 
    irm https://claude.ai/install.ps1 | iex
    Ou fique em CMD e use o instalador CMD em vez disso: 
    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  • && não válido: você está em PowerShell mas executou o comando do instalador CMD. Use o instalador PowerShell: 
    irm https://claude.ai/install.ps1 | iex

​
Instalação interrompida em servidores Linux com pouca memória

Se você vir Killed durante a instalação em um VPS ou instância em nuvem: 
Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
O assassino OOM do Linux encerrou o processo porque o sistema ficou sem memória. Claude Code requer pelo menos 4 GB de RAM disponível. Soluções:
  1. Adicione espaço de swap se seu servidor tiver RAM limitada. Swap usa espaço em disco como memória de overflow, permitindo que a instalação seja concluída mesmo com RAM física baixa. Crie um arquivo de swap de 2 GB e ative-o: 
    sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
    Depois tente a instalação novamente: 
    curl -fsSL https://claude.ai/install.sh | bash
  2. Feche outros processos para liberar memória antes de instalar.
  3. Use uma instância maior se possível. Claude Code requer pelo menos 4 GB de RAM.

​
A instalação trava no Docker

Ao instalar Claude Code em um contêiner Docker, instalar como root em / pode causar travamentos. Soluções:
  1. Defina um diretório de trabalho antes de executar o instalador. Quando executado de /, o instalador verifica todo o sistema de arquivos, o que causa uso excessivo de memória. Definir WORKDIR limita a verificação a um pequeno diretório: 
    WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
  2. Aumente os limites de memória do Docker se usar Docker Desktop: 
    docker build --memory=4g .

​
Windows: Claude Desktop substitui o comando CLI claude

Se você instalou uma versão mais antiga do Claude Desktop, ela pode registrar um Claude.exe no diretório WindowsApps que tem prioridade de PATH sobre Claude Code CLI. Executar claude abre o aplicativo Desktop em vez do CLI. Atualize Claude Desktop para a versão mais recente para corrigir este problema.

​
Windows: “Claude Code on Windows requires git-bash”

Claude Code no Windows nativo precisa de Git for Windows, que inclui Git Bash. Se Git não estiver instalado, baixe e instale de git-scm.com/downloads/win. Durante a configuração, selecione “Add to PATH.” Reinicie seu terminal após instalar. Se Git já estiver instalado mas Claude Code ainda não conseguir encontrá-lo, defina o caminho em seu arquivo settings.json: 
{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}
Se seu Git está instalado em outro lugar, encontre o caminho executando where.exe git no PowerShell e use o caminho bin\bash.exe desse diretório.

​
Linux: variante binária incorreta instalada (incompatibilidade musl/glibc)

Se você vir erros sobre bibliotecas compartilhadas faltando como libstdc++.so.6 ou libgcc_s.so.1 após a instalação, o instalador pode ter baixado a variante binária incorreta para seu sistema. 
Error loading shared library libstdc++.so.6: No such file or directory
Isso pode acontecer em sistemas baseados em glibc que têm pacotes de compilação cruzada musl instalados, fazendo o instalador detectar incorretamente o sistema como musl. Soluções:
  1. Verifique qual libc seu sistema usa: 
    ldd /bin/ls | head -1
    Se mostrar linux-vdso.so ou referências a /lib/x86_64-linux-gnu/, você está em glibc. Se mostrar musl, você está em musl.
  2. Se você está em glibc mas recebeu o binário musl, remova a instalação e reinstale. Você também pode baixar manualmente o binário correto do bucket GCS em https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json. Abra uma issue no GitHub com a saída de ldd /bin/ls e ls /lib/libc.musl*.
  3. Se você realmente está em musl (Alpine Linux), instale os pacotes necessários: 
    apk add libgcc libstdc++ ripgrep

​
Illegal instruction no Linux

Se o instalador imprimir Illegal instruction em vez da mensagem Killed do OOM, o binário baixado não corresponde à arquitetura da sua CPU. Isso geralmente acontece em servidores ARM que recebem um binário x86, ou em CPUs mais antigas que carecem de conjuntos de instruções necessários. 
bash: line 142: 2238232 Illegal instruction    "$binary_path" install ${TARGET:+"$TARGET"}
Soluções:
  1. Verifique sua arquitetura: 
    uname -m
    x86_64 significa 64-bit Intel/AMD, aarch64 significa ARM64. Se o binário não corresponder, abra uma issue no GitHub com a saída.
  2. Tente um método de instalação alternativo enquanto o problema de arquitetura é resolvido: 
    brew install --cask claude-code

​
dyld: cannot load no macOS

Se você vir dyld: cannot load ou Abort trap: 6 durante a instalação, o binário é incompatível com sua versão do macOS ou hardware. 
dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6
Soluções:
  1. Verifique sua versão do macOS: Claude Code requer macOS 13.0 ou posterior. Abra o menu Apple e selecione About This Mac para verificar sua versão.
  2. Atualize o macOS se você estiver em uma versão mais antiga. O binário usa comandos de carregamento que versões mais antigas do macOS não suportam.
  3. Tente Homebrew como um método de instalação alternativo: 
    brew install --cask claude-code

​
Problemas de instalação do Windows: erros em WSL

Você pode encontrar os seguintes problemas em WSL: Problemas de detecção de SO/plataforma: se você receber um erro durante a instalação, WSL pode estar usando 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 Node via gerenciador de pacotes da sua distribuição Linux ou via nvm. Conflitos de versão nvm: se você tiver nvm instalado tanto em WSL quanto em Windows, você pode experimentar conflitos de versão ao alternar versões do Node em WSL. Isso acontece porque WSL importa o PATH do Windows por padrão, fazendo nvm/npm do Windows ter prioridade sobre a instalação WSL. Você pode identificar este problema por:
  • Executar which npm e which node - se apontarem para caminhos do Windows (começando com /mnt/c/), versões do Windows estão sendo usadas
  • Experimentar funcionalidade quebrada após alternar versões do Node com nvm em WSL
Para resolver este problema, corrija seu PATH do Linux para garantir que as versões do Linux node/npm tenham prioridade: Solução primária: Certifique-se de que nvm está carregado adequadamente 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 de shell (~/.bashrc, ~/.zshrc, etc.): 
# Carregue 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: Ajuste a ordem do PATH Se nvm está carregado adequadamente mas caminhos do Windows ainda têm prioridade, você pode explicitamente colocar seus caminhos do Linux no início do PATH em sua configuração de shell: 
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
Evite desabilitar a importação de PATH do Windows via appendWindowsPath = false pois isso quebra a capacidade de chamar executáveis do Windows de WSL. Da mesma forma, evite desinstalar Node.js do Windows se você o usa para desenvolvimento do Windows.

​
Configuração de sandbox WSL2

Sandboxing é suportado em WSL2 mas requer instalar pacotes adicionais. Se você vir um erro como “Sandbox requires socat and bubblewrap” ao executar /sandbox, instale as dependências: 
sudo apt-get install bubblewrap socat
WSL1 não suporta sandboxing. Se você vir “Sandboxing requires WSL2”, você precisa atualizar para WSL2 ou executar Claude Code sem sandboxing.

​
Erros de permissão durante a instalação

Se o instalador nativo falhar com erros de permissão, o diretório de destino pode não ser gravável. Veja Verificar permissões de diretório. Se você instalou anteriormente com npm e está tendo erros de permissão específicos do npm, mude para o instalador nativo: 
curl -fsSL https://claude.ai/install.sh | bash

​
Permissões e autenticação

Essas seções abordam falhas de login, problemas de token e comportamento de prompts de permissão.

​
Prompts de permissão repetidos

Se você se encontrar aprovando repetidamente 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 o navegador não abrir automaticamente durante o login, pressione c para copiar a URL OAuth para sua área de transferência e depois cole-a em seu navegador manualmente.

​
Erro OAuth: Código inválido

Se você vir OAuth error: Invalid code. Please make sure the full code was copied, o código de login expirou ou foi truncado durante a cópia e colagem. Soluções:
  • Pressione Enter para tentar novamente e complete o login rapidamente após o navegador abrir
  • Digite c para copiar a URL completa se o navegador não abrir automaticamente
  • Se usar uma sessão remota/SSH, o navegador pode abrir na máquina errada. Copie a URL exibida no terminal e abra-a em seu navegador local em vez disso.

​
403 Forbidden após o login

Se você vir API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}} após fazer login:
  • Usuários Claude Pro/Max: verifique se sua assinatura está ativa em claude.ai/settings
  • Usuários Console: confirme que sua conta tem a função “Claude Code” ou “Developer” atribuída pelo seu administrador
  • Atrás de um proxy: proxies corporativos podem interferir com solicitações de API. Veja configuração de rede para configuração de proxy.

​
Falha de login OAuth em WSL2

O login baseado em navegador em WSL2 pode falhar se WSL não conseguir abrir seu navegador do Windows. Defina a variável de ambiente BROWSER: 
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude
Ou copie a URL manualmente: quando o prompt de login aparecer, pressione c para copiar a URL OAuth e depois cole-a em seu navegador do Windows.

​
”Not logged in” ou token expirado

Se Claude Code solicitar que você faça login novamente após uma sessão, seu token OAuth pode ter expirado. Execute /login para se autenticar novamente. Se isso acontecer frequentemente, verifique se seu relógio do sistema está preciso, pois a validação de token depende de timestamps corretos.

​
Locais de arquivo de configuração

Claude Code armazena configuração em vários locais:
ArquivoPropósito
~/.claude/settings.jsonConfigurações do usuário (permissões, hooks, substituições de modelo)
.claude/settings.jsonConfigurações do projeto (verificadas no controle de origem)
.claude/settings.local.jsonConfigurações locais do projeto (não confirmadas)
~/.claude.jsonEstado global (tema, OAuth, servidores MCP)
.mcp.jsonServidores MCP do projeto (verificados no controle de origem)
managed-mcp.jsonServidores MCP gerenciados
Configurações gerenciadasConfigurações gerenciadas (gerenciadas por servidor, políticas MDM/nível de SO ou baseadas em arquivo)
No Windows, ~ refere-se ao seu diretório home do usuário, como C:\Users\SeuNome. Para detalhes sobre como configurar esses arquivos, veja Configurações e MCP.

​
Redefinir configuração

Para redefinir Claude Code para configurações padrão, você pode remover os arquivos de configuração: 
# Redefinir todas as configurações e estado do usuário
rm ~/.claude.json
rm -rf ~/.claude/

# Redefinir configurações específicas do projeto
rm -rf .claude/
rm .mcp.json
Isso removerá todas as suas configurações, configurações de servidor MCP e histórico de sessão.

​
Desempenho e estabilidade

Essas seções cobrem problemas relacionados ao uso de recursos, responsividade e comportamento de pesquisa.

​
Alto uso de CPU ou memória

Claude Code é 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 parece 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 pesquisa e descoberta

Se a ferramenta Search, menções @file, agentes personalizados e skills personalizados não estão funcionando, instale o sistema ripgrep: 
# 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
Depois defina USE_BUILTIN_RIPGREP=0 em seu ambiente.

​
Resultados de pesquisa lentos ou incompletos em WSL

Penalidades de desempenho de leitura de disco ao trabalhar entre sistemas de arquivos em WSL podem resultar em menos correspondências do que esperado ao usar Claude Code em WSL. A pesquisa ainda funciona, mas retorna menos resultados do que em um sistema de arquivos nativo.
/doctor mostrará Search como OK neste caso.
Soluções:
  1. Envie pesquisas 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 de WSL, para melhor desempenho do sistema de arquivos.

​
Problemas de integração de IDE

Se Claude Code não se conectar ao seu IDE ou se comportar inesperadamente dentro de um terminal IDE, tente as soluções abaixo.

​
IDE JetBrains não detectado em WSL2

Se você está usando Claude Code em 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 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: Configure Windows Firewall (recomendado)
  1. Encontre seu endereço IP WSL2: 
    wsl hostname -I
# Saída de exemplo: 172.21.123.45
  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 tanto seu IDE quanto Claude Code
Opção 2: Mude para rede espelhada Adicione ao .wslconfig em seu diretório de usuário do Windows: 
[wsl2]
networkingMode=mirrored
Depois 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 o guia de IDE JetBrains.

​
Relatar problemas de integração de IDE do Windows

Se você está experimentando problemas de integração de IDE no Windows, crie uma issue com as seguintes informações:
  • Tipo de ambiente: Windows nativo (Git Bash) ou WSL1/WSL2
  • Modo de rede WSL, se aplicável: NAT ou espelhado
  • Nome e versão do IDE
  • Versão da extensão/plugin Claude Code
  • Tipo de shell: Bash, Zsh, PowerShell, etc.

​
Tecla Escape não funciona em terminais IDE JetBrains

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 atalho de teclado com os atalhos padrão do JetBrains. Para corrigir este problema:
  1. Vá para Configurações → Ferramentas → Terminal
  2. Qualquer um:
    • 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 faltando em cercas de código, o que pode afetar destaque de sintaxe e legibilidade no GitHub, editores e ferramentas de documentação.

​
Tags de linguagem faltando em blocos de código

Se você notar blocos de código como este em markdown gerado: 
```
function example() {
  return "hello";
}
```text
Em vez de blocos adequadamente marcados como: 
```javascript
function example() {
  return "hello";
}
```text
Soluções:
  1. Peça ao Claude para adicionar tags de linguagem: solicite “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 faltando. Veja Auto-format code after edits para um exemplo de um hook de formatação PostToolUse.
  3. Verificação manual: após gerar arquivos markdown, revise-os para formatação adequada de bloco de código e solicite correções se necessário.

​
Espaçamento e formatação inconsistentes

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

​
Reduzir problemas de formatação 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 comuns de formatação

​
Obter 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 diagnosticar problemas. Ele verifica:
    • Tipo de instalação, versão e funcionalidade de pesquisa
    • Status de atualização automática e versões disponíveis
    • Arquivos de configuração inválidos (JSON malformado, tipos incorretos)
    • Erros de configuração de servidor MCP
    • Problemas de configuração de atalhos de teclado
    • Avisos de uso de contexto (arquivos CLAUDE.md grandes, alto uso de token MCP, regras de permissão inacessíveis)
    • Erros de carregamento de plugin e agente
  4. Pergunte ao Claude diretamente sobre suas capacidades e recursos - Claude tem acesso integrado à sua documentação