​
Problemas comunes de instalación

​
Problemas de permisos en Linux

Al instalar Claude Code con npm, puede encontrar errores de permisos si su prefijo global de npm no tiene permisos de escritura para el usuario (por ejemplo, /usr, o /usr/local).

​
Solución recomendada: Crear un prefijo npm con permisos de escritura para el usuario

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

# Primero, guarde una lista de sus paquetes globales existentes para migrarlos después
npm list -g --depth=0 > ~/npm-global-packages.txt

# Cree un directorio para sus paquetes globales
mkdir -p ~/.npm-global

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

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

# Aplique la nueva configuración del PATH
source ~/.bashrc

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

# Opcional: Reinstale sus paquetes globales anteriores en la nueva ubicación
# Mire ~/npm-global-packages.txt e instale los paquetes que desea mantener

Esta solución es recomendada porque:

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

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

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

Método de recuperación para Ubuntu/Debian:

  1. Durante el reinicio, mantenga presionada la tecla SHIFT para acceder al menú GRUB

  2. Seleccione “Opciones avanzadas para Ubuntu/Debian”

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

  4. Seleccione “Ir al prompt de shell root”

  5. Vuelva a montar el sistema de archivos con permisos de escritura:

    mount -o remount,rw /

  6. Arregle los permisos:

    # Restaure la propiedad de root
chown -R root:root /usr
chmod -R 755 /usr

# Asegúrese de que /usr/local sea propiedad de su usuario para paquetes npm
chown -R SU_NOMBRE_USUARIO:SU_NOMBRE_USUARIO /usr/local

# Configure el 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

# Arregle la configuración de 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 los paquetes afectados (opcional pero recomendado):

    # Guarde la lista de paquetes instalados
dpkg --get-selections > /tmp/installed_packages.txt

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

  8. Reinicie:

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

Si el modo de recuperación no funciona, puede usar un USB Live:

  1. Arranque desde un USB Live (Ubuntu, Debian o cualquier distribución Linux)

  2. Encuentre su partición del sistema:

    lsblk

  3. Monte su partición del sistema:

    sudo mount /dev/sdXY /mnt  # reemplace sdXY con su partición del sistema real

  4. Si tiene una partición de arranque separada, móntela también:

    sudo mount /dev/sdXZ /mnt/boot  # si es necesario

  5. Haga chroot en su sistema:

    # Para Ubuntu/Debian:
sudo chroot /mnt

# Para sistemas basados en Arch:
sudo arch-chroot /mnt

  6. Siga los pasos 6-8 del método de recuperación de Ubuntu/Debian anterior

Después de restaurar su sistema, siga la solución recomendada anterior para configurar un prefijo npm con permisos de escritura para el usuario.

​
Problemas con el actualizador automático

Si Claude Code no puede actualizarse automáticamente, puede deberse a problemas de permisos con el directorio de prefijo global de npm. Siga la solución recomendada anterior para solucionar esto.

Si prefiere deshabilitar el actualizador automático en su lugar, puede usar:

claude config set -g autoUpdaterStatus disabled

​
Permisos y autenticación

​
Solicitudes repetidas de permisos

Si se encuentra aprobando repetidamente los mismos comandos, puede permitir que herramientas específicas se ejecuten sin aprobación:

# Permitir que npm test se ejecute sin aprobación
claude config add allowedTools "Bash(npm test)"

# Permitir que npm test y cualquiera de sus subcomandos se ejecuten sin aprobación
claude config add allowedTools "Bash(npm test:*)"

​
Problemas de autenticación

Si está experimentando problemas de autenticación:

  1. Ejecute /logout para cerrar sesión completamente
  2. Cierre Claude Code
  3. Reinicie con claude y complete el proceso de autenticación nuevamente

Si los problemas persisten, intente:

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

Esto elimina su 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 los entornos de desarrollo, pero puede consumir recursos significativos al procesar bases de código grandes. Si está experimentando problemas de rendimiento:

  1. Use /compact regularmente para reducir el tamaño del contexto
  2. Cierre y reinicie Claude Code entre tareas importantes
  3. Considere agregar directorios de compilación grandes a su archivo .gitignore

​
Comandos que se cuelgan o se congelan

Si Claude Code parece no responder:

  1. Presione Ctrl+C para intentar cancelar la operación actual
  2. Si no responde, es posible que necesite cerrar la terminal y reiniciar

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

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

Para solucionar este problema:

  1. Vaya a Configuración → Herramientas → Terminal
  2. Haga clic en el hipervínculo “Configurar atajos de teclado de terminal” junto a “Anular atajos de IDE”
  3. Dentro de los atajos de teclado de terminal, desplácese hacia abajo hasta “Cambiar el foco al Editor” y elimine 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 el foco al Editor” de PyCharm.

​
Obtener más ayuda

Si está experimentando problemas no cubiertos aquí:

  1. Use el comando /bug dentro de Claude Code para reportar problemas directamente a Anthropic
  2. Revise el repositorio de GitHub para problemas conocidos
  3. Ejecute /doctor para verificar la salud de su instalación de Claude Code

Was this page helpful?

Tutoriales