Dépannage des déconnexions distantes de Claude Code : symptômes, critères et solutions pour six types de déconnexion

Exécuter Claude Code à distance, le plus pénible n'est pas de ne pas pouvoir se connecter, mais de se connecter puis de se déconnecter, et à chaque fois pour une raison différente.

Le terme « déconnexion » recouvre en réalité six pannes totalement différentes. Leurs symptômes ont chacun leurs caractéristiques, et les solutions sont indépendantes les unes des autres : traiter une connexion longue invalidée par un changement de réseau comme un problème de mise en veille de la machine, même en désactivant la veille, ne sert à rien ; attendre qu’une connexion demi-morte se rétablisse en pensant que le réseau est simplement mauvais, même jusqu’au matin, elle ne se rétablira pas d’elle-même.

Cet article part de ce que vous observez réellement pour remonter aux causes : pour chaque type de déconnexion, il donne les symptômes, comment le confirmer, et la solution correspondante. Si vous voulez passer directement à l’action, rendez-vous à la checklist de diagnostic de la dernière section.

Cet article ne traite que du diagnostic des déconnexions. Pour savoir comment monter un accès distant, voir « Accès distant à Claude Code : contrôler vos sessions depuis n’importe où, même sans la machine locale » ; pour l’utilisation sur mobile, voir « Se connecter à Claude Code depuis un mobile : consulter vos sessions et approuver les outils sur iOS à tout moment ».

Commençons par les symptômes : lequel voyez-vous ?

Une connexion distante se compose de deux extrémités : la machine de développement qui exécute Claude Code ←→ l’appareil de consultation que vous tenez en main. Un problème sur l’une ou l’autre extrémité se manifeste par une « déconnexion », mais les symptômes diffèrent :

Ce que vous voyez	Cause probable	Aller à
La session s’arrête soudainement, et après reconnexion la progression est toujours au même point	Veille / verrouillage de la machine de développement	§1
Se déconnecte au moment où vous entrez dans un ascenseur, passez en 4G, changez de WiFi	Connexion longue coupée	§2
Dès que vous fermez le terminal local, ou que la machine locale se met en veille, la session distante se coupe immédiatement	Contrainte stricte du mode miroir	§3
Affiche en ligne, mais les messages restent sans réponse, sans aucune erreur	Connexion demi-morte	§4
Reconnexion possible, mais on revient à une session vide / les messages de la période de déconnexion ont disparu	La reconnexion ne reprend pas la session d’origine	§5
Après plusieurs heures, la session a disparu	Processus récupéré, et pas de récupération à froid	§6

La plus trompeuse est la quatrième : elle ne signale aucune erreur. L’état de la connexion est vert, les messages partent, mais il n’y a jamais de réponse — c’est encore plus difficile à diagnostiquer qu’une déconnexion franche, car tous les indicateurs vous disent que « tout va bien ».

1. Veille / verrouillage / fermeture de l’écran de la machine de développement

Symptômes : la session s’arrête complètement à un moment donné. Après reconnexion, la progression est toujours au point de la déconnexion, pas un pas de plus.

Pourquoi : beaucoup pensent que « ma machine de développement reste allumée », mais la mise en veille du système, le sommeil à la fermeture de l’écran, ou le verrouillage programmé suspendent ou tuent directement le processus de Claude Code. Côté appareil de consultation, on voit simplement « tout à coup, ça ne bouge plus ».

Comment le confirmer : retournez sur la machine de développement pour vérifier si le processus existe toujours et si les journaux système contiennent des traces de mise en veille. Si le processus est toujours là mais que l’horodatage s’est arrêté au moment de la déconnexion, c’est probablement la cause.

Solution : réglez le plan d’alimentation de la machine de développement sur « jamais de veille / ne pas dormir à la fermeture de l’écran ». C’est la seule façon de vraiment résoudre le problème — aucun accès distant ne peut sauver une machine déjà endormie.

2. Changement de réseau qui coupe la connexion longue

Symptômes : la déconnexion se produit à un instant très précis — entrer dans un ascenseur, passer du WiFi à la 4G, le redial de la box en pleine nuit.

Pourquoi : la synchronisation en temps réel à distance repose sur une connexion longue (WebSocket / SSH). Dès que l’IP change, cette connexion tombe immédiatement, sans aucune discussion.

Comment le confirmer : si le moment de la déconnexion correspond à celui du changement de réseau, c’est bien cela.

Solution : ce type de déconnexion est impossible à éviter ; il faut s’appuyer sur la reconnexion automatique + le backoff (1s→2s→5s…, pour éviter de bombarder aussitôt après une coupure). Le SSH brut n’a pas cette capacité : une fois coupé, c’est coupé, il faut le relancer manuellement. C’est un critère impératif dans le choix d’une solution.

3. Solution de type miroir : la machine locale doit rester au premier plan

Symptômes : dès que le terminal local est fermé, ou que la machine locale se met en veille, le téléphone se déconnecte immédiatement. Ce n’est pas une expiration progressive, c’est une perte de synchronisation.

Pourquoi : le Remote Control officiel d’Anthropic projette la session en cours d’exécution sur votre machine locale vers le téléphone / navigateur. Il exige que le processus Claude Code de la machine locale reste au premier plan et que la machine reste en ligne. Dès que la machine locale tombe, l’extrémité distante n’a aucun cycle de vie indépendant auquel se raccrocher.

Comment le confirmer : fermez la fenêtre du terminal local et observez si la session distante se coupe dans la même seconde. Si c’est le cas, vous utilisez une solution de type miroir.

Solution : passez à une architecture avec un service démon résident côté machine de développement — l’extrémité qui exécute les sessions devient un service en arrière-plan qui démarre au boot, vivant indépendamment de votre appareil de consultation. Que l’appareil de consultation soit fermé, changé ou déconnecté, le service continue de tourner sur la machine de développement. C’est la différence fondamentale entre « miroir » et « service résident », ce n’est pas un paramètre qu’on peut ajuster.

4. Connexion demi-morte (half-open) : la plus difficile à détecter

Symptômes : affiche en ligne, mais les messages restent sans réponse et aucune erreur n’est signalée. Cela peut durer quelques minutes, ou rester bloqué jusqu’à ce que vous vous reconnectiez manuellement.

Pourquoi : lors d’une interruption réseau silencieuse (expiration d’une entrée NAT, perte d’état sur un équipement intermédiaire, signal trop faible pour ne perdre que des paquets sans couper la liaison), les deux extrémités TCP peuvent toutes deux se croire encore connectées, alors que les données ne passent plus. Sans heartbeat, les deux parties entretiennent cette illusion indéfiniment.

Comment le confirmer : l’état de la connexion est normal, mais les messages envoyés ne reçoivent ni accusé de réception ni erreur ; après une déconnexion manuelle et une reconnexion, tout revient immédiatement — c’est bien cela.

Solution : il faut faire tourner un heartbeat (keepalive ping) sur la connexion : si aucune réponse de l’autre extrémité n’est reçue dans le délai convenu, on considère que la connexion est demi-morte et on la coupe pour se reconnecter, plutôt que d’attendre bêtement. Le critère doit être « aucune réponse reçue », pas « aucune erreur signalée » — une connexion demi-morte ne signale jamais d’erreur.

5. La reconnexion ne reprend pas la session d’origine / perte de messages

Symptômes : après une déconnexion, la reconnexion fonctionne, mais on arrive soit sur une session vide, soit les messages envoyés par l’autre partie pendant la déconnexion ont tous disparu.

Pourquoi : la reconnexion ne fait que rétablir une connexion, sans réabonner cette connexion à la session d’origine ; les messages de la période de déconnexion ne sont pas non plus mis en cache pour vous.

Comment le confirmer : après reconnexion, l’ID de session a changé, ou l’historique commence seulement au moment de la reconnexion.

Solution : choisissez une solution capable de se réabonner automatiquement à la session d’origine après reconnexion et de rejouer l’historique de la période de déconnexion. Une reconnexion sans reprise de session ne sert à rien.

6. Processus de session récupéré sans récupération à froid

Symptômes : les déconnexions courtes et les reconnexions fonctionnent normalement, mais après plusieurs heures, la session a disparu.

Pourquoi : un processus de session resté inactif longtemps peut être récupéré, et le démon lui-même peut avoir redémarré (mise à niveau, relance après crash). L’état de la session en mémoire disparaît alors.

Comment le confirmer : le problème ne se reproduit qu’après une longue déconnexion, pas après une courte.

Solution : il faut une capacité de récupération à froid — l’état de la session est persisté sur disque, et même si le processus a disparu, le contexte peut être restauré depuis le disque. Dans l’idéal, vous envoyez un message et la session se restaure automatiquement, sans que vous vous en aperceviez.

Checklist de diagnostic (utilisable avec n’importe quelle solution)

Passez dans l’ordre, chaque étape peut être infirmée de manière indépendante :

1. La machine qui exécute les sessions s’est-elle mise en veille / verrouillée ? → Désactivez la veille automatique, et ne pas dormir à la fermeture de l’écran. (§1)
2. Le moment de la déconnexion coïncide-t-il avec votre changement de réseau ? → Il faut une solution avec reconnexion automatique + backoff, pas de SSH brut. (§2)
3. Dès que le terminal local est fermé, la session distante se coupe-t-elle immédiatement ? → C’est une contrainte stricte du mode miroir, il faut passer à une architecture de démon résident. (§3)
4. Bloqué sur « affiche en ligne mais les messages restent sans réponse » ? → Connexion demi-morte, seul le heartbeat peut la rétablir automatiquement. (§4)
5. Après reconnexion, la session est vide / il manque des messages ? → Il faut « reprise de la session d’origine + rejeu de l’historique ». (§5)
6. Vous ne perdez la session qu’après une longue déconnexion ? → Il faut la persistance sur disque + la récupération à froid. (§6)

En pratique, sur les solutions concrètes

Parmi les six points ci-dessus, seul le premier est un problème de réglage de votre machine ; les cinq autres sont déterminés par l’architecture — ils sont figés au moment du choix de la solution, et aucun réglage de paramètres ne peut les corriger une fois le problème survenu.

Une solution distante sans déconnexion doit disposer simultanément : d’un processus démon résident côté machine de développement (pour le risque résiduel du §1 et le §3), de la reconnexion automatique + backoff (§2), du heartbeat (§4), de la reconnexion avec reprise de la session d’origine + rejeu de l’historique (§5), et de la persistance sur disque avec récupération à froid (§6).

L’ensemble PandaNpc + pandapaw a été conçu en suivant ces six points un par un : pandapaw est enregistré sur la machine de développement comme démon résident qui démarre au boot (pas une fenêtre de terminal que vous devez garder ouverte manuellement ; s’il plante, il est relancé automatiquement) ; côté appareil de consultation, la reconnexion automatique avec backoff est intégrée ; la connexion exécute un heartbeat, et si aucune réponse n’est reçue, elle est jugée demi-morte et la reconnexion est déclenchée ; après reconnexion, la session d’origine est automatiquement reprise et l’historique de la période de déconnexion est rejoué ; même si le processus de session est récupéré, un simple message restaure la session à froid depuis le disque.

Pour l’installation et la connexion, voir « Accès distant à Claude Code » ; pour la consultation des sessions et l’approbation des outils sur mobile, voir « Se connecter à Claude Code depuis un mobile ».

Un piège supplémentaire : ne vous faites pas piéger par la facturation en mode distant

En diagnostiquant les déconnexions, on a tendance à utiliser claude -p (mode headless) pour exécuter les sessions, mais depuis le 15 juin 2026, Anthropic a modifié la facturation — le mode headless ne consomme plus le quota de l’abonnement, mais un petit crédit SDK mensuel, et une fois épuisé, il est facturé selon l’API ; une utilisation intensive peut vite dépasser le budget. Le mode interactif (le REPL claude) consomme toujours le quota de l’abonnement. Quand vous changez de solution pour diagnostiquer les déconnexions, attention à ne pas changer aussi votre mode de facturation.