OmniRoute Remote Mode : guide de dépannage 2026

Dans la documentation officielle d’OmniRoute, REQUEST_TIMEOUT_MS est indiqué à 600000 par défaut et STREAM_IDLE_TIMEOUT_MS hérite de cette valeur lorsqu’aucun réglage spécifique n’est fourni. Ce chiffre ne prouve toutefois pas qu’un client peut atteindre le serveur : pour OmniRoute Remote Mode, la bonne méthode consiste à confirmer d’abord la santé du service et le contexte distant, puis l’adresse, le jeton, le proxy et enfin le client. Réinstaller OmniRoute avant cette séquence fait souvent disparaître les indices utiles. (documentation officielle du guide d’installation)

Cette semaine, l’action recommandée est donc simple : conserver une copie des journaux, exécuter les tests depuis le poste réellement utilisé, et ne jamais résoudre une panne en ouvrant une interface d’administration sans authentification sur Internet.

Ce guide concerne :

• les développeurs qui se connectent depuis un ordinateur portable à une instance OmniRoute distante et obtiennent une expiration ou une liste de modèles vide ;
• les équipes qui font partager une passerelle IA distante à Claude Code, Cursor ou d’autres outils de développement ;
• les utilisateurs d’un Mac distant qui veulent vérifier la reprise après redémarrage, la coupure réseau et les longues réponses en flux.

Commencer par le cas trompeur : la connexion réussit, mais la requête reste locale

Le symptôme le plus coûteux n’est pas toujours « connexion impossible ». Un poste peut afficher une connexion réussie alors que les commandes suivantes utilisent encore l’instance locale.

Le mécanisme d’OmniRoute repose sur un contexte enregistré localement : celui-ci contient une URL de serveur et un identifiant d’accès. Le contexte default correspond généralement à l’instance locale, tandis qu’un contexte créé par omniroute connect peut cibler un serveur distant. Les commandes de configuration peuvent ensuite écrire les fichiers du client sur le poste local tout en récupérant le catalogue depuis le serveur distant. (documentation officielle du Remote Mode)

Le cas typique ressemble à ceci :

1. omniroute connect <hôte-distant> réussit ;
2. omniroute models list affiche pourtant les modèles connus du Mac local ;
3. omniroute setup-claude écrit une configuration qui vise localhost ;
4. Claude Code fonctionne, mais les journaux du serveur distant ne contiennent aucune requête.

Avant toute modification, exécutez :

omniroute contexts list
omniroute contexts current
omniroute models list

Puis comparez le résultat avec une commande explicitement distante :

omniroute setup-claude \
  --remote https://<domaine-distant> \
  --api-key <jeton-de-gestion> \
  --dry-run

Le point important est l’emplacement de la preuve. Le nom du contexte affiché dans l’interface ne suffit pas. Il faut rapprocher l’URL du contexte, le fichier généré sur le poste et une trace côté serveur. Si le serveur distant reste silencieux, la commande n’a pas suivi le chemin attendu.

Première étape : prouver que l’instance distante est réellement disponible

Un processus présent dans la liste du système ne signifie pas que l’application est prête. Le service peut être bloqué pendant une migration de données, démarré avec un mauvais répertoire persistant, écouter uniquement sur la boucle locale ou redémarrer sans conserver sa configuration.

Signaux à reconnaître

La panne se situe probablement dans cette couche si :

• omniroute connect expire immédiatement ou ne reçoit aucune réponse HTTP ;
• le port répond parfois, puis disparaît après un redémarrage ;
• le tableau de bord s’ouvre, mais les modèles, fournisseurs ou journaux sont absents ;
• le processus existe, alors que le endpoint de santé échoue ;
• la configuration revient à son état initial après chaque relance.

Commandes de prise de preuve

Sur le serveur distant, adaptez les commandes au mode d’installation :

omniroute doctor --json
omniroute doctor --no-liveness
ps aux | grep -i omniroute
ss -lntp | grep <port>
journalctl -u <service-omniroute> -n 200 --no-pager

Si le service est exécuté dans un conteneur :

docker ps
docker logs --tail 200 <conteneur-omniroute>
docker inspect <conteneur-omniroute>

Depuis le poste local, testez séparément la résolution, TCP et HTTP :

getent hosts <domaine-distant>
nc -vz <domaine-distant> <port>
curl -vk https://<domaine-distant>/<endpoint-sante>

Il faut conserver l’heure, le code HTTP, le certificat présenté et l’identifiant de requête lorsqu’il existe. La documentation officielle fournit notamment omniroute doctor, avec une sortie JSON destinée aux diagnostics automatisés. (référence officielle de omniroute doctor)

Conclusion de traitement

Si aucun port n’est ouvert, corrigez le service ou son adresse d’écoute. Si le port est ouvert mais que l’HTTP ne répond pas, inspectez l’application et le proxy. Si l’endpoint répond mais que le catalogue est vide, passez à la persistance et aux fournisseurs.

Après correction, vérifiez les quatre éléments suivants :

• le processus reste actif pendant plusieurs minutes ;
• l’endpoint de santé répond deux fois de suite ;
• le catalogue de modèles est toujours présent après un redémarrage ;
• le contexte local atteint la même URL que celle testée avec curl.

Deuxième étape : séparer délai réseau, port fermé et application muette

Un délai d’attente ne décrit pas une cause unique. Il peut signaler une adresse erronée, une règle de pare-feu, un tunnel arrêté, un service qui écoute sur une autre interface ou un proxy qui accepte la connexion sans transmettre la requête.

Signaux à reconnaître

• Échec immédiat de résolution : nom de domaine ou DNS incorrect.
• Refus TCP immédiat : hôte joignable, mais aucun service n’écoute sur le port demandé.
• Expiration TCP : filtrage, route absente, tunnel fermé ou adresse non exposée.
• Réponse HTTP rapide en erreur : le réseau fonctionne ; la couche applicative ou l’authentification doit être inspectée.
• Réponse du proxy mais aucune trace côté OmniRoute : chemin réécrit, mauvais upstream ou en-tête supprimé.

Prise de preuve

curl -vk --connect-timeout 10 \
  https://<domaine-distant>/<endpoint-sante>

curl -vk --resolve <domaine-distant>:443:<adresse-ip> \
  https://<domaine-distant>/<endpoint-sante>

nc -vz -w 10 <adresse-ip> <port>

Le test --resolve permet de distinguer le DNS du serveur réellement atteint. Il faut également vérifier que le service n’écoute pas uniquement sur 127.0.0.1 lorsque le proxy se trouve sur une autre machine. À l’inverse, exposer directement le port d’administration sur toutes les interfaces n’est pas une correction acceptable.

La documentation Remote Mode recommande un transport HTTPS ou un réseau privé de type Tailnet ; une adresse fournie sans schéma peut être interprétée comme HTTP, ce qui convient éventuellement à un réseau local mais pas à une entrée publique. (instructions officielles du Remote Mode)

Rappel de sécurité : ne désactivez pas l’authentification et n’ouvrez pas tous les ports pour « voir si cela marche ». Utilisez une URL HTTPS, un tunnel privé ou une règle réseau limitée aux postes autorisés, puis rétablissez immédiatement les contrôles si un test temporaire a été nécessaire.

Conclusion de traitement

• Si le DNS est en cause, corrigez le nom ou la zone avant de toucher à OmniRoute.
• Si le port est filtré, autorisez uniquement l’entrée nécessaire vers le proxy ou le tunnel.
• Si le proxy répond sans joindre l’origine, vérifiez son upstream et sa route.
• Si le service est accessible seulement depuis le réseau local, construisez d’abord un point d’entrée protégé.

Pour une équipe qui utilise un Mac distant comme nœud toujours actif, la stabilité de l’entrée réseau compte autant que la puissance de la machine. Un serveur éteint, une adresse qui change ou un tunnel lancé dans une session utilisateur non persistante produiront la même impression qu’une panne OmniRoute.

Troisième étape : contrôler le jeton et son périmètre réel

OmniRoute distingue le jeton d’accès utilisé par Remote Mode de la clé d’inférence utilisée pour les appels de modèles. Le premier autorise des commandes de gestion ; la seconde sert aux surfaces d’inférence, par exemple les requêtes compatibles OpenAI. Les mélanger produit une erreur d’authentification même lorsque le serveur est parfaitement joignable.

Signaux à reconnaître

• 401 ou message indiquant un jeton absent ou invalide ;
• 403 lors d’une modification alors que la lecture fonctionne ;
• models list fonctionne, mais setup-* échoue ;
• un jeton récemment créé n’est accepté qu’une seule fois ;
• la variable d’environnement contient une clé d’inférence au lieu d’un jeton de gestion.

Commandes de prise de preuve

env | grep -E 'OMNIROUTE|ANTHROPIC'
omniroute contexts current
omniroute tokens scopes
curl -vk \
  -H "Authorization: Bearer <jeton-de-gestion>" \
  https://<domaine-distant>/api/cli/whoami

La réponse de whoami doit être comparée au contexte actif : URL, utilisateur logique, état du jeton et périmètre. La documentation officielle décrit trois niveaux hiérarchiques : read, write et admin. Une commande de lecture peut donc fonctionner avec un jeton qui sera refusé pour une modification ou la gestion des jetons.

Conclusion de traitement

Utilisez le plus petit périmètre compatible avec la tâche :

• read pour consulter modèles, fournisseurs, journaux et usage ;
• write pour appliquer une configuration ou préparer un outil ;
• admin uniquement pour créer, révoquer ou gérer des ressources sensibles.

Après correction, ne vous contentez pas d’un seul test :

omniroute models list
omniroute setup-claude --dry-run
omniroute tokens list

La dernière commande ne doit être exécutée qu’avec un jeton administrateur. Pour une équipe, créez un jeton par poste ou par automatisation, avec un nom explicite, une durée contrôlée et une procédure de révocation documentée. La suppression d’un contexte local ne révoque pas nécessairement le jeton côté serveur ; la révocation doit être effectuée sur l’instance distante.

Quatrième étape : vérifier le contexte, le chemin client et les fichiers générés

Lorsque la connexion fonctionne mais que Remote Mode affiche une liste de modèles vide, la cause est souvent un chemin client incohérent plutôt qu’un problème de modèle.

Signaux à reconnaître

• contexts current indique default alors que le serveur attendu est distant ;
• une configuration générée contient localhost ;
• Claude Code répond, mais aucune requête n’apparaît dans les journaux distants ;
• un outil utilise la surface OpenAI-compatible alors que sa configuration attend la surface Anthropic ;
• le catalogue distant est correct, mais le client conserve une ancienne liste.

Prise de preuve

omniroute contexts list
omniroute contexts current

omniroute setup-claude \
  --remote https://<domaine-distant> \
  --api-key <jeton-de-gestion> \
  --dry-run

grep -R "localhost\|<domaine-distant>" ~/.claude ~/.config 2>/dev/null

Les commandes setup-* peuvent consulter le catalogue distant et écrire localement les fichiers propres à chaque outil. La documentation d’intégration précise notamment que setup-claude crée des profils locaux, tandis que --remote force la récupération depuis une URL distante. (guide officiel des intégrations CLI)

Pour Claude Code, vérifiez aussi la base URL et le jeton d’inférence réellement injectés :

env | grep -E 'ANTHROPIC_BASE_URL|ANTHROPIC_AUTH_TOKEN'

Ne déduisez pas le chemin réseau à partir du nom du profil ou du nom du modèle. La preuve doit provenir de trois endroits : fichier local, journal du client et journal du serveur.

Conclusion de traitement

Si un outil doit rester local, utilisez explicitement le contexte local. Si l’objectif est de faire passer les requêtes par la passerelle distante, activez le contexte distant ou fournissez --remote et --api-key à la commande concernée.

Pour une équipe avec plusieurs postes, documentez également la séparation des identifiants dans un guide sur l’isolation des accès pour plusieurs outils de développement, puis conservez les secrets dans des variables d’environnement ou un trousseau plutôt que dans un dépôt Git.

Cinquième étape : isoler les erreurs du proxy inverse et des réponses en flux

Un proxy inverse ajoute plusieurs points de rupture : chemin modifié, certificat incorrect, en-tête Authorization absent, tamponnage de la réponse ou fermeture d’une connexion inactive.

NGINX indique que proxy_pass peut remplacer une partie du chemin demandé lorsqu’une URI est incluse dans la directive. Cette différence suffit à transformer une route valide en endpoint introuvable. NGINX précise également que le tamponnage des réponses est activé par défaut et qu’il peut être désactivé pour transmettre les données au client au fur et à mesure. (guide officiel du proxy inverse NGINX)

Signaux à reconnaître

• la connexion simple réussit, mais une génération longue s’interrompt ;
• Claude Code reçoit les en-têtes puis reste bloqué ;
• le proxy renvoie 404, 401 ou 502, alors que l’origine fonctionne en local ;
• les journaux montrent une connexion client sans requête correspondante côté OmniRoute ;
• la réponse arrive en bloc à la fin au lieu d’être transmise progressivement.

Prise de preuve

Testez d’abord l’origine depuis la machine du proxy :

curl -vk http://127.0.0.1:<port>/<endpoint-sante>

Puis l’entrée publique :

curl -vk https://<domaine-distant>/<endpoint-sante>

Comparez :

• le chemin complet ;
• le code HTTP ;
• les en-têtes Authorization, Host et Content-Type ;
• le type de contenu attendu pour une réponse en flux ;
• l’heure de fermeture de la connexion.

Dans NGINX, une zone de flux peut nécessiter une configuration dédiée :

location / {
    proxy_pass http://127.0.0.1:<port>;
    proxy_set_header Host $host;
    proxy_set_header Authorization $http_authorization;
    proxy_buffering off;
}

Cet extrait est un point de départ, pas une configuration universelle : le chemin, le TLS, les règles d’accès et les délais doivent être validés selon l’installation. Les délais ne doivent pas être copiés depuis une liste générique. OmniRoute documente ses propres variables de requête et de flux, tandis que la couche Cloudflare possède ses propres limites. (référence officielle des réglages OmniRoute)

Cloudflare documente notamment un délai de lecture proxy par défaut de 125 secondes et un délai d’inactivité proxy de 900 secondes entre Cloudflare et l’origine ; ces valeurs appartiennent à Cloudflare et ne remplacent pas les réglages d’OmniRoute ou de NGINX. (limites officielles de connexion Cloudflare)

Conclusion de traitement

• Si l’origine échoue déjà, corrigez OmniRoute avant le proxy.
• Si l’origine fonctionne mais pas l’URL publique, corrigez le chemin, le certificat ou l’en-tête.
• Si les réponses longues sont coupées, inspectez le tamponnage et chaque délai d’inactivité.
• Si un tunnel privé est utilisé, testez le tunnel depuis le même poste que Claude Code.

Utiliser une décision conditionnelle plutôt que réinstaller

La séquence suivante permet de choisir l’action sans repartir de zéro :

• Si l’endpoint de santé échoue localement sur le serveur, vérifiez le processus, le répertoire persistant et les journaux ; ne modifiez pas encore le client.
• Si l’origine répond mais que l’entrée distante expire, vérifiez DNS, pare-feu, tunnel et certificat ; ne régénérez pas le jeton.
• Si whoami renvoie une erreur d’authentification, remplacez ou révoquez le jeton concerné ; ne réutilisez pas une clé d’inférence.
• Si la lecture fonctionne mais qu’une modification renvoie 403, choisissez un périmètre supérieur uniquement si la tâche l’exige ; ne donnez pas admin par défaut.
• Si les modèles distants sont visibles mais que Claude Code utilise localhost, corrigez le contexte ou le fichier client ; ne réinstallez pas OmniRoute.
• Si les requêtes courtes passent et les flux longs cassent, examinez le proxy, le tamponnage et les délais ; ne changez pas de modèle avant d’avoir vérifié le transport.
• Si le service revient après redémarrage mais perd son catalogue, inspectez le volume persistant et la procédure de démarrage ; ne considérez pas le redémarrage comme une validation.

Valider la réparation avec une matrice d’acceptation

Une réparation est terminée lorsque les scénarios suivants sont vérifiés, avec leur preuve conservée :

• [ ] un membre disposant de read consulte les modèles et les journaux ;
• [ ] un membre disposant de write peut préparer une configuration sans gérer les jetons ;
• [ ] un membre sans autorisation reçoit un refus attendu, sans accès aux données sensibles ;
• [ ] Claude Code ou l’outil cible produit une requête visible dans les journaux distants ;
• [ ] le serveur distant redémarre et retrouve son catalogue ;
• [ ] le poste local retrouve le contexte actif sans enregistrer une nouvelle clé en clair ;
• [ ] la révocation d’un jeton bloque effectivement les nouvelles commandes ;
• [ ] une requête longue traverse le proxy sans fermeture prématurée ;
• [ ] une coupure du poste client n’expose pas l’interface d’administration ;
• [ ] l’équipe sait qui reprend le diagnostic, où se trouvent les journaux et quel jeton doit être révoqué.

Pour les projets audio, vidéo ou de design qui lancent des traitements longs, ajoutez un test de génération suffisamment représentatif : une courte requête peut réussir alors qu’un flux de transcription, de rendu ou d’analyse d’image révèle un délai mal aligné.

Questions fréquentes

Pourquoi omniroute connect reste-t-il bloqué ou finit-il par expirer ?

Commencez par séparer le réseau du service applicatif. Testez la résolution du nom, l’ouverture du port et un endpoint HTTP de santé depuis le poste client, puis vérifiez l’adresse d’écoute et les journaux sur le serveur. Si le port répond mais qu’aucun endpoint ne renvoie de réponse, le problème vient du processus ou du proxy, pas du jeton.

Que faire si Remote Mode est connecté mais n’affiche aucun modèle ?

Le contexte actif peut être valide tout en pointant vers une autre instance. Affichez le contexte courant, comparez son URL avec celle du serveur attendu, puis lancez la commande de liste des modèles avec un paramètre distant explicite. Vérifiez également que le catalogue distant contient des fournisseurs actifs et que le client n’a pas conservé une configuration locale.

Comment corriger une authentification distante OmniRoute refusée ?

Ne confondez pas le jeton de gestion Remote Mode avec la clé d’inférence utilisée pour les requêtes de modèle. Contrôlez l’en-tête Authorization, l’état du jeton, son expiration et son périmètre read, write ou admin. Après correction, testez séparément une commande de lecture, une modification autorisée et un appel de modèle afin de confirmer le principe du moindre privilège.

Pourquoi Claude Code ne fonctionne-t-il plus après l’ajout d’un proxy inverse ?

Claude Code peut recevoir une URL de base incorrecte, un chemin réécrit ou un en-tête d’autorisation supprimé par le proxy. Vérifiez la différence entre la surface Anthropic et la surface OpenAI-compatible, puis observez les journaux du proxy et d’OmniRoute sur une requête réelle. Pour une réponse en flux, désactivez le tamponnage et contrôlez les délais d’inactivité.

Comment faire reprendre un client après le redémarrage d’OmniRoute ?

Après le redémarrage, confirmez d’abord que le service a retrouvé son répertoire persistant, son catalogue de modèles et son entrée HTTPS. Depuis le poste local, vérifiez le contexte actif et exécutez une commande de lecture avant de relancer Claude Code ou un autre outil. Si le jeton a été révoqué ou si l’URL a changé, recréez uniquement le contexte concerné.

Quand remplacer l’instance actuelle par un Mac distant maintenu en continu

Lorsque la panne est finalement attribuée à un ordinateur local souvent éteint, à une adresse réseau instable ou à un environnement partagé sans processus persistant, le problème n’est plus seulement OmniRoute. Une installation conservée sur le poste d’un développeur cumule généralement trois défauts : elle dépend de son alimentation et de sa session, elle rend les redémarrages difficiles à auditer, et elle oblige l’équipe à maintenir elle-même le tunnel, le proxy et les accès.

Un Mac distant exploité comme nœud continu offre alors une base plus cohérente pour les outils de développement, les traitements audio ou vidéo et les longues sessions Claude Code, à condition de valider l’accès HTTPS, la persistance, la reprise après redémarrage et la séparation des jetons. Les équipes peuvent examiner les options de location de Mac mini aux États-Unis ou demander une orientation via la page de contact de Vuncloud si elles ont besoin d’un environnement temporaire plutôt que d’administrer un serveur fragile.

La location n’est pas le meilleur choix pour une charge lourde permanente nécessitant des interfaces physiques spécifiques ou un contrôle matériel direct. En revanche, pour tester OmniRoute Remote Mode, fournir un poste distant à plusieurs développeurs ou valider une chaîne de déploiement sans laisser un Mac personnel allumé en permanence, elle réduit surtout le nombre de variables difficiles à reprendre en cas d’incident.

Blog

• Comparer le tunnel SSH et la connexion WebSocket sécurisée pour isoler une panne distante
• Suivre une installation distante complète avec vérifications SSH, VNC et diagnostic de passerelle
• Utiliser un tunnel SSH pour le débogage distant et la redirection sécurisée des ports