La mayoría de los fallos de Claude Code caen en tres categorías: problemas de instalación, errores de autenticación o conflictos específicos del entorno. Ejecuta claude doctor primero — diagnostica automáticamente la mayoría de los problemas en segundos. Si Claude Code no arranca en absoluto, salta a la sección de instalación más abajo.
Instalas Claude Code, npm dice que todo salió bien, pero claude devuelve "command not found" — es una de las quejas más comunes en Reddit y GitHub Issues. Desde errores de autenticación hasta conflictos de rutas en WSL y crashes por ventana de contexto, esta guía cubre las soluciones para cada patrón de fallo importante.
¿Qué Debo Hacer Primero Cuando Claude Code No Arranca?
Antes de entrar en soluciones específicas, deja que Claude Code intente diagnosticar el problema por sí mismo.
claude doctor
Este comando verifica automáticamente:
- Compatibilidad de la versión de Node.js
- Validez del token de autenticación
- Conectividad de red
- Integridad de archivos de configuración (validación JSON)
- Errores en la configuración de servidores MCP
Cualquier ✗ en la salida apunta directamente a la causa raíz. Copia el mensaje de error tal cual y búscalo — casi seguro alguien ya lo resolvió antes.
Si claude no arranca en absoluto, doctor no está disponible. Trátalo como un problema de instalación y pasa a la siguiente sección.
Algo más que vale la pena verificar temprano: la página de estado de Anthropic. Si la API está experimentando una caída, ningún troubleshooting local va a ayudar.
¿Cómo Soluciono Fallos de Instalación de Claude Code?
Usa el Instalador Nativo (Recomendado)
Antes de pelear con problemas de npm, considera cambiar al instalador nativo. Desde finales de 2025, Anthropic recomienda este método sobre npm — es un ejecutable autocontenido con cero dependencias (no necesita Node.js ni npm) y se actualiza automáticamente en segundo plano.
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
Después de la instalación, verifica con claude --version. Si estás migrando desde una instalación por npm, desinstala primero la versión de npm para evitar conflictos:
npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash
El instalador nativo elimina la mayoría de los problemas relacionados con npm que se describen a continuación. Si aún necesitas el método npm (pipelines de CI, entornos corporativos con acceso restringido a curl, etc.), sigue leyendo.
Patrón 1: Error de Permisos en Instalación Global de npm
npm warn logfile Error: EACCES: permission denied
Esto sucede cuando npm no puede escribir en el directorio global. sudo npm install -g funciona como solución rápida, pero tiende a crear otros dolores de cabeza con permisos más adelante. El enfoque más limpio es mover el directorio global de npm a tu carpeta home.
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code
Patrón 2: Versión de Node.js Desactualizada
Claude Code requiere Node.js 18 o superior. Verifica tu versión primero.
node --version
Si estás por debajo de 18, cambia con nvm.
# Instalar o actualizar nvm (v0.40.4 a marzo de 2026)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22
Patrón 3: npm install Se Cuelga
Común en entornos con proxy o redes corporativas. Agrega --verbose para ver dónde se atasca el proceso.
npm install -g @anthropic-ai/claude-code --verbose
Si es un timeout, aumenta el tiempo de espera de fetch de npm.
npm config set fetch-timeout 600000
Patrón 4: Bloqueo por Proxy Corporativo o Firewall
Detrás de un proxy corporativo, npm y Claude Code pueden fallar al intentar alcanzar servidores externos. Configura el proxy para npm, y si tu empresa usa un certificado CA personalizado, indícaselo a Node.js.
# Configurar proxy de npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
# Si tu empresa usa un certificado CA personalizado
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.crt
Agrega la línea NODE_EXTRA_CA_CERTS a .bashrc para hacerla permanente.
Patrón 5: Conflictos por Múltiples Instalaciones
Si has instalado Claude Code varias veces (globalmente, localmente, con diferentes versiones de Node), los conflictos de versiones pueden causar comportamientos extraños.
# Verificar múltiples instalaciones
which -a claude
npm ls -g @anthropic-ai/claude-code
# Instalación limpia: desinstalar y reinstalar
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
¿Por Qué Recibo Errores de Autenticación 401 o 403?
Los errores de autenticación son la primera barrera que la mayoría encuentra después de una instalación exitosa.
401 Unauthorized: La clave de API es inválida o ha expirado. Verifica tu clave en la Consola de Anthropic.
403 Forbidden: Tu plan no incluye acceso a Claude Code, o la clave de API no tiene los permisos necesarios.
Claude Code está disponible en estos planes:
- Pro ($20/mes) — incluye Claude Code
- Max 5x ($100/mes) — acceso completo
- Max 20x ($200/mes) — acceso completo
- Team Premium ($150/persona/mes) — incluye Claude Code
- Clave de API — facturación por uso desde la Consola de Anthropic
Para restablecer la autenticación:
# Eliminar credenciales existentes
claude auth logout
# Re-autenticarse
claude auth login
Si el navegador no se abre automáticamente (común en servidores remotos o entornos headless), presiona c para copiar la URL de OAuth al portapapeles. Pégala manualmente en tu navegador para completar la autenticación.
También puedes establecer la clave de API directamente como variable de entorno.
export ANTHROPIC_API_KEY="sk-ant-..."
Agrégala a .bashrc o .zshrc para hacerla permanente.
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc
Si el 403 persiste después de re-autenticarte, ejecuta claude auth status para verificar tu estado de autenticación actual. Si todo se ve correcto de tu lado, contacta al soporte de Anthropic.
¿Qué Causa que Claude Code Falle en WSL?
WSL (Subsistema de Windows para Linux) introduce su propio conjunto de problemas. Si usas Claude Code sobre WSL2, los siguientes problemas aparecen con frecuencia en GitHub Issues y foros de la comunidad.
npm de Windows Filtrándose en WSL
Ejecuta which npm dentro de WSL. Si la ruta empieza con /mnt/c/..., estás llamando al npm del lado de Windows — no el de Linux. Instala Node.js por separado dentro de WSL.
# Instalar nvm dentro de WSL (v0.40.4 a marzo de 2026)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
La Autenticación del Navegador No Se Abre
claude auth login intenta abrir un navegador, pero en WSL a menudo el navegador predeterminado no se lanza. Cuando esto pase, presiona c para copiar la URL de OAuth al portapapeles y pégala en tu navegador de Windows.
Establecer la clave de API directamente vía variable de entorno (ve la sección de autenticación arriba) también funciona de forma confiable.
Problemas de Rutas y Rendimiento
Trabajar con archivos del lado de Windows (/mnt/c/...) desde WSL causa una degradación importante del rendimiento. Mantén tus proyectos de Claude Code dentro del sistema de archivos de WSL (~/) para mejores resultados.
# Bien: sistema de archivos nativo de WSL
cd ~/projects/my-app
# Lento: sistema de archivos de Windows montado en WSL
cd /mnt/c/Users/username/projects/my-app
Para un análisis más profundo de problemas de conexión específicos de WSL, consulta Solucionar Desconexiones de Claude Code en WSL2.
Configuración del Sandbox en WSL2
La función sandbox de Claude Code requiere bubblewrap y socat en WSL2. Si ves errores relacionados con sandbox:
sudo apt install bubblewrap socat
Cambiar a Windows Nativo
Si los problemas de WSL se resisten, Claude Code también funciona nativamente en Windows vía PowerShell. Pero para la mayoría del trabajo de desarrollo, WSL es el mejor entorno una vez correctamente configurado. Solo recurre a Windows nativo si realmente estás atascado.
# PowerShell
npm install -g @anthropic-ai/claude-code
¿Qué Problemas Son Específicos de macOS?
macOS generalmente tiene menos problemas que WSL, pero hay un par de trampas.
Conflictos entre Homebrew y nvm para Node.js
Si instalaste Node.js con Homebrew y también usas nvm, pueden entrar en conflicto. Verifica cuál node está activo:
which node
# Homebrew: /opt/homebrew/bin/node
# nvm: /Users/username/.nvm/versions/node/v22.x.x/bin/node
Elige uno y quédate con él. Si usas nvm, asegúrate de que el Node de Homebrew no lo esté sobreescribiendo:
brew uninstall node
Problemas con Keychain y Credenciales
En macOS, Claude Code puede almacenar credenciales en el Keychain del sistema. Si la autenticación se comporta de forma extraña después de una actualización del SO o cambio de contraseña, resetea las credenciales almacenadas:
claude auth logout
claude auth login
Si eso no funciona, abre Acceso a Llaveros (en Aplicaciones > Utilidades) y busca entradas relacionadas con Claude. Elimínalas manualmente antes de volver a iniciar sesión.
Compatibilidad con Apple Silicon (M1/M2/M3/M4)
Claude Code funciona de forma nativa en Apple Silicon — no necesita Rosetta. Si usas el instalador nativo, detecta la arquitectura automáticamente. Si usas el método npm, asegúrate de estar ejecutando un Node.js nativo para ARM (no una versión x86 a través de Rosetta), ya que esto puede causar problemas sutiles de rendimiento.
# Verificar que tienes Node.js ARM
node -p "process.arch"
# Debería mostrar: arm64
¿Cómo Soluciono "claude: command not found"?
Si la instalación se completó pero el comando no se encuentra, el directorio del binario simplemente no está en tu PATH.
Primero, encuentra dónde lo instaló npm.
npm root -g
El binario claude está en la carpeta bin/ un nivel arriba de esa ruta.
# Ejemplo: si npm root es /usr/local/lib/node_modules, verifica /usr/local/bin
ls $(npm prefix -g)/bin/claude
Si el archivo existe, agrega su directorio al PATH.
echo "export PATH=\"$(npm prefix -g)/bin:\$PATH\"" >> ~/.bashrc
source ~/.bashrc
Si personalizaste el prefix de npm (como se recomendó en la sección de instalación), usa esa ruta.
npm config get prefix
# Salida de ejemplo: /home/username/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Abre una nueva sesión de shell o ejecuta source ~/.bashrc después de hacer el cambio. Esto soluciona el problema en la gran mayoría de los casos.
¿Cómo Diagnosticar Rendimiento Lento?
Cuando las respuestas de Claude Code se vuelven anormalmente lentas, la causa generalmente cae en una de tres categorías.
1. Ventana de Contexto Sobrecargada
Las sesiones largas llenan la ventana de contexto, lo que degrada la calidad y velocidad de las respuestas. Verifica el uso actual de tokens con /cost.
Si supera el 80%, comprime con /compact o inicia de nuevo con /clear. Para estrategias de gestión proactiva del contexto, consulta Cómo Reduje el Consumo de Tokens de Claude Code en un 50% y Solucionar Error de Ventana de Contexto Excedida.
2. Sobrecarga de Servidores MCP
Demasiados servidores MCP añaden latencia a cada llamada de herramienta. Desactiva los que no uses a través de la UI de Claude Code — presiona @ para ver los servidores conectados y desactívalos.
También puedes verificar el estado de los servidores MCP con claude doctor, que reporta cualquier servidor que esté fallando o respondiendo lento.
3. Problemas de Red o del Lado de la API
Los tiempos de respuesta de la API de Anthropic varían con la carga del servidor. Verifica la página de estado primero. Luego ejecuta claude doctor para verificar la conectividad con la API desde tu máquina.
claude doctor
¿Qué Hacer Cuando Nada Más Funciona?
Si nada de lo anterior resolvió el problema, recopila logs y escala.
Recopilar Información de Depuración
# Ejecutar con logging detallado (muestra llamadas a herramientas e interacciones API)
claude --verbose 2>&1 | tee claude-verbose.log
# Para trazado más profundo a nivel de protocolo (depuración de MCP)
claude --debug --mcp-debug 2>&1 | tee claude-debug.log
# Recopilar información del entorno
node --version
npm --version
claude --version
uname -a
echo $SHELL
echo $PATH
claude auth status
Reportar en GitHub Issues
Los bugs de Claude Code se rastrean en el repositorio oficial. Antes de abrir un issue nuevo:
- Busca issues existentes — tu problema puede que ya tenga solución
- Incluye: SO, versión de Node.js, mensaje de error y log de depuración
- Agrega pasos de reproducción claros
GitHub Issues llega al equipo de desarrollo de forma más confiable que los foros comunitarios. La documentación oficial de troubleshooting también vale la pena revisarla — se actualiza frecuentemente.
FAQ
¿Funciona Claude Code en el plan gratuito?
No. Claude Code requiere un plan de pago — Pro ($20/mes), Max ($100–200/mes) o Team Premium ($150/persona/mes). También puedes usarlo con una clave de API directa desde la Consola de Anthropic, que se factura por uso.
¿Qué versión de Node.js necesita Claude Code?
Si usas el instalador nativo, no necesitas Node.js en absoluto. Para el método de instalación por npm, necesitas Node.js 18 o superior — recomiendo Node.js 22 LTS para mejor compatibilidad. Usa nvm para gestionar versiones.
¿Debería usar el instalador nativo o npm?
Usa el instalador nativo a menos que tengas una razón específica para no hacerlo. Es el método recomendado por Anthropic desde finales de 2025 — cero dependencias, actualizaciones automáticas y elimina la mayoría de los problemas de instalación. El método npm sigue funcionando pero requiere Node.js 18+ y actualizaciones manuales.
¿Cómo verifico si la API de Anthropic está caída?
Visita la página de estado de Anthropic. Si la API está experimentando problemas, el troubleshooting local no va a ayudar — espera a que el servicio se recupere.
¿Puedo usar Claude Code detrás de un proxy corporativo?
Sí. Configura npm config set proxy y npm config set https-proxy para la instalación, y NODE_EXTRA_CA_CERTS para certificados CA personalizados. Consulta la sección de instalación para más detalles.
¿Por qué Claude Code se sigue desconectando en WSL2?
Generalmente causado por la capa de networking de WSL2, ciclos de suspensión/despertar, o presión de memoria del proceso vmmem. Consulta la guía dedicada: Solucionar Desconexiones de Claude Code en WSL2.
¿Cómo reseteo Claude Code completamente?
Elimina credenciales, limpia la caché y reinstala:
claude auth logout
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude
npm install -g @anthropic-ai/claude-code
claude auth login
¿Cuál es la diferencia entre claude doctor, --verbose y --debug?
Sirven para cosas distintas. claude doctor ejecuta un chequeo rápido de salud (versión de Node, autenticación, red, configuración MCP). claude --verbose inicia Claude Code con logging expandido que muestra llamadas a herramientas e interacciones API — útil para entender qué está pasando durante una sesión. claude --debug habilita trazado más profundo a nivel de protocolo, y --mcp-debug añade diagnósticos específicos de MCP encima de eso.
¿Cómo uso Claude Code en un servidor remoto sin navegador?
Establece la clave de API como variable de entorno en lugar de usar el login basado en navegador:
export ANTHROPIC_API_KEY="sk-ant-..."
O usa claude auth login y presiona c para copiar la URL de OAuth, luego ábrela en cualquier dispositivo con navegador.
Conclusión
Casi todos los problemas de Claude Code caen en una de tres categorías:
- Problemas de instalación: Versión de Node.js, permisos de npm, configuración del PATH, configuración de proxy
- Problemas de autenticación: Validez de la clave de API, plan de suscripción, variables de entorno
- Problemas específicos del entorno: Conflictos WSL/Windows, resolución de rutas, dependencias del sandbox
Acostúmbrate a ejecutar claude doctor primero — acelera dramáticamente el diagnóstico. Y antes de pasar una hora debuggeando, revisa la página de estado de Anthropic para descartar una caída del servicio.
Una vez que la configuración esté completa, el siguiente paso es escribir un archivo CLAUDE.md para darle a Claude Code contexto específico de tu proyecto. Ahí es donde empiezan las verdaderas ganancias de productividad. Si manejas múltiples proyectos, la guía de múltiples instancias explica cómo gestionar sesiones paralelas de forma efectiva. Y si estás evaluando alternativas, consulta las comparaciones Claude Code vs Cursor y Claude Code vs GitHub Copilot.