Solución de problemas

Corrige el alto uso de CPU o memoria, cuelgues, thrashing de auto-compact, y problemas de búsqueda en Claude Code, y encuentra la página correcta para otros problemas.

Esta página cubre problemas de rendimiento, estabilidad y búsqueda una vez que Claude Code está en ejecución. Para otros problemas, comienza con la página que coincida con dónde estés atrapado:

Si no estás seguro de cuál aplica, ejecuta /doctor dentro de Claude Code para una verificación automatizada de tu instalación, configuración, extensiones, y uso de contexto; propone correcciones que puede aplicar después de que confirmes. Si claude no inicia en absoluto, ejecuta claude doctor desde tu shell en su lugar. Ejecuta /mcp para verificar el estado del servidor MCP.

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á experimentando problemas de rendimiento:

1. Utilice /compact regularmente para reducir el tamaño del contexto. Si devuelve Not enough messages to compact., la conversación tiene muy pocos turnos para resumir; eso puede suceder incluso con un contexto completo cuando un único pegado grande lo llenó
2. Cierre y reinicie Claude Code entre tareas principales
3. Considere añadir directorios de compilación grandes a su archivo .gitignore
4. Reinicie con claude --safe-mode para verificar si un plugin, servidor MCP, o hook es la fuente. Desactiva todas las personalizaciones para la sesión; si el uso disminuye, consulte Depurar su configuración para encontrar cuál es

Si la memoria de sesión supera 2.5GB, aparece una advertencia crítica de uso de memoria. Para liberar la memoria, reinicie Claude Code y ejecute claude --continue para reanudar la conversación en un proceso nuevo.

Fuera de renderizado a pantalla completa, ejecutar /compact también libera memoria. La advertencia desaparece una vez que el uso de memoria cae por debajo de 2.5GB.

Si el uso de memoria se mantiene alto después de estos pasos, ejecute /heapdump para escribir dos archivos a ~/Desktop: una instantánea de montón de JavaScript denominada <session-id>.heapsnapshot y un desglose de memoria denominado <session-id>-diagnostics.json. Claude Code oculta el comando del menú de comandos; escriba el comando completo. En Linux sin una carpeta Desktop, los archivos se escriben en su directorio de inicio.

El comando también imprime un resumen en la conversación, mostrando el tamaño del conjunto residente, montón de JS, búferes de matriz, y memoria nativa no contabilizada, más cualquier indicador de fuga que detecte, como una tasa de crecimiento de memoria alta o un número inusualmente alto de identificadores abiertos. El resumen indica si la mayoría de la memoria está en el montón de JS, que la instantánea captura, o en memoria nativa, que no lo hace.

Haga una de dos cosas con la salida:

• Infórmelo: abra un problema de GitHub y adjunte solo el archivo -diagnostics.json, que contiene las estadísticas detrás del resumen impreso y ningún contenido de conversación ni credenciales
• Investíguelo usted mismo: si el resumen dice que la mayoría de la memoria es montón de JS, abra el archivo .heapsnapshot en Chrome DevTools en Memory → Load y ordene por tamaño retenido para ver qué está reteniendo la memoria

Si el resumen dice que la mayoría de la memoria es nativa, la instantánea no puede mostrarlo; incluya los indicadores de fuga del resumen en su informe en su lugar.

Las tablas grandes se cortan en la terminal

Una tabla Markdown con más de 200 filas renderiza sus primeras 200 filas seguidas de una línea … N more rows not shown. Solo la visualización está limitada: la tabla completa permanece en la conversación, y /copy copia cada fila. Para una tabla demasiado grande para leer en la terminal, pida a Claude que la escriba en un archivo en su lugar. Antes de v2.1.208, Claude Code renderizaba cada fila, por lo que reanudar una sesión que contenía una tabla muy grande podría estancarse mientras se re-renderizaba.

Auto-compaction se detiene con un error de thrashing

Si ve Autocompact is thrashing: the context refilled to the limit..., la compactación automática fue exitosa pero un archivo o salida de herramienta rellenó inmediatamente la ventana de contexto varias veces seguidas. Claude Code deja de reintentar para evitar desperdiciar llamadas de API en un bucle que no está haciendo progreso.

Para recuperarse:

1. Pida a Claude que lea el archivo de gran tamaño en fragmentos más pequeños, como un rango de línea específico o función, en lugar de todo el archivo
2. Ejecute /compact con un enfoque que elimine la salida grande, por ejemplo /compact keep only the plan and the diff
3. Mueva el trabajo de archivo grande a un subagente para que se ejecute en una ventana de contexto separada
4. Ejecute /clear si la conversación anterior ya no es necesaria

El comando se cuelga o congela

Si Claude Code parece no responder:

1. Presione Ctrl+C para intentar cancelar la operación actual
2. Si no responde, es posible que necesite cerrar la terminal y reiniciar

Reiniciar no pierde su conversación. Ejecute claude --resume en el mismo directorio para retomar la sesión.

Texto garbled o corrupto en la terminal integrada de un editor

Si los caracteres se renderizan como cuadros, manchas, o glifos incorrectos al ejecutar Claude Code en la terminal integrada de VS Code, Cursor, o Devin Desktop, el renderizador GPU de la terminal es probablemente la causa. Ejecute /terminal-setup dentro de Claude Code para establecer terminal.integrated.gpuAcceleration a "off", o establézcalo manualmente en la configuración de su editor y recargue la ventana. Consulte Configuración de terminal para las otras configuraciones que /terminal-setup escribe.

La rueda del ratón se desplaza una línea a la vez en renderizado a pantalla completa

En renderizado a pantalla completa, Claude Code desplaza la conversación en sí en lugar de dejarlo a su terminal. Si cada muesca de rueda mueve menos líneas de las que desea, ejecute /scroll-speed para aumentar el número de líneas por muesca y guárdelo, o establezca la variable de entorno CLAUDE_CODE_SCROLL_SPEED, excepto en la terminal del IDE JetBrains, donde Claude Code aplica su propio manejo de desplazamiento y ninguno de los dos tiene efecto. Consulte Desplazamiento de rueda del ratón para los valores que cada uno acepta.

Para moverse más rápido sin cambiar la velocidad, presione PgUp y PgDn para desplazarse media pantalla a la vez. Para usar el desplazamiento nativo de su terminal en su lugar, ejecute /tui default para cambiar al renderizador clásico.

Los comandos del portapapeles como `pbcopy` fallan dentro del sandbox

Cuando sandboxing está activado, las utilidades del portapapeles como pbcopy, xclip, y wl-copy pueden fallar al alcanzar el portapapeles del sistema desde dentro de un comando Bash en sandbox, dejando su portapapeles sin cambios después de que Claude canaliza texto a ellos.

Para poner la salida de Claude en su portapapeles, pida a Claude que imprima el contenido en su respuesta, luego ejecute /copy. /copy escribe en el portapapeles desde el proceso de Claude Code en sí en lugar de desde un comando en sandbox, por lo que el sandboxing no lo bloquea. Puede copiar un único bloque de código en lugar de toda la respuesta, y también escribe lo que copió en un archivo e imprime la ruta, lo que le da una alternativa cuando la escritura del portapapeles no alcanza su terminal, por ejemplo sobre SSH.

Cuando Claude canaliza texto a una de estas herramientas, añadir pbcopy *, wl-copy *, o xclip * a excludedCommands no saca esa llamada del sandbox por sí sola.

Texto copiado no llega a su portapapeles local sobre SSH

Cuando Claude Code se ejecuta en una máquina remota sobre SSH, no puede ejecutar una herramienta de portapapeles en su máquina local. Fuera de tmux, cuando selecciona texto en renderizado a pantalla completa o ejecuta /copy, Claude Code envía el texto a su terminal como una secuencia de escape OSC 52 en su lugar. Su terminal decide si lo pone en su portapapeles. /copy informa Copied to clipboard independientemente de si el texto llegó, y fuera de tmux el aviso de selección lee sent N chars via OSC 52.

Algunos terminales no actúan sobre OSC 52. iTerm2 lo ignora hasta que activa Settings > General > Selection > Applications in terminal may access clipboard, y macOS Terminal.app no lo admite.

Para obtener el texto sin OSC 52:

• Mantenga presionada la tecla de selección nativa de su terminal mientras arrastra, luego copie con el atajo habitual de su terminal, como Cmd+C. La tecla es Fn en Terminal.app e Option en iTerm2. Mantener selección de texto nativa la enumera para otros terminales.
• Establezca CLAUDE_CODE_DISABLE_MOUSE=1 en la máquina remota para que su terminal maneje la selección para toda la sesión.

Problemas de búsqueda y descubrimiento

Si la herramienta Search, menciones @file, agentes personalizados, o skills personalizados no encuentran archivos, el binario ripgrep incluido puede no ejecutarse en su sistema. Instale el paquete ripgrep de su plataforma e indique a Claude Code que lo use en su lugar:

brew install ripgrep

sudo apt install ripgrep

apk add ripgrep

pacman -S ripgrep

winget install BurntSushi.ripgrep.MSVC

Luego establezca USE_BUILTIN_RIPGREP a 0, ya sea en su entorno de shell o en el bloque env de su settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Para confirmar que el cambio tuvo efecto, ejecute claude doctor en su terminal y verifique que la línea Search muestre la ruta de su ripgrep del sistema en lugar de OK (bundled).

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.

Soluciones:

1. Envíe búsquedas más específicas: reduzca 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".

2. Mueva el proyecto al sistema de archivos de Linux: si es posible, asegúrese de que su proyecto esté ubicado en el sistema de archivos de Linux (/home/) en lugar del sistema de archivos de Windows (/mnt/c/).

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

Obtén más ayuda

Si estás experimentando problemas no cubiertos aquí:

1. Ejecuta /doctor para una verificación de configuración y /mcp para verificar el estado del servidor MCP
2. Usa el comando /feedback dentro de Claude Code para reportar problemas directamente a Anthropic
3. Verifica el repositorio de GitHub para problemas conocidos
4. Pregunta a Claude directamente sobre sus capacidades y características. Claude tiene acceso integrado a su documentación.

Para problemas de cuenta, facturación o suscripción, contacta al soporte de Anthropic en su lugar: inicia sesión en claude.ai (Usuarios de Console: platform.claude.com), haz clic en tus iniciales en la esquina inferior izquierda y selecciona Obtener ayuda. Consulta Cómo obtener soporte para el flujo completo, incluyendo quién puede comunicarse con un agente humano en cada plan.