​
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 seu prefixo global do 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 do 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 alteraram a propriedade e permissões de arquivos do sistema ou similares

Se você já executou um comando que alterou as permissões do diretório 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á realizar etapas de recuperação.

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

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

  2. Selecione “Opções avançadas para Ubuntu/Debian”

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

  4. Selecione “Cair para prompt de shell root”

  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

# Garanta que /usr/local seja de propriedade do seu usuário para pacotes npm
chown -R SEU_NOME_DE_USUÁRIO:SEU_NOME_DE_USUÁRIO /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 USB Live:

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

  1. Inicialize a partir de um USB live (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 do sistema real

  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 para 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 com o atualizador automático

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

Se você preferir desativar o atualizador automático, você 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 encontrar aprovando repetidamente os mesmos comandos, você pode permitir que ferramentas específicas sejam executadas sem aprovação usando o comando /permissions. Veja a documentação de Permissões.

​
Problemas de autenticação

Se você estiver 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.

​
Desempenho e estabilidade

​
Alto uso de CPU ou memória

O Claude Code foi projetado para funcionar com a maioria dos ambientes de desenvolvimento, mas pode consumir recursos significativos ao processar bases de código grandes. Se você estiver enfrentando problemas de desempenho:

  1. Use /compact regularmente para reduzir o tamanho do contexto
  2. Feche e reinicie o Claude Code entre tarefas importantes
  3. Considere adicionar diretórios de compilação grandes ao seu arquivo .gitignore

​
Comando trava ou congela

Se o Claude Code parecer não responder:

  1. Pressione Ctrl+C para tentar cancelar a operação atual
  2. Se não responder, você pode precisar fechar o terminal e reiniciar

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

Se você estiver usando o Claude Code em terminais JetBrains e a tecla ESC não interromper o agente como esperado, isso provavelmente se deve a um conflito de atalhos de teclado com os atalhos padrão do JetBrains.

Para corrigir este problema:

  1. Vá para Configurações → Ferramentas → Terminal
  2. Clique no hiperlink “Configurar atalhos de teclado do terminal” ao lado de “Substituir atalhos do IDE”
  3. Dentro dos atalhos do terminal, role para baixo até “Alternar foco para o Editor” e exclua 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 “Alternar foco para o Editor” do PyCharm.

​
Obtendo mais ajuda

Se você estiver enfrentando problemas não abordados 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