Solucionar problemas de instalación
Si prefieres evitar la terminal por completo, la aplicación de escritorio Claude Code te permite instalar y usar Claude Code a través de una interfaz gráfica. Descárgala para macOS o Windows y comienza a codificar sin ninguna configuración de línea de comandos. | Lo que ves | Solución |
|---|
command not found: claude o 'claude' is not recognized | Corrige tu PATH |
syntax error near unexpected token '<' | El script de instalación devuelve HTML |
curl: (56) Failure writing output to destination | Descarga el script primero, luego ejecútalo |
Killed durante la instalación en Linux | Añade espacio de intercambio para servidores con poca memoria |
TLS connect error o SSL/TLS secure channel | Actualiza los certificados CA |
Failed to fetch version o no se puede alcanzar el servidor de descarga | Verifica la conectividad de red y la configuración del proxy |
irm is not recognized o && is not valid | Usa el comando correcto para tu shell |
Claude Code on Windows requires git-bash | Instala o configura Git Bash |
Error loading shared library | Variante binaria incorrecta para tu sistema |
Illegal instruction en Linux | Desajuste de arquitectura |
dyld: cannot load o Abort trap en macOS | Incompatibilidad binaria |
Invoke-Expression: Missing argument in parameter list | El script de instalación devuelve HTML |
App unavailable in region | Claude Code no está disponible en tu país. Consulta países compatibles. |
unable to get local issuer certificate | Configura certificados CA corporativos |
OAuth error o 403 Forbidden | Corrige la autenticación |
Depurar problemas de instalación
Verifica la conectividad de red
El instalador descarga desde storage.googleapis.com. Verifica que puedas alcanzarlo:
curl -sI https://storage.googleapis.com
- Firewalls corporativos o proxies bloqueando Google Cloud Storage
- Restricciones de red regional: intenta usar una VPN o una red alternativa
- Problemas de TLS/SSL: actualiza los certificados CA de tu sistema, o verifica si
HTTPS_PROXY está configurado
Si estás detrás de un proxy corporativo, establece HTTPS_PROXY y HTTP_PROXY a la dirección de tu proxy antes de instalar. Pregunta a tu equipo de TI por la URL del proxy si no la conoces, o verifica la configuración del proxy en tu navegador.
Este ejemplo establece ambas variables de proxy, luego ejecuta el instalador a través de tu proxy:
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
Verifica tu PATH
Si la instalación fue exitosa pero obtienes un error command not found o not recognized al ejecutar claude, el directorio de instalación no está en tu PATH. Tu shell busca programas en directorios listados en PATH, y el instalador coloca claude en ~/.local/bin/claude en macOS/Linux o %USERPROFILE%\.local\bin\claude.exe en Windows.
Verifica si el directorio de instalación está en tu PATH listando tus entradas de PATH y filtrando por local/bin:
macOS/Linux
Windows PowerShell
Windows CMD
echo $PATH | tr ':' '\n' | grep local/bin
# Zsh (macOS por defecto)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Bash (Linux por defecto)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
$env:PATH -split ';' | Select-String 'local\\bin'
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
echo %PATH% | findstr /i "local\bin"
%USERPROFILE%\.local\bin a tu variable PATH de usuario. Reinicia tu terminal.Verifica que la corrección funcionó:Verifica instalaciones conflictivas
Múltiples instalaciones de Claude Code pueden causar desajustes de versión o comportamiento inesperado. Verifica qué está instalado:
macOS/Linux
Windows PowerShell
Lista todos los binarios claude encontrados en tu PATH:Verifica si las versiones del instalador nativo y npm están presentes:ls -la ~/.local/bin/claude
npm -g ls @anthropic-ai/claude-code 2>/dev/null
where.exe claude
Test-Path "$env:LOCALAPPDATA\Claude Code\claude.exe"
~/.local/bin/claude es recomendada. Elimina cualquier instalación adicional:
Desinstala una instalación global de npm:
npm uninstall -g @anthropic-ai/claude-code
brew uninstall --cask claude-code
Verifica permisos de directorio
El instalador necesita acceso de escritura a ~/.local/bin/ y ~/.claude/. Si la instalación falla con errores de permisos, verifica si estos directorios son escribibles:
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local
Verifica que el binario funciona
Si claude está instalado pero se bloquea o cuelga al iniciar, ejecuta estas comprobaciones para reducir la causa.
Confirma que el binario existe y es ejecutable:
En Linux, verifica si hay bibliotecas compartidas faltantes. Si ldd muestra bibliotecas faltantes, es posible que necesites instalar paquetes del sistema. En Alpine Linux y otras distribuciones basadas en musl, consulta Configuración de Alpine Linux.
ldd $(which claude) | grep "not found"
Problemas comunes de instalación
Estos son los problemas de instalación más frecuentemente encontrados y sus soluciones.
El script de instalación devuelve HTML en lugar de un script de shell
Al ejecutar el comando de instalación, puedes ver uno de estos errores:
bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'
Invoke-Expression: Missing argument in parameter list.
-
Usa un método de instalación alternativo:
En macOS o Linux, instala a través de Homebrew:
brew install --cask claude-code
winget install Anthropic.ClaudeCode
-
Reintentar después de unos minutos: el problema es a menudo temporal. Espera e intenta el comando original nuevamente.
command not found: claude después de la instalación
La instalación terminó pero claude no funciona. El error exacto varía según la plataforma:
| Plataforma | Mensaje de error |
|---|
| macOS | zsh: command not found: claude |
| Linux | bash: claude: command not found |
| Windows CMD | 'claude' is not recognized as an internal or external command |
| PowerShell | claude : The term 'claude' is not recognized as the name of a cmdlet |
curl: (56) Failure writing output to destination
El comando curl ... | bash descarga el script y lo pasa directamente a Bash para su ejecución usando una tubería (|). Este error significa que la conexión se rompió antes de que el script terminara de descargar. Las causas comunes incluyen interrupciones de red, la descarga siendo bloqueada a mitad de camino, o límites de recursos del sistema.
Soluciones:
-
Verifica la estabilidad de la red: Los binarios de Claude Code se alojan en Google Cloud Storage. Prueba que puedas alcanzarlo:
curl -fsSL https://storage.googleapis.com -o /dev/null
-
Intenta un método de instalación alternativo:
En macOS o Linux:
brew install --cask claude-code
winget install Anthropic.ClaudeCode
Errores de conexión TLS o SSL
Errores como curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed, o el Could not establish trust relationship for the SSL/TLS secure channel de PowerShell indican fallos en el apretón de manos TLS.
Soluciones:
-
Actualiza tus certificados CA del sistema:
En Ubuntu/Debian:
sudo apt-get update && sudo apt-get install ca-certificates
brew install ca-certificates
-
En Windows, habilita TLS 1.2 en PowerShell antes de ejecutar el instalador:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex
-
Verifica la interferencia de proxy o firewall: los proxies corporativos que realizan inspección TLS pueden causar estos errores, incluyendo
unable to get local issuer certificate. Establece NODE_EXTRA_CA_CERTS a tu paquete de certificados CA corporativos:
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
Failed to fetch version from storage.googleapis.com
El instalador no pudo alcanzar el servidor de descarga. Esto típicamente significa que storage.googleapis.com está bloqueado en tu red.
Soluciones:
-
Prueba la conectividad directamente:
curl -sI https://storage.googleapis.com
-
Si estás detrás de un proxy, establece
HTTPS_PROXY para que el instalador pueda enrutarse a través de él. Consulta configuración de proxy para detalles.
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
-
Si estás en una red restringida, intenta una red diferente o VPN, o usa un método de instalación alternativo:
En macOS o Linux:
brew install --cask claude-code
winget install Anthropic.ClaudeCode
Windows: irm o && no reconocido
Si ves 'irm' is not recognized o The token '&&' is not valid, estás ejecutando el comando incorrecto para tu shell.
-
irm no reconocido: estás en CMD, no en PowerShell. Tienes dos opciones:
Abre PowerShell buscando “PowerShell” en el menú Inicio, luego ejecuta el comando de instalación original:
irm https://claude.ai/install.ps1 | iex
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
-
&& no válido: estás en PowerShell pero ejecutaste el comando del instalador de CMD. Usa el instalador de PowerShell:
irm https://claude.ai/install.ps1 | iex
Instalación eliminada en servidores Linux con poca memoria
Si ves Killed durante la instalación en un VPS o instancia en la nube:
Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}
-
Añade espacio de intercambio si tu servidor tiene RAM limitada. El intercambio usa espacio en disco como memoria de desbordamiento, permitiendo que la instalación se complete incluso con RAM física baja.
Crea un archivo de intercambio de 2 GB y habilítalo:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
curl -fsSL https://claude.ai/install.sh | bash
-
Cierra otros procesos para liberar memoria antes de instalar.
-
Usa una instancia más grande si es posible. Claude Code requiere al menos 4 GB de RAM.
La instalación se cuelga en Docker
Al instalar Claude Code en un contenedor Docker, instalar como root en / puede causar cuelgues.
Soluciones:
-
Establece un directorio de trabajo antes de ejecutar el instalador. Cuando se ejecuta desde
/, el instalador escanea todo el sistema de archivos, lo que causa un uso excesivo de memoria. Establecer WORKDIR limita el escaneo a un pequeño directorio:
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
-
Aumenta los límites de memoria de Docker si usas Docker Desktop:
docker build --memory=4g .
Windows: Claude Desktop anula el comando CLI claude
Si instalaste una versión anterior de Claude Desktop, puede registrar un Claude.exe en el directorio WindowsApps que toma prioridad en PATH sobre Claude Code CLI. Ejecutar claude abre la aplicación de escritorio en lugar de la CLI.
Actualiza Claude Desktop a la última versión para corregir este problema.
Windows: “Claude Code on Windows requires git-bash”
Claude Code en Windows nativo necesita Git para Windows, que incluye Git Bash.
Si Git no está instalado, descárgalo e instálalo desde git-scm.com/downloads/win. Durante la configuración, selecciona “Add to PATH.” Reinicia tu terminal después de instalar.
Si Git ya está instalado pero Claude Code aún no puede encontrarlo, establece la ruta en tu archivo settings.json:
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}
where.exe git en PowerShell y usa la ruta bin\bash.exe de ese directorio.
Linux: variante binaria incorrecta instalada (desajuste musl/glibc)
Si ves errores sobre bibliotecas compartidas faltantes como libstdc++.so.6 o libgcc_s.so.1 después de la instalación, el instalador puede haber descargado la variante binaria incorrecta para tu sistema.
Error loading shared library libstdc++.so.6: No such file or directory
-
Verifica qué libc usa tu sistema:
Si muestra
linux-vdso.so o referencias a /lib/x86_64-linux-gnu/, estás en glibc. Si muestra musl, estás en musl.
-
Si estás en glibc pero obtuviste el binario musl, elimina la instalación y reinstala. También puedes descargar manualmente el binario correcto desde el bucket de GCS en
https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json. Abre un problema en GitHub con la salida de ldd /bin/ls y ls /lib/libc.musl*.
-
Si realmente estás en musl (Alpine Linux), instala los paquetes requeridos:
apk add libgcc libstdc++ ripgrep
Illegal instruction en Linux
Si el instalador imprime Illegal instruction en lugar del mensaje Killed de OOM, el binario descargado no coincide con la arquitectura de tu CPU. Esto ocurre comúnmente en servidores ARM que reciben un binario x86, o en CPUs más antiguas que carecen de conjuntos de instrucciones requeridos.
bash: line 142: 2238232 Illegal instruction "$binary_path" install ${TARGET:+"$TARGET"}
-
Verifica tu arquitectura:
x86_64 significa 64-bit Intel/AMD, aarch64 significa ARM64. Si el binario no coincide, abre un problema en GitHub con la salida.
-
Intenta un método de instalación alternativo mientras se resuelve el problema de arquitectura:
brew install --cask claude-code
dyld: cannot load en macOS
Si ves dyld: cannot load o Abort trap: 6 durante la instalación, el binario es incompatible con tu versión de macOS o hardware.
dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6
-
Verifica tu versión de macOS: Claude Code requiere macOS 13.0 o posterior. Abre el menú Apple y selecciona About This Mac para verificar tu versión.
-
Actualiza macOS si estás en una versión anterior. El binario usa comandos de carga que las versiones anteriores de macOS no soportan.
-
Intenta Homebrew como método de instalación alternativo:
brew install --cask claude-code
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 puede 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 puede estar usando una instalación de Windows de Node.js. 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 corregir 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, puedes 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 npm/nvm 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 carga 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.):
# Carga 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"
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
Evita desabilitar la importación de PATH de Windows a través de appendWindowsPath = false ya que esto rompe la capacidad de llamar ejecutables de Windows desde WSL. De manera similar, evita desinstalar Node.js de Windows si lo usas para desarrollo de Windows.
Configuración de sandbox WSL2
Sandboxing es compatible en WSL2 pero requiere instalar paquetes adicionales. Si ves un error como “Sandbox requires socat and bubblewrap” al ejecutar /sandbox, instala las dependencias:
sudo apt-get install bubblewrap socat
sudo dnf install bubblewrap socat
Errores de permisos durante la instalación
Si el instalador nativo falla con errores de permisos, el directorio de destino puede no ser escribible. Consulta Verifica permisos de directorio.
Si instalaste previamente con npm y estás teniendo errores específicos de permisos de npm, cambia al instalador nativo:
curl -fsSL https://claude.ai/install.sh | bash
Permisos y autenticación
Estas secciones abordan fallos de inicio de sesión, problemas de tokens, y comportamiento de solicitudes de permisos.
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. Consulta 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 el navegador no se abre automáticamente durante el inicio de sesión, presiona c para copiar la URL de OAuth a tu portapapeles, luego pégala en tu navegador manualmente.
Error OAuth: Código inválido
Si ves OAuth error: Invalid code. Please make sure the full code was copied, el código de inicio de sesión expiró o fue truncado durante la copia-pega.
Soluciones:
- Presiona Enter para reintentar y completa el inicio de sesión rápidamente después de que se abra el navegador
- Escribe
c para copiar la URL completa si el navegador no se abre automáticamente
- Si usas una sesión remota/SSH, el navegador puede abrirse en la máquina incorrecta. Copia la URL mostrada en la terminal y ábrela en tu navegador local en su lugar.
403 Forbidden después del inicio de sesión
Si ves API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}} después de iniciar sesión:
- Usuarios de Claude Pro/Max: verifica que tu suscripción esté activa en claude.ai/settings
- Usuarios de Console: confirma que tu cuenta tiene el rol “Claude Code” o “Developer” asignado por tu administrador
- Detrás de un proxy: los proxies corporativos pueden interferir con solicitudes de API. Consulta configuración de red para configuración de proxy.
El inicio de sesión OAuth falla en WSL2
El inicio de sesión basado en navegador en WSL2 puede fallar si WSL no puede abrir tu navegador de Windows. Establece la variable de entorno BROWSER:
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude
c para copiar la URL de OAuth, luego pégala en tu navegador de Windows.
”Not logged in” o token expirado
Si Claude Code te solicita iniciar sesión nuevamente después de una sesión, tu token de OAuth puede haber expirado.
Ejecuta /login para re-autenticarte. Si esto ocurre frecuentemente, verifica que tu reloj del sistema sea preciso, ya que la validación de tokens depende de marcas de tiempo correctas.
Ubicaciones de archivos de configuración
Claude Code almacena la configuración en varias ubicaciones:
| Archivo | Propósito |
|---|
~/.claude/settings.json | Configuración de usuario (permisos, hooks, anulaciones de modelo) |
.claude/settings.json | Configuración de proyecto (registrada en control de fuente) |
.claude/settings.local.json | Configuración de proyecto local (no confirmada) |
~/.claude.json | Estado global (tema, OAuth, servidores MCP) |
.mcp.json | Servidores MCP de proyecto (registrados en control de fuente) |
managed-mcp.json | Servidores MCP administrados |
| Configuración administrada | Configuración administrada (administrada por servidor, políticas MDM/nivel de SO, o basada en archivos) |
~ se refiere a tu directorio de inicio de usuario, como C:\Users\TuNombre.
Para detalles sobre la configuración de estos archivos, consulta Configuración y MCP.
Restablecimiento de configuración
Para restablecer Claude Code a la configuración predeterminada, puedes eliminar los archivos de configuración:
# Restablece toda la configuración de usuario y estado
rm ~/.claude.json
rm -rf ~/.claude/
# Restablece la configuración específica del proyecto
rm -rf .claude/
rm .mcp.json
Esto eliminará toda tu configuración, configuraciones de servidores MCP, e historial de sesiones.
Rendimiento y estabilidad
Estas secciones cubren problemas relacionados con el uso de recursos, capacidad de respuesta, y comportamiento de búsqueda.
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:
- Usa
/compact regularmente para reducir el tamaño del contexto
- Cierra y reinicia Claude Code entre tareas principales
- Considera añadir directorios de compilación grandes a tu archivo
.gitignore
El comando se cuelga o congela
Si Claude Code parece no responder:
- Presiona Ctrl+C para intentar cancelar la operación actual
- Si no responde, es posible que necesites cerrar la terminal y reiniciar
Problemas de búsqueda y descubrimiento
Si la herramienta Search, menciones @file, agentes personalizados, y skills personalizados no funcionan, instala el sistema ripgrep:
# 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
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 al usar Claude Code en WSL. La búsqueda aún funciona, pero devuelve menos resultados que en un sistema de archivos nativo.
/doctor mostrará Search como OK en este caso.
-
Envía búsquedas más específicas: reduce el número de archivos buscados especificando directorios o tipos de archivo: “Search for JWT validation logic in the auth-service package” o “Find use of md5 hash in JS files”.
-
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/).
-
Usa 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 integración de IDE
Si Claude Code no se conecta a tu IDE o se comporta inesperadamente dentro de una terminal de IDE, intenta las soluciones a continuación.
IDE de JetBrains no detectado en WSL2
Si estás usando Claude Code en WSL2 con IDEs de JetBrains y obteniendo errores “No available IDEs detected”, esto es probablemente debido a la configuración de red de WSL2 o Windows Firewall bloqueando la conexión.
Modos de red de WSL2
WSL2 usa red NAT por defecto, lo que puede prevenir la detección de IDE. Tienes dos opciones:
Opción 1: Configura Windows Firewall (recomendado)
-
Encuentra tu dirección IP de WSL2:
wsl hostname -I
# Salida de ejemplo: 172.21.123.45
-
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
-
Reinicia tanto tu IDE como Claude Code
Opción 2: Cambia a red reflejada
Añade a .wslconfig en tu directorio de usuario de Windows:
[wsl2]
networkingMode=mirrored
wsl --shutdown desde PowerShell.
Estos problemas de red solo afectan a WSL2. WSL1 usa la red del host directamente y no requiere estas configuraciones.
Reporta problemas de integración de IDE en Windows
Si estás experimentando problemas de integración de IDE en Windows, crea un problema con la siguiente información:
- Tipo de entorno: Windows nativo (Git Bash) o WSL1/WSL2
- Modo de red de WSL, si aplica: NAT o reflejado
- Nombre y versión del IDE
- Versión de extensión/plugin de Claude Code
- Tipo de shell: Bash, Zsh, PowerShell, etc.
La tecla Escape no funciona en terminales de IDE de JetBrains
Si estás usando Claude Code en terminales de JetBrains y la tecla Esc no interrumpe el agente como se espera, esto es probablemente debido a un choque de atajos de teclado con los atajos de teclado predeterminados de JetBrains.
Para corregir este problema:
- Ve a Settings → Tools → Terminal
- Cualquiera de:
- Desmarca “Move focus to the editor with Escape”, o
- Haz clic en “Configure terminal keybindings” y elimina el atajo “Switch focus to Editor”
- Aplica los cambios
Esto permite que la tecla Esc interrumpa correctamente las operaciones de Claude Code.
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";
}
```text
```javascript
function example() {
return "hello";
}
```text
-
Pide a Claude que añada etiquetas de lenguaje: solicita “Add appropriate language tags to all code blocks in this markdown file.”
-
Usa hooks de post-procesamiento: configura hooks de formato automático para detectar y añadir etiquetas de lenguaje faltantes. Consulta Auto-format code after edits para un ejemplo de un hook de formato PostToolUse.
-
Verificación manual: después de generar archivos markdown, revísalos para el formato correcto de bloques de código y solicita correcciones si es necesario.
Si el markdown generado tiene líneas en blanco excesivas o espaciado inconsistente:
Soluciones:
-
Solicita correcciones de formato: pide a Claude que “Fix spacing and formatting issues in this markdown file.”
-
Usa herramientas de formato: configura hooks para ejecutar formateadores de markdown como
prettier o scripts de formato personalizados en archivos markdown generados.
-
Especifica preferencias de formato: incluye requisitos de formato en tus solicitudes o archivos de memoria del proyecto.
Para minimizar problemas de formato:
- Sé explícito en solicitudes: pide “properly formatted markdown with language-tagged code blocks”
- Usa convenciones de proyecto: documenta tu estilo de markdown preferido en
CLAUDE.md
- Configura hooks de validación: usa hooks de post-procesamiento para verificar y corregir automáticamente problemas comunes de formato
Obtén 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
- Verifica el repositorio de GitHub para problemas conocidos
- Ejecuta
/doctor para diagnosticar problemas. Verifica:
- Tipo de instalación, versión, y funcionalidad de búsqueda
- Estado de actualización automática y versiones disponibles
- Archivos de configuración inválidos (JSON malformado, tipos incorrectos)
- Errores de configuración de servidores MCP
- Problemas de configuración de atajos de teclado
- Advertencias de uso de contexto (archivos CLAUDE.md grandes, alto uso de tokens de MCP, reglas de permisos inalcanzables)
- Errores de carga de plugins y agentes
- Pregunta a Claude directamente sobre sus capacidades y características - Claude tiene acceso integrado a su documentación
