Claude Code: Diagnóstico de desconexiones remotas: síntomas, criterios y soluciones para seis tipos de desconexión

Ejecutar Claude Code remotamente: lo peor no es no poder conectarse, sino que se desconecta después de haberte conectado, y cada vez por un motivo diferente.

El término «desconexión» en realidad cubre seis fallos completamente distintos. Sus síntomas tienen características propias y sus soluciones no guardan relación entre sí: tratar la caída de una conexión persistente por cambio de red como si fuera suspensión de la máquina no servirá aunque desactives la hibernación; esperar a que una conexión semimuerta se recupere creyendo que es mala señal no hará que se arregle sola ni al amanecer.

Este artículo deduce las causas a partir de lo que realmente ves: para cada tipo de desconexión se indican los síntomas, cómo confirmarlo y la solución correspondiente. Si prefieres ir directo a la acción, salta a la lista de verificación de la última sección.

Este artículo trata solo de diagnóstico de desconexiones. Para montar el acceso remoto, consulta «Acceso remoto a Claude Code: controla sesiones desde cualquier lugar sin la máquina local»; para usarlo en el móvil, consulta «Claude Code en el móvil: consulta sesiones y aprueba herramientas en cualquier momento en iOS».

Primero, identifica el síntoma: ¿cuál estás viendo?

La conexión remota consta de dos segmentos: la máquina de desarrollo que ejecuta Claude Code ←→ tu dispositivo de visualización. Si falla cualquiera de los dos, se manifiesta como «desconectado», pero los síntomas difieren:

Lo que ves	Causa probable	Ir a
La conversación se congela de repente; al reconectar, el progreso sigue en ese mismo punto	Suspensión / bloqueo de pantalla de la máquina de desarrollo	§1
Se desconecta justo al entrar en el ascensor, cambiar a 4G o cambiar de WiFi	Conexión persistente cortada	§2
Al cerrar la terminal local, o si la máquina local se suspende, la remota se cae inmediatamente	Limitación dura de las soluciones por espejado de pantalla	§3
Muestra en línea, pero los mensajes no llegan y no hay ningún error	Conexión semimuerta	§4
Se puede reconectar, pero vuelve a una sesión vacía / los mensajes de la desconexión se han perdido	La reconexión no retomó la sesión original	§5
Al cabo de varias horas, la sesión ha desaparecido	Proceso reciclado, sin recuperación en frío	§6

La más fácil de diagnosticar mal es la cuarta: no da ningún error. El estado de la conexión está en verde, los mensajes se envían, pero nunca hay respuesta; es más difícil de localizar que una desconexión directa, porque todos los indicadores te dicen que «todo es normal».

1. Suspensión de la máquina de desarrollo / bloqueo de pantalla / tapa cerrada

Síntomas: La conversación se queda completamente detenida en algún momento. Al reconectar, el progreso sigue exactamente donde se cortó, sin avanzar ni un paso.

Por qué: Muchos creen que «mi máquina de desarrollo está siempre encendida», pero la suspensión del sistema, el sueño al cerrar la tapa o el bloqueo programado de pantalla suspenden o matan directamente el proceso de Claude Code. En el lado del visor, lo que se ve es «de repente se quedó quieto».

Cómo confirmarlo: Vuelve a la máquina de desarrollo y mira si el proceso sigue existiendo y si los registros del sistema muestran eventos de suspensión. Si el proceso sigue pero la marca de tiempo está congelada en el momento de la desconexión, básicamente es esto.

Solución: Configura el plan de energía de la máquina de desarrollo para «no suspender / no suspender al cerrar la tapa». Es la única solución de raíz: ninguna solución remota puede salvar una máquina que ya se ha quedado dormida.

2. El cambio de red corta la conexión persistente

Síntomas: Se corta en un instante muy concreto: al entrar en el ascensor, al cambiar de WiFi a 4G, o cuando la banda ancha de casa vuelve a marcar a medianoche.

Por qué: La sincronización remota en tiempo real depende de una conexión persistente (WebSocket / SSH). En cuanto cambia la IP, esa conexión se invalida en el acto, sin margen de negociación.

Cómo confirmarlo: Si el momento de la desconexión coincide con el momento en que cambiaste de red, es esto.

Solución: Este tipo no se puede evitar; solo se puede contener con reconexión automática + retroceso exponencial (1s → 2s → 5s…, para no golpear la red en cuanto se cae). SSH pelado no tiene esta capacidad; si se corta, se cortó, y hay que reconectar a mano. A la hora de elegir solución, este es un requisito innegociable.

3. Soluciones de espejado de pantalla: la máquina local debe permanecer abierta en primer plano

Síntomas: Al cerrar la terminal local, o si la máquina local se suspende, la del móvil cae inmediatamente. No es un timeout lento; es la pérdida de la sincronización.

Por qué: El Remote Control oficial de Anthropic proyecta la sesión que se está ejecutando en tu máquina local hacia el móvil/navegador. Su premisa es que el Claude Code local esté abierto en primer plano y que la máquina local esté siempre en línea. Si la máquina local se cae, el lado remoto no tiene un ciclo de vida independiente al que agarrarse.

Cómo confirmarlo: Cierra la ventana de la terminal local y mira si la remota se cae en el mismo segundo. Si es así, estás usando una solución de espejado de pantalla.

Solución: Cambia a una arquitectura de servicio residente en el lado de la máquina de desarrollo: el lado que ejecuta la sesión se convierte en un servicio en segundo plano que se inicia con el arranque y vive independientemente de tu dispositivo de visualización. Aunque cierres, cambies o pierdas la conexión del visor, seguirá ejecutándose en la máquina de desarrollo. Esa es la diferencia esencial entre «espejado» y «servicio residente»; no se ajusta con parámetros.

4. Conexión semimuerta (half-open): la más difícil de detectar

Síntomas: Muestra en línea, los mensajes no reciben respuesta y tampoco da errores. Puede quedarse atascado unos minutos, o hasta que reconectes manualmente.

Por qué: Cuando la red se interrumpe en silencio (timeout de entradas NAT, pérdida de estado en dispositivos intermedios, señal tan débil que solo pierde paquetes pero no corta el enlace), los extremos TCP pueden creer ambos que siguen conectados, cuando en realidad los datos ya no pasan. Sin heartbeat, ambos mantienen esa ilusión.

Cómo confirmarlo: El estado de la conexión se ve normal, pero los mensajes enviados no tienen acuse de recibo ni error; al desconectar y reconectar manualmente se recupera al instante: eso es.

Solución: La conexión debe ejecutar heartbeat (ping de mantenimiento): si en un tiempo acordado no llega ninguna respuesta del otro extremo, se declara como conexión semimuerta y se reconecta activamente, en lugar de esperar. El criterio debe ser «no hay respuesta», no «no hay error»: una conexión semimuerta nunca da error.

5. La reconexión no retoma la sesión original / mensajes perdidos

Síntomas: Se puede reconectar tras una caída, pero o bien vuelves a una sesión vacía, o bien los mensajes enviados por la otra parte durante la desconexión han desaparecido.

Por qué: La reconexión solo crea una nueva conexión; no ha vuelto a suscribirse a la sesión original, y los mensajes de la desconexión no se han almacenado en caché para ti.

Cómo confirmarlo: Tras reconectar, el ID de sesión ha cambiado, o el historial solo empieza desde el momento de la reconexión.

Solución: Elige una solución que tras reconectar se suscriba automáticamente a la sesión original y reproduzca el historial del periodo de desconexión. Si solo reconecta pero no retoma la sesión, es como no haber reconectado.

6. El proceso de sesión es reciclado y no hay recuperación en frío

Síntomas: Las desconexiones cortas y reconexiones funcionan con normalidad, pero si vuelves después de varias horas, la sesión ha desaparecido.

Por qué: Los procesos de sesión inactivos durante mucho tiempo pueden ser reciclados, y el propio daemon puede haberse reiniciado (por actualización o relanzado tras un fallo). El estado de la sesión en memoria se pierde con ello.

Cómo confirmarlo: Solo se reproduce si la desconexión ha sido larga; no se reproduce con desconexiones cortas.

Solución: Se necesita capacidad de recuperación en frío: el estado de la sesión se guarda en disco, y aunque el proceso desaparezca, se puede restaurar el contexto desde el disco. Idealmente, envías un mensaje y se recupera solo y continúa, sin que lo notes.

Lista de verificación (aplicable a cualquier solución)

Recórrela en orden; cada paso se puede refutar de forma independiente:

1. ¿La máquina que ejecuta la sesión se suspendió o se bloqueó? → Desactiva la suspensión automática y el sueño al cerrar la tapa. (§1)
2. ¿Coincide el momento de la desconexión con el cambio de red? → Necesitas una solución con reconexión automática + retroceso, no SSH pelado. (§2)
3. ¿La remota se cae inmediatamente si cierras la terminal local? → Es la limitación dura del espejado; hay que cambiar a arquitectura de daemon residente. (§3)
4. ¿Atascado en «muestra en línea pero los mensajes no responden»? → Conexión semimuerta; solo un heartbeat puede recuperarla automáticamente. (§4)
5. ¿Sesión vacía o mensajes perdidos tras reconectar? → Necesitas «retomar la sesión original + reproducción del historial». (§5)
6. ¿Solo pierdes la sesión si la desconexión es larga? → Necesitas persistencia en disco + recuperación en frío. (§6)

Aterrizando en soluciones concretas

De los seis puntos anteriores, solo el 1 es un problema de configuración de tu propia máquina; los otros cinco están determinados por la arquitectura: quedan fijados al elegir la solución, y una vez que surge el problema, ajustar parámetros ya no puede salvar la situación.

Una solución remota que no se caiga necesita tener a la vez: un proceso daemon residente en la máquina de desarrollo (cubre el riesgo residual de §1 y §3), reconexión automática + retroceso (§2), detección por heartbeat (§4), reconexión a la sesión original + reproducción del historial (§5) y recuperación en frío desde disco (§6).

El conjunto PandaNpc + pandapaw se ha construido contrastando punto por punto estos seis criterios: pandapaw se registra en la máquina de desarrollo como un daemon residente que arranca con el sistema (no es una ventana de terminal que tengas que abrir manualmente; si se cae, se relanza automáticamente); el visor reconecta automáticamente con retroceso tras una caída; en la conexión corre un heartbeat, y si no recibe respuesta, la declara semimuerta y reconecta por su cuenta; tras reconectar, se suscribe automáticamente a la sesión original y reproduce el historial del periodo de desconexión; incluso si el proceso de la sesión es reciclado, basta con enviar un mensaje para recuperarlo en frío desde el disco y continuar.

Para los detalles de instalación y conexión, consulta «Acceso remoto a Claude Code»; para ver sesiones y aprobar herramientas desde el móvil, consulta «Claude Code en el móvil».

Una trampa adicional: ten cuidado con la facturación al ejecutar en remoto

Al diagnosticar desconexiones es fácil pasar a claude -p (modo headless) sin pensarlo, pero desde el 15 de junio de 2026 Anthropic ajustó la facturación: headless ya no consume la cuota de suscripción, sino que usa un pequeño crédito mensual de SDK; cuando se agota, se factura por API, y con un uso intensivo es fácil pasarse. El modo interactivo (claude REPL) sigue consumiendo la cuota de suscripción. Al cambiar de solución para diagnosticar desconexiones, ten cuidado de no cambiar también, de paso, el modelo de facturación.