Problemas comunes de instalación

Problemas de permisos en Linux

Al instalar Claude Code con npm, puedes encontrar errores de permisos si tu prefijo global de npm no es escribible por el usuario (ej. /usr, o /usr/local).

Solución recomendada: Crear un prefijo npm escribible por el usuario

El enfoque más seguro es configurar npm para usar un directorio dentro de tu carpeta de inicio:

# Primero, guarda una lista de tus paquetes globales existentes para migración posterior
npm list -g --depth=0 > ~/npm-global-packages.txt

# Crea un directorio para tus paquetes globales
mkdir -p ~/.npm-global

# Configura npm para usar la nueva ruta de directorio
npm config set prefix ~/.npm-global

# Nota: Reemplaza ~/.bashrc con ~/.zshrc, ~/.profile, u otro archivo apropiado para tu shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Aplica la nueva configuración de PATH
source ~/.bashrc

# Ahora reinstala Claude Code en la nueva ubicación
npm install -g @anthropic-ai/claude-code

# Opcional: Reinstala tus paquetes globales anteriores en la nueva ubicación
# Mira ~/npm-global-packages.txt e instala los paquetes que quieras conservar

Esta solución es recomendada porque:

  • Evita modificar permisos de directorios del sistema
  • Crea una ubicación limpia y dedicada para tus paquetes npm globales
  • Sigue las mejores prácticas de seguridad

Recuperación del sistema: Si has ejecutado comandos que cambian la propiedad y permisos de archivos del sistema o similares

Si ya has ejecutado un comando que cambió los permisos de directorios del sistema (como sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr) y tu sistema ahora está roto (por ejemplo, si ves sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set), necesitarás realizar pasos de recuperación.

Método de recuperación Ubuntu/Debian:
  1. Mientras reinicias, mantén presionado SHIFT para acceder al menú GRUB

  2. Selecciona “Opciones avanzadas para Ubuntu/Debian”

  3. Elige la opción de modo de recuperación

  4. Selecciona “Ir al prompt de shell root”

  5. Remonta el sistema de archivos como escribible:

    mount -o remount,rw /
    
  6. Corrige permisos:

    # Restaura propiedad root
    chown -R root:root /usr
    chmod -R 755 /usr
    
    # Asegúrate de que /usr/local sea propiedad de tu usuario para paquetes npm
    chown -R TU_NOMBRE_USUARIO:TU_NOMBRE_USUARIO /usr/local
    
    # Establece bit setuid para binarios 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
    
    # Corrige configuración 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. Reinstala paquetes afectados (opcional pero recomendado):

    # Guarda lista de paquetes instalados
    dpkg --get-selections > /tmp/installed_packages.txt
    
    # Reinstálalos
    awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y
    
  8. Reinicia:

    reboot
    
Método alternativo de recuperación con USB en vivo:

Si el modo de recuperación no funciona, puedes usar un USB en vivo:

  1. Inicia desde un USB en vivo (Ubuntu, Debian, o cualquier distribución Linux)

  2. Encuentra tu partición del sistema:

    lsblk
    
  3. Monta tu partición del sistema:

    sudo mount /dev/sdXY /mnt  # reemplaza sdXY con tu partición real del sistema
    
  4. Si tienes una partición de arranque separada, móntala también:

    sudo mount /dev/sdXZ /mnt/boot  # si es necesario
    
  5. Haz chroot a tu sistema:

    # Para Ubuntu/Debian:
    sudo chroot /mnt
    
    # Para sistemas basados en Arch:
    sudo arch-chroot /mnt
    
  6. Sigue los pasos 6-8 del método de recuperación Ubuntu/Debian arriba

Después de restaurar tu sistema, sigue la solución recomendada arriba para configurar un prefijo npm escribible por el usuario.

Problemas del actualizador automático

Si Claude Code no puede actualizarse automáticamente, puede ser debido a problemas de permisos con tu directorio de prefijo global npm. Sigue la solución recomendada arriba para corregir esto.

Si prefieres deshabilitar el actualizador automático en su lugar, puedes establecer la variable de entorno DISABLE_AUTOUPDATER a 1

Permisos y autenticación

Solicitudes de permisos repetidas

Si te encuentras aprobando repetidamente los mismos comandos, puedes permitir que herramientas específicas se ejecuten sin aprobación usando el comando /permissions. Ver documentación de Permisos.

Problemas de autenticación

Si estás experimentando problemas de autenticación:

  1. Ejecuta /logout para cerrar sesión completamente
  2. Cierra Claude Code
  3. Reinicia con claude y completa el proceso de autenticación nuevamente

Si los problemas persisten, intenta:

rm -rf ~/.config/claude-code/auth.json
claude

Esto elimina tu información de autenticación almacenada y fuerza un inicio de sesión limpio.

Rendimiento y estabilidad

Alto uso de CPU o memoria

Claude Code está diseñado para trabajar con la mayoría de entornos de desarrollo, pero puede consumir recursos significativos al procesar bases de código grandes. Si estás experimentando problemas de rendimiento:

  1. Usa /compact regularmente para reducir el tamaño del contexto
  2. Cierra y reinicia Claude Code entre tareas importantes
  3. Considera agregar directorios de construcción grandes a tu archivo .gitignore

El comando se cuelga o se congela

Si Claude Code parece no responder:

  1. Presiona Ctrl+C para intentar cancelar la operación actual
  2. Si no responde, puede que necesites cerrar la terminal y reiniciar

La tecla ESC no funciona en terminales JetBrains (IntelliJ, PyCharm, etc.)

Si estás usando Claude Code en terminales JetBrains y la tecla ESC no interrumpe el agente como se esperaba, esto probablemente se debe a un conflicto de combinación de teclas con los atajos predeterminados de JetBrains.

Para corregir este problema:

  1. Ve a Configuración → Herramientas → Terminal
  2. Haz clic en el hipervínculo “Configurar combinaciones de teclas del terminal” junto a “Anular atajos del IDE”
  3. Dentro de las combinaciones de teclas del terminal, desplázate hacia abajo hasta “Cambiar foco al Editor” y elimina ese atajo

Esto permitirá que la tecla ESC funcione correctamente para cancelar operaciones de Claude Code en lugar de ser capturada por la acción “Cambiar foco al Editor” de PyCharm.

Obtener más ayuda

Si estás experimentando problemas no cubiertos aquí:

  1. Usa el comando /bug dentro de Claude Code para reportar problemas directamente a Anthropic
  2. Revisa el repositorio de GitHub para problemas conocidos
  3. Ejecuta /doctor para verificar la salud de tu instalación de Claude Code