​
Problemas comuns de instalação

​
Problemas de permissão no Linux

Ao instalar o Claude Code com npm, você pode encontrar erros de permissão se o prefixo global do seu npm não for gravável pelo usuário (ex. /usr, ou /usr/local).

​
Solução recomendada: Criar um prefixo npm gravável pelo usuário

A abordagem mais segura é configurar o npm para usar um diretório dentro da sua pasta home:

# Primeiro, salve uma lista dos seus pacotes globais existentes para migração posterior
npm list -g --depth=0 > ~/npm-global-packages.txt

# Crie um diretório para seus pacotes globais
mkdir -p ~/.npm-global

# Configure o npm para usar o novo caminho do diretório
npm config set prefix ~/.npm-global

# Nota: Substitua ~/.bashrc por ~/.zshrc, ~/.profile, ou outro arquivo apropriado para seu shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Aplique a nova configuração PATH
source ~/.bashrc

# Agora reinstale o Claude Code no novo local
npm install -g @anthropic-ai/claude-code

# Opcional: Reinstale seus pacotes globais anteriores no novo local
# Veja ~/npm-global-packages.txt e instale os pacotes que deseja manter

Esta solução é recomendada porque:

  • Evita modificar permissões de diretórios do sistema
  • Cria um local limpo e dedicado para seus pacotes npm globais
  • Segue as melhores práticas de segurança

​
Recuperação do Sistema: Se você executou comandos que alteram propriedade e permissões de arquivos do sistema ou similares

Se você já executou um comando que alterou permissões de diretórios do sistema (como sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr) e seu sistema agora está quebrado (por exemplo, se você vê sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set), você precisará executar etapas de recuperação.

Método de Recuperação Ubuntu/Debian:

  1. Durante a reinicialização, mantenha SHIFT pressionado para acessar o menu GRUB

  2. Selecione “Advanced options for Ubuntu/Debian”

  3. Escolha a opção de modo de recuperação

  4. Selecione “Drop to root shell prompt”

  5. Remonte o sistema de arquivos como gravável:

    mount -o remount,rw /

  6. Corrija as permissões:

    # Restaure a propriedade root
chown -R root:root /usr
chmod -R 755 /usr

# Certifique-se de que /usr/local seja propriedade do seu usuário para pacotes npm
chown -R YOUR_USERNAME:YOUR_USERNAME /usr/local

# Defina o bit setuid para binários críticos
chmod u+s /usr/bin/sudo
chmod 4755 /usr/bin/sudo
chmod u+s /usr/bin/su
chmod u+s /usr/bin/passwd
chmod u+s /usr/bin/newgrp
chmod u+s /usr/bin/gpasswd
chmod u+s /usr/bin/chsh
chmod u+s /usr/bin/chfn

# Corrija a configuração do sudo
chown root:root /usr/libexec/sudo/sudoers.so
chmod 4755 /usr/libexec/sudo/sudoers.so
chown root:root /etc/sudo.conf
chmod 644 /etc/sudo.conf

  7. Reinstale pacotes afetados (opcional mas recomendado):

    # Salve a lista de pacotes instalados
dpkg --get-selections > /tmp/installed_packages.txt

# Reinstale-os
awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y

  8. Reinicie:

    reboot
Método Alternativo de Recuperação com Live USB:

Se o modo de recuperação não funcionar, você pode usar um live USB:

  1. Inicialize a partir de um live USB (Ubuntu, Debian, ou qualquer distribuição Linux)

  2. Encontre sua partição do sistema:

    lsblk

  3. Monte sua partição do sistema:

    sudo mount /dev/sdXY /mnt  # substitua sdXY pela sua partição real do sistema

  4. Se você tiver uma partição de boot separada, monte-a também:

    sudo mount /dev/sdXZ /mnt/boot  # se necessário

  5. Faça chroot no seu sistema:

    # Para Ubuntu/Debian:
sudo chroot /mnt

# Para sistemas baseados em Arch:
sudo arch-chroot /mnt

  6. Siga os passos 6-8 do método de recuperação Ubuntu/Debian acima

Após restaurar seu sistema, siga a solução recomendada acima para configurar um prefixo npm gravável pelo usuário.

​
Problemas do atualizador automático

Se o Claude Code não conseguir atualizar automaticamente, pode ser devido a problemas de permissão com seu diretório de prefixo global do npm. Siga a solução recomendada acima para corrigir isso.

Se você preferir desabilitar o atualizador automático, pode definir a variável de ambiente DISABLE_AUTOUPDATER como 1

​
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á 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 Settings → Tools → 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 à 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