Solución de problemas
Descubre soluciones a problemas comunes con la instalación y uso de Claude Code.
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:
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:
-
Mientras reinicias, mantén presionado SHIFT para acceder al menú GRUB
-
Selecciona “Opciones avanzadas para Ubuntu/Debian”
-
Elige la opción de modo de recuperación
-
Selecciona “Ir al prompt de shell root”
-
Remonta el sistema de archivos como escribible:
-
Corrige permisos:
-
Reinstala paquetes afectados (opcional pero recomendado):
-
Reinicia:
Método alternativo de recuperación con USB en vivo:
Si el modo de recuperación no funciona, puedes usar un USB en vivo:
-
Inicia desde un USB en vivo (Ubuntu, Debian, o cualquier distribución Linux)
-
Encuentra tu partición del sistema:
-
Monta tu partición del sistema:
-
Si tienes una partición de arranque separada, móntala también:
-
Haz chroot a tu sistema:
-
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:
- Ejecuta
/logout
para cerrar sesión completamente - Cierra Claude Code
- Reinicia con
claude
y completa el proceso de autenticación nuevamente
Si los problemas persisten, intenta:
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:
- Usa
/compact
regularmente para reducir el tamaño del contexto - Cierra y reinicia Claude Code entre tareas importantes
- Considera agregar directorios de construcción grandes a tu archivo
.gitignore
El comando se cuelga o se congela
Si Claude Code parece no responder:
- Presiona Ctrl+C para intentar cancelar la operación actual
- 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:
- Ve a Configuración → Herramientas → Terminal
- Haz clic en el hipervínculo “Configurar combinaciones de teclas del terminal” junto a “Anular atajos del IDE”
- 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í:
- Usa el comando
/bug
dentro de Claude Code para reportar problemas directamente a Anthropic - Revisa el repositorio de GitHub para problemas conocidos
- Ejecuta
/doctor
para verificar la salud de tu instalación de Claude Code