Saltar al contenido principal

​
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:
  • Ejecuta npm config set os linux antes de la instalación
  • Instala 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 comienzan con /usr/ en lugar de /mnt/c/. Para solucionar esto, intenta instalar Node a través del gestor de paquetes de tu distribución de 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 ocurre 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 por:
  • Ejecutar which npm y which node - si apuntan a rutas de Windows (comenzando con /mnt/c/), se están usando versiones de Windows
  • Experimentar 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: Asegúrate de que nvm se cargue correctamente en tu shell La causa más común es que nvm no se carga en shells no interactivos. Añade lo siguiente a tu archivo de configuración de shell (~/.bashrc, ~/.zshrc, etc.): 
# Load nvm if it exists
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
O ejecuta directamente en tu sesión actual: 
source ~/.nvm/nvm.sh
Alternativa: Ajusta el orden de PATH Si nvm se carga correctamente pero las rutas de Windows aún tienen prioridad, puedes anteponer explícitamente tus rutas de Linux a PATH en tu configuración de shell: 
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
Evita desactivar la importación de PATH de Windows (appendWindowsPath = false) ya que esto rompe la capacidad de llamar fácilmente a ejecutables de Windows desde WSL. De manera similar, evita desinstalar Node.js de Windows si lo usas para desarrollo de 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 podrías encontrar errores de permisos si tu prefijo global de npm no es escribible por el usuario (por ejemplo, /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 actualmente está en beta.
Usa el siguiente comando para ejecutar el instalador nativo. macOS, Linux, WSL: 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell: 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([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 añade un enlace simbólico a la instalación en ~/.local/bin/claude.
Asegúrate de que tengas 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: 
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  # Should show an alias to ~/.claude/local/claude
En Windows: 
where claude  # Should show path to claude executable
Verifica la instalación: 
claude doctor # Check installation health

​
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 funcionar 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 principales
  3. Considera añadir directorios de compilación grandes a tu archivo .gitignore

​
El comando se cuelga o 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

​
Problemas de búsqueda y descubrimiento

Si la herramienta de Búsqueda, menciones @file, agentes personalizados y comandos de barra diagonal 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 entre 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. Envía búsquedas más específicas: Reduce el número de archivos buscados especificando directorios o tipos de archivo: “Busca lógica de validación JWT en el paquete auth-service” o “Encuentra uso de hash md5 en archivos JS”.
  2. Mueve el proyecto al sistema de archivos de Linux: Si es posible, asegúrate de que tu proyecto esté ubicado en el sistema de archivos de Linux (/home/) en lugar del sistema de archivos de Windows (/mnt/c/).
  3. Usa Windows nativo en su lugar: Considera ejecutar Claude Code de forma nativa en Windows en lugar de a través de WSL, para mejor rendimiento del sistema de archivos.

​
Problemas de integración de IDE

​
IDE de JetBrains no detectado en WSL2

Si estás usando Claude Code en WSL2 con IDEs de JetBrains y obtienes errores “No available IDEs detected”, esto probablemente se debe a la configuración de red de WSL2 o al Firewall de Windows bloqueando la conexión.

​
Modos de red de WSL2

WSL2 usa redes NAT por defecto, lo que puede prevenir la detección de IDE. Tienes dos opciones: Opción 1: Configura el Firewall de Windows (recomendado)
  1. Encuentra tu dirección IP de WSL2: 
    wsl hostname -I
# Example output: 172.21.123.456
  2. Abre PowerShell como Administrador y crea una regla de firewall: 
    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
    (Ajusta el rango de IP basado en tu subred de WSL2 del paso 1)
  3. Reinicia tanto tu IDE como Claude Code
Opción 2: Cambia a redes espejadas Añade a .wslconfig en tu directorio de usuario de Windows: 
[wsl2]
networkingMode=mirrored
Luego reinicia WSL con wsl --shutdown desde PowerShell.
Estos problemas de red solo afectan a WSL2. WSL1 usa la red del host directamente y no requiere estas configuraciones.
Para consejos de configuración adicionales de JetBrains, ver nuestra guía de integración de IDE.

​
Reportar problemas de integración de IDE en Windows (nativo y WSL)

Si estás experimentando problemas de integración de IDE en Windows, por favor crea un problema con la siguiente información: si eres nativo (git bash), o WSL1/WSL2, modo de red de WSL (NAT o espejado), nombre/versión del IDE, versión de extensión/plugin de Claude Code, y tipo de shell (bash/zsh/etc)

​
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 espera, esto probablemente se debe a un conflicto de vinculación de teclas con los atajos por defecto de JetBrains. Para solucionar este problema:
  1. Ve a Settings → Tools → Terminal
  2. Ya sea:
    • Desmarca “Move focus to the editor with Escape”, o
    • Haz clic en “Configure terminal keybindings” y elimina el atajo “Switch focus to Editor”
  3. Aplica los cambios
Esto permite que la tecla ESC interrumpa correctamente las operaciones de Claude Code.

​
Problemas de formato de Markdown

Claude Code a veces genera archivos markdown con etiquetas de lenguaje faltantes en cercas 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. Pide a Claude que añada etiquetas de lenguaje: Simplemente solicita “Please add appropriate language tags to all code blocks in this markdown file.”
  2. Usa ganchos de post-procesamiento: Configura ganchos de formato automático para detectar y añadir etiquetas de lenguaje faltantes. Ver el ejemplo de gancho de formato de markdown para detalles de implementación.
  3. Verificación manual: Después de generar archivos markdown, revísalos para formato correcto de bloques de código y solicita correcciones si es necesario.

​
Espaciado e formato inconsistentes

Si el markdown generado tiene líneas en blanco excesivas o espaciado inconsistente: Soluciones:
  1. Solicita correcciones de formato: Pide a Claude que “Fix spacing and formatting issues in this markdown file.”
  2. Usa herramientas de formato: Configura ganchos para ejecutar formateadores de markdown como prettier o scripts de formato personalizados en archivos markdown generados.
  3. Especifica preferencias de formato: Incluye requisitos de formato en tus indicaciones o archivos de memoria del proyecto.

​
Mejores prácticas para generación de Markdown

Para minimizar problemas de formato:
  • Sé explícito en solicitudes: Pide “properly formatted markdown with language-tagged code blocks”
  • Usa convenciones del proyecto: Documenta tu estilo de markdown preferido en CLAUDE.md
  • Configura ganchos de validación: Usa ganchos de post-procesamiento para verificar y corregir automáticamente problemas de formato comunes

​
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. Verifica el repositorio de GitHub para problemas conocidos
  3. Ejecuta /doctor para verificar la salud de tu instalación de Claude Code
  4. Pregunta a Claude directamente sobre sus capacidades y características - Claude tiene acceso integrado a su documentación