​
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 uses sudo)

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 administrador de paquetes de tu distribución Linux o a través de nvm.

Conflictos de versión de nvm: Si tienes nvm instalado tanto en WSL como en Windows, podrías experimentar conflictos de versión al cambiar versiones de Node en WSL. Esto sucede porque WSL importa el PATH de Windows por defecto, causando que nvm/npm de Windows tenga prioridad sobre la instalación de WSL.

Puedes identificar este problema:

  • Ejecutando which npm y which node - si apuntan a rutas de Windows (que comienzan con /mnt/c/), se están usando las versiones de Windows
  • Experimentando funcionalidad rota después de cambiar versiones de Node con nvm en WSL

Para resolver este problema, corrige tu PATH de Linux para asegurar que las versiones de node/npm de Linux tengan prioridad:

Solución principal: Asegurar que nvm esté cargado correctamente en tu shell

La causa más común es que nvm no está cargado en shells no interactivos. Agrega lo siguiente a tu archivo de configuración de shell (~/.bashrc, ~/.zshrc, etc.):

# Cargar nvm si existe
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

O ejecutar directamente en tu sesión actual:

source ~/.nvm/nvm.sh

Alternativa: Ajustar el orden del PATH

Si nvm está cargado correctamente pero las rutas de Windows aún tienen prioridad, puedes anteponer explícitamente tus rutas de Linux al PATH en tu configuración de shell:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Evita deshabilitar la importación del PATH de Windows (appendWindowsPath = false) ya que esto rompe la capacidad de llamar fácilmente ejecutables de Windows desde WSL. De manera similar, evita desinstalar Node.js de Windows si lo usas para desarrollo en Windows.

​
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 prevenir 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:

# Instalar versión estable (por defecto)
curl -fsSL https://claude.ai/install.sh | bash

# Instalar última versión
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Instalar número de versión específico
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

# Instalar versión estable (por defecto)
irm https://claude.ai/install.ps1 | iex

# Instalar última versión
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Instalar número de versión específico
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Este comando instala la compilación apropiada de Claude Code para tu sistema operativo y arquitectura y agrega 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 funciona, puedes migrar a una instalación local:

claude migrate-installer

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:

which claude  # Debería mostrar un alias a ~/.claude/local/claude

En Windows:

where claude  # Debería mostrar la ruta al ejecutable claude

Verificar instalación:

claude doctor # Verificar la salud de la 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:

  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 compilació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, 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 por defecto de JetBrains.

Para solucionar 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.

​
Problemas de búsqueda y descubrimiento

Si la herramienta de Búsqueda, menciones @file, agentes personalizados y comandos de barra personalizados no funcionan, instala ripgrep del sistema:

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

Luego establece USE_BUILTIN_RIPGREP=0 en tu entorno.

​
Resultados de búsqueda lentos o incompletos en WSL

Las penalizaciones de rendimiento de lectura de disco al trabajar a través de sistemas de archivos en WSL pueden resultar en menos coincidencias de las esperadas (pero no una falta completa de funcionalidad de búsqueda) al usar Claude Code en WSL.

/doctor mostrará Búsqueda como OK en este caso.

Soluciones:

  1. Enviar búsquedas más específicas: Reduce el número de archivos buscados especificando directorios o tipos de archivo: “Buscar lógica de validación JWT en el paquete auth-service” o “Encontrar uso de hash md5 en archivos JS”.

  2. Mover proyecto al sistema de archivos Linux: Si es posible, asegúrate de que tu proyecto esté ubicado en el sistema de archivos Linux (/home/) en lugar del sistema de archivos Windows (/mnt/c/).

  3. Usar Windows nativo en su lugar: Considera ejecutar Claude Code nativamente en Windows en lugar de a través de WSL, para mejor rendimiento del sistema de archivos.

​
Problemas de formato de Markdown

Claude Code a veces genera archivos markdown con etiquetas de lenguaje faltantes en los bloques de código, lo que puede afectar el resaltado de sintaxis y la legibilidad en GitHub, editores y herramientas de documentación.

​
Etiquetas de lenguaje faltantes en bloques de código

Si notas bloques de código como este en markdown generado:

```
function example() {
  return "hello";
}
```

En lugar de bloques correctamente etiquetados como:

```javascript
function example() {
  return "hello";
}
```

Soluciones:

  1. Pedir a Claude que agregue etiquetas de lenguaje: Simplemente solicita “Por favor agrega etiquetas de lenguaje apropiadas a todos los bloques de código en este archivo markdown.”

  2. Usar hooks de post-procesamiento: Configura hooks de formato automático para detectar y agregar etiquetas de lenguaje faltantes. Ver el ejemplo de hook de formato markdown para detalles de implementación.

  3. Verificación manual: Después de generar archivos markdown, revísalos para formato apropiado de bloques de código y solicita correcciones si es necesario.

​
Espaciado y formato inconsistente

Si el markdown generado tiene líneas en blanco excesivas o espaciado inconsistente:

Soluciones:

  1. Solicitar correcciones de formato: Pide a Claude que “Corrija problemas de espaciado y formato en este archivo markdown.”

  2. Usar herramientas de formato: Configura hooks para ejecutar formateadores de markdown como prettier o scripts de formato personalizados en archivos markdown generados.

  3. Especificar preferencias de formato: Incluye requisitos de formato en tus prompts o archivos de memoria del proyecto.

​
Mejores prácticas para generación de markdown

Para minimizar problemas de formato:

  • Ser explícito en las solicitudes: Pide “markdown correctamente formateado con bloques de código etiquetados por lenguaje”
  • Usar convenciones del proyecto: Documenta tu estilo de markdown preferido en CLAUDE.md
  • Configurar hooks de validación: Usa hooks de post-procesamiento para verificar y corregir automáticamente problemas comunes de formato

​
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
  4. Pregunta directamente a Claude sobre sus capacidades y características - Claude tiene acceso incorporado a su documentación