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 instalación en Windows: errores en WSL
Podrías encontrar los siguientes problemas en WSL:
Problemas de detección de SO/plataforma: Si recibes un error durante la instalación, WSL podría estar usando npm
de Windows. Intenta:
- Ejecutar
npm config set os linux
antes de la instalación - Instalar con
npm install -g @anthropic-ai/claude-code --force --no-os-check
(NO usessudo
)
Errores de node no encontrado: Si ves exec: node: not found
al ejecutar claude
, tu entorno WSL podría estar usando una instalación de Node.js de Windows. Puedes confirmar esto con which npm
y which node
, que deberían apuntar a rutas de Linux que comiencen con /usr/
en lugar de /mnt/c/
. Para solucionarlo, intenta instalar Node a través del gestor de paquetes de tu distribución Linux o a través de nvm
.
Problemas de instalación en Linux y Mac: errores de permisos o comando no encontrado
Al instalar Claude Code con npm, los problemas de PATH
pueden impedir el acceso a claude
.
También 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: Instalación nativa de Claude Code
Claude Code tiene una instalación nativa que no depende de npm o Node.js.
El instalador nativo de Claude Code está actualmente en beta.
Usa el siguiente comando para ejecutar el instalador nativo.
macOS, Linux, WSL:
Windows PowerShell:
Este comando instala la compilación apropiada de Claude Code para tu sistema operativo y arquitectura y añade un enlace simbólico a la instalación en ~/.local/bin/claude
.
Asegúrate de tener el directorio de instalación en tu PATH del sistema.
Solución alternativa: Migrar a instalación local
Alternativamente, si Claude Code se ejecuta, puedes migrar a una instalación local:
Esto mueve Claude Code a ~/.claude/local/
y configura un alias en tu configuración de shell. No se requiere sudo
para futuras actualizaciones.
Después de la migración, reinicia tu shell, y luego verifica tu instalación:
En macOS/Linux/WSL:
En Windows:
Verificar instalación:
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 añadir directorios de compilació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, podrías necesitar cerrar la terminal y reiniciar
La tecla ESC no funciona en terminales de JetBrains (IntelliJ, PyCharm, etc.)
Si estás usando Claude Code en terminales de 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 solucionar este problema:
- Ve a Configuración → Herramientas → Terminal
- Haz clic en el hipervínculo “Configure terminal keybindings” junto a “Override IDE Shortcuts”
- Dentro de las combinaciones de teclas del terminal, desplázate hacia abajo hasta “Switch focus to 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 “Switch focus to 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 - Pregunta directamente a Claude sobre sus capacidades y características - Claude tiene acceso integrado a su documentación