Los desarrolladores que han utilizado Claude Code se han topado alguna vez con esta escena: en la terminal aparece una línea que dice "Symbioting… (3m 12s · ↓ 5.7k tokens)", la barra de progreso parece congelada y no hay ninguna salida nueva durante varios minutos. Intentas enviar un mensaje como "¿Sigues ahí?", y para tu sorpresa, Claude retoma el trabajo inmediatamente y termina la tarea que estaba realizando.
Esta extraña experiencia de "bloqueo + resurrección mediante mensaje" parece magia, pero en realidad es el resultado de la superposición de varios modos de fallo en el protocolo de streaming de Anthropic, los mecanismos de tiempo de espera (timeout) y la gestión del contexto. Este artículo, basado en la documentación oficial de resolución de problemas de Claude Code y en los hilos de GitHub #25979, #24688, #39718, #25286, #25539 y #51659, explica claramente las causas reales por las que Claude Code se bloquea, y ofrece 7 métodos de recuperación inmediatos y 5 estrategias de prevención.
Valor central: Al terminar de leer este artículo, sabrás qué significa cada verbo del spinner, por qué enviar un mensaje a veces puede "revivir" al modelo, cuándo es obligatorio forzar un reinicio con Ctrl+C y cómo reducir la tasa de bloqueos a casi cero.
Interpretación completa de los indicadores de estado de Claude Code
Para solucionar el problema de "bloqueo", el primer paso es entender la línea de estado que Claude Code te muestra en la terminal. El valor Symbioting… (3m 12s · ↓ 5.7k tokens) de la captura de pantalla parece misterioso, pero en realidad es información estructurada donde cada parte tiene un significado claro.
| Campo | Valor de ejemplo | Significado |
|---|---|---|
| Verbo del Spinner | Symbioting… |
Descripción antropomórfica de la etapa actual, personalizable desde la v2.1.23 |
| Tiempo de espera | 3m 12s |
Tiempo transcurrido acumulado desde el inicio de esta ronda |
| Flecha de flujo | ↓ o ↑ |
↓ indica recepción de datos de la API, ↑ indica envío |
| Recuento de tokens | 5.7k tokens |
Cantidad de tokens descargados/subidos hasta el momento |
Claude Code incluye 187 verbos de spinner predeterminados; Befuddling, Ruminating, Accomplishing y Symbioting son solo algunos de ellos. Están ahí simplemente para hacer que la experiencia de espera sea más dinámica, sin diferencias técnicas entre ellos. A partir de la versión 2.1.23, se introdujo la opción de configuración spinnerVerbs, y la comunidad incluso cuenta con paquetes de más de 1900 verbos personalizados.
Para determinar si Claude Code está realmente bloqueado, la clave no está en el verbo, sino en dos cosas: si el tiempo sigue aumentando y si el recuento de tokens sigue cambiando. Si después de 3m 12s pasan 30 segundos y el tiempo marca 3m 42s, pero el recuento de tokens sigue estancado en 5.7k, entonces se puede determinar que la respuesta en streaming se ha detenido.
Si utilizas la API de Claude en tu país a través de un servicio proxy de API como APIYI (apiyi.com), el significado de los campos de estado es exactamente el mismo que en la versión oficial, por lo que puedes usar el mismo método de diagnóstico para localizar el problema.
Las 6 causas principales por las que Claude Code se bloquea
Una vez que entiendes los indicadores de estado, puedes comparar el comportamiento real para localizar la causa raíz. Las siguientes 6 razones están ordenadas por frecuencia y cubren más del 90% de los casos reales reportados en el rastreador de GitHub Issues.
Causa raíz 1: Interrupción silenciosa de la respuesta en streaming de la API
Esta es la causa más común y oculta, correspondiente al Issue #25979 de GitHub. El cliente HTTP de Claude Code no tiene un mecanismo de tiempo de espera de lectura (read timeout). Si la API ascendente deja de enviar paquetes a mitad de la transmisión, el proceso se quedará bloqueado en el estado del kernel epoll_wait esperando nuevos datos. El spinner en la interfaz sigue girando, pero el contador de tokens no aumenta. Las causas comunes incluyen inestabilidad en la red transfronteriza, multiplexación con tmux, o cortes en conexiones SSH de larga duración.
Causa raíz 2: El payload de invocación de herramienta es demasiado grande y provoca un reset de la conexión
Corresponde al Issue #39718. Cuando el modelo le pide a Claude Code que ejecute una herramienta que genera una salida masiva (por ejemplo, Write en un archivo de cientos de miles de líneas), si la conexión HTTP subyacente no transmite datos válidos durante 5 minutos, el sistema operativo la reiniciará activamente. Claude Code no captura este error, por lo que el spinner sigue activo en la interfaz. Este tipo de bloqueo suele ocurrir exactamente a los 5 minutos.
Causa raíz 3: Thrashing por auto-compresión
Cuando la ventana de contexto de Claude Code está casi llena, se activa la auto-compresión (auto-compact). Si un archivo muy grande o la salida de una herramienta se vuelve a leer en el contexto inmediatamente después de ser comprimido, se activará la compresión repetidamente, y el sistema terminará deteniéndose y lanzando el aviso Autocompact is thrashing. Antes de que aparezca el aviso, la interfaz parece bloqueada.
Causa raíz 4: Uso del contexto superior al 80%
La documentación oficial indica claramente que, una vez superado el 80% del contexto, el tiempo de respuesta se deteriora significativamente, manifestándose en algunos casos como una falta de respuesta prolongada. La característica de este "falso bloqueo" es que el contador de tokens sigue aumentando lentamente, pero a una fracción de la velocidad normal.
Causa raíz 5: Anomalías en la configuración que provocan un bloqueo durante el inicio
Corresponde a los Issues #31049, #29652, etc. Por ejemplo, si enableAllProjectMcpServers: true carga una gran cantidad de servidores MCP locales, o si additionalDirectories tiene un prefijo de ruta anormal como //C:/, Claude Code se bloqueará al iniciar. Este bloqueo suele ocurrir en los primeros segundos al abrir una nueva sesión.
Causa raíz 6: Residuos en la línea de estado (la respuesta terminó pero la interfaz no se actualizó)
Corresponde al Issue #25539. En algunas versiones, Claude ya ha devuelto el resultado completo, pero el spinner de la terminal no se ha borrado, dando la impresión de que sigue trabajando. Si presionas Enter o envías un mensaje, Claude comenzará inmediatamente una nueva ronda de trabajo; en realidad, nunca estuvo bloqueado, la interfaz simplemente "mintió".
Al investigar, te sugiero que primero compruebes si el contador de tokens está aumentando. Si estás utilizando el servicio proxy de API de APIYI (apiyi.com), puedes verificar simultáneamente en los registros de la plataforma si la solicitud ha devuelto un 200 OK, y combinar esto con el estado de la interfaz de Claude Code para una validación cruzada.
¿Por qué enviar un mensaje puede "revivir" a Claude Code?
Muchos han descubierto un "misterioso" milagro de ingeniería: Claude Code se bloquea durante 3 minutos, envías un "¿sigues ahí?" o simplemente presionas Enter, y continúa inmediatamente con el trabajo que estaba haciendo. Este fenómeno se puede explicar a nivel de protocolo.
El primer caso es el de residuos en la línea de estado (Causa raíz 6). Claude realmente ha completado la respuesta, pero la interfaz no ha eliminado el spinner. En este caso, tu nuevo mensaje se procesa directamente como la siguiente ronda de indicación, lo que parece una "resurrección", pero en esencia es solo continuar el flujo.
El segundo caso es el bloqueo de la respuesta en streaming (Causa raíz 1). Cuando Claude Code recibe una nueva entrada, cierra activamente el estado de espera actual, limpia la solicitud incompleta y comienza una nueva solicitud HTTP. La nueva solicitud se envía con el historial completo de la sesión, y el modelo continúa respondiendo desde el punto de interrupción, por lo que parece que "sigue trabajando".
El tercer caso es cuando un servidor MCP o una invocación de herramienta está esperando una respuesta descendente. El nuevo mensaje es enrutado por Claude Code como una nueva decisión de invocación de herramienta, evitando indirectamente la llamada que se quedó bloqueada.
Es importante enfatizar que enviar un mensaje no es una cura mágica. Cuando el bloqueo se debe a que el proceso subyacente está en un estado de espera irrecuperable (como en la fase avanzada de la Causa raíz 2), enviar un mensaje solo hará que el mensaje entre en la cola de entrada, pero no será procesado; en ese caso, debes usar Ctrl+C o cerrar la terminal. Para los escenarios que utilizan el servicio proxy de API de APIYI (apiyi.com), la tasa de éxito de la "resurrección" mediante mensajes suele ser mayor, ya que la plataforma de proxy generalmente libera las conexiones con tiempo de espera agotado antes que el punto final oficial.
7 métodos para recuperar Claude Code cuando se queda bloqueado
Cada causa raíz requiere una solución distinta. La siguiente tabla organiza los 7 métodos más efectivos según su "nivel de intrusión", de menor a mayor, para ayudarte a decidir rápidamente.
| Método | Comando | Causa raíz aplicable | ¿Se pierde el contexto? |
|---|---|---|---|
| Enviar un mensaje | Entrada directa de texto | Causa 1 / 6 | No |
| Interrumpir operación | Ctrl+C |
Causa 1 / 2 / 3 | No |
| Diagnóstico | /doctor |
Cualquiera (primero) | No |
| Comprimir contexto | /compact |
Causa 3 / 4 | Historial parcial a resumen |
| Limpiar sesión | /clear |
Causa 4 (grave) | Sí |
| Reiniciar terminal | claude --resume |
Causa 1 / 2 (grave) | No |
| Forzar cierre | kill -9 <pid> |
Causa 1 / 2 (irreparable) | Se pierde la ronda actual |
La recomendación operativa es seguir el orden de "menor a mayor". Primero, intenta presionar Enter o enviar un mensaje simple; si no funciona, usa Ctrl+C para cancelar la ronda actual. Si la terminal no responde en absoluto, cierra la terminal y utiliza claude --resume para recuperar la sesión.
/doctor es el comando de diagnóstico recomendado oficialmente por Anthropic. Realiza una comprobación integral de la instalación, el archivo de configuración, la lista de servidores MCP y el uso de la ventana de contexto. Tras ejecutarlo, suele ofrecer sugerencias de reparación específicas. Si el informe indica Context: 87%, es casi seguro que la causa es la número 4, y usar /compact aliviará el problema de inmediato.
Para tareas largas, te sugiero integrar /compact periódicamente en tu flujo de trabajo para mantener el uso de la ventana de contexto por debajo del 60%. Además, al invocar a Claude a través de la plataforma APIYI (apiyi.com), puedes solicitar cuotas independientes para el proceso principal de Claude Code y los servidores MCP, lo que facilita la identificación del origen de cualquier anomalía.
5 mejores prácticas para evitar que Claude Code se bloquee
La resolución de problemas es solo apagar fuegos; un flujo de trabajo realmente estable depende de la prevención. Las siguientes 5 prácticas se basan en el análisis de causas raíz de múltiples issues de GitHub y pueden reducir la tasa de bloqueos a niveles casi insignificantes.
La primera es la lectura de archivos grandes por fragmentos. Leer directamente archivos de más de 1MB casi siempre disparará la presión sobre la ventana de contexto. Cambia a un proceso de dos pasos: primero usa ls -la para ver el tamaño y luego usa Read con los parámetros offset/limit para leer por partes; esto evita la causa raíz 4.
La segunda es delegar tareas complejas a subagentes. Los subagentes de Claude Code tienen su propia ventana de contexto independiente. Delegar tareas como la generación masiva de archivos o la reescritura de código por lotes a un subagente evita, desde la raíz, que el contexto principal se sature.
La tercera es desactivar servidores MCP sospechosos. Cada servidor MCP añadido aumenta el riesgo de bloqueo durante el inicio. Mantén en la configuración solo los MCP que realmente usas a diario y desactiva el resto; esto reduce significativamente la causa raíz 5.
La cuarta es configurar tiempos de espera (timeouts) para el modelo principal y la lectura. Una práctica consolidada en la comunidad es establecer STREAM_READ_TIMEOUT_MS en 120 segundos y añadir un proceso watchdog externo que monitoree si el archivo JSONL sigue creciendo; si no, lo mata y reinicia automáticamente. Esto es extremadamente efectivo contra la causa raíz 1.
La quinta es utilizar una ruta de API estable. Las llamadas transfronterizas, las conexiones de banda ancha doméstica y el uso de tmux aumentan la probabilidad de interrupciones en el streaming. Una forma sencilla es realizar la invocación del modelo a través de plataformas de agregación y servicio proxy de API como APIYI (apiyi.com). Esto permite que la conexión TCP de larga duración pase por nodos estables, reduciendo la frecuencia de la causa raíz 1.
Los equipos que implementan estas 5 medidas reportan que la frecuencia de bloqueos semanales cae de 5-10 veces a menos de 1, y el tiempo promedio de recuperación se reduce de 5-10 minutos a apenas unos segundos.
Preguntas frecuentes
Q1: ¿Los diferentes verbos en el spinner significan que Claude está haciendo cosas distintas?
No. Los 187 verbos predeterminados son solo frases antropomórficas seleccionadas al azar y no tienen ninguna relación con el estado real de Claude. Para determinar el estado, observa el conteo de tokens y el tiempo de espera.
Q2: ¿Se pierde el contexto después de un Ctrl+C?
No. Ctrl+C solo cancela la ronda actual que no se ha completado; toda la sesión se mantiene. Si Ctrl+C no responde, puedes presionar una vez más o cerrar directamente la terminal y luego usar claude --resume para recuperar la sesión.
Q3: ¿Es fácil que Claude Code se bloquee al usarlo desde fuera de EE. UU.?
La red transfronteriza es uno de los principales factores que causan interrupciones en el streaming. Se recomienda utilizar plataformas de agregación y servicio proxy de API como APIYI (apiyi.com) para realizar la invocación del modelo, ya que los nodos de tránsito estables mantienen la conexión de larga duración con Anthropic, lo que reduce notablemente la probabilidad de bloqueos para los desarrolladores.
Q4: ¿Qué debo hacer si veo `Autocompact is thrashing`?
Detén la tarea actual inmediatamente y usa un comando de compresión con enfoque, como /compact keep only the plan and the diff, para limpiar los grandes bloques de salida original del contexto. Si sigue fallando, abre una nueva sesión o cambia la lectura de archivos grandes al modo de subagente.
Q5: ¿Puedo cambiar yo mismo los verbos del spinner?
Sí. En ~/.claude/settings.json, añade el campo spinnerVerbs. Los modos pueden ser default, append o replace, combinados con un arreglo de cadenas de texto. La comunidad cuenta con paquetes de verbos con 88 temas y más de 1900 palabras que puedes aplicar directamente.
Resumen
La esencia de por qué Claude Code se bloquea radica en la superposición de tres subsistemas en escenarios límite: el protocolo de streaming, la gestión del contexto y la integración MCP. Al comprender los 4 campos del indicador de estado, memorizar las 6 causas raíz y las 7 estrategias de recuperación, podrás transformar lo que parece una "falla metafísica" en un problema técnico conocido y manejable.
Nuestra recomendación práctica es convertir los métodos de recuperación en memoria muscular: primero envía un mensaje, luego presiona Ctrl+C, ejecuta /doctor y, finalmente, cierra la terminal y usa claude --resume. Si combinas esto con un servicio proxy de API estable y sigues nuestras 5 prácticas preventivas —como mantener el contexto por debajo del 80%, delegar archivos grandes a subagentes y utilizar la ruta estable de APIYI (apiyi.com)—, la gran mayoría de los bloqueos podrán resolverse por sí mismos en cuestión de segundos.
Autor: Equipo técnico de APIYI
Contacto: Obtén acceso a toda la serie de modelos Claude y soporte de proxy estable para Claude Code a través de APIYI en apiyi.com
Fecha de actualización: 13 de mayo de 2026
