Troubleshooting (Français)

Référence rapide

Vous découvrez OmniRoute ? Commencez ici — ces solutions règlent 90 % des problèmes :

Je vois ceci	Ce que cela signifie	Ce qu’il faut faire
« Impossible de se connecter »	OmniRoute ne fonctionne pas	Exécutez omniroute ou docker restart omniroute
« Clé API non valide »	Votre clé est incorrecte ou a expiré	Copiez à nouveau la clé depuis le site web du fournisseur
« Limite de débit dépassée »	Vous envoyez trop de requêtes	Attendez 1 minute ou utilisez model: "auto" pour un basculement automatique
« Quota dépassé »	Vous avez épuisé votre quota gratuit ou payant	Connectez davantage de fournisseurs ou utilisez des fournisseurs gratuits (Kiro, Pollinations)
« Réponses lentes »	Le fournisseur est surchargé ou géographiquement éloigné	Utilisez model: "auto/fast" ou connectez un fournisseur plus rapide (Groq, Cerebras)
« Mauvais fournisseur utilisé »	auto a choisi un autre fournisseur	C’est normal ! auto choisit le meilleur. Imposez un fournisseur précis avec model: "openai/gpt-4o"
« 502 Bad Gateway »	Le fournisseur est indisponible	Attendez et réessayez, ou utilisez model: "auto" pour changer de fournisseur
« 401 Unauthorized »	Vos identifiants sont incorrects	Vérifiez votre clé API ou authentifiez-vous à nouveau avec OAuth
« omniroute n’est pas reconnu »	Les modules globaux de node sont absents du PATH Windows	Ajoutez votre préfixe npm global au PATH Windows. Trouvez-le avec npm config get prefix.
« 429 Too Many Requests »	Limite de débit atteinte	Attendez 1 minute ou connectez davantage de fournisseurs

Toujours bloqué ? Consultez le dépannage détaillé ci-dessous ou demandez de l’aide sur Discord.

---

Dépannage détaillé

---

Limitation du débit chez les fournisseurs gratuits (429 / 400 / 401)

Symptôme : lorsque vous utilisez model: "auto" avec des fournisseurs gratuits ou sans authentification (opencode, auggie, etc.), vous obtenez par intermittence des réponses HTTP 429, 400 ou 401 au lieu des résultats attendus. Les requêtes aboutissent lorsque vous réessayez la même invite quelques instants plus tard, mais les automatisations (tâches cron, agents, scripts) s’interrompent dès le premier échec.

Cause principale : trois modes de défaillance indépendants se cumulent :

1. Limite de débit du fournisseur (429) : les offres gratuites peuvent imposer un quota par fenêtre temporelle. Une rafale d’appels parallèles l’épuise, si bien que la requête suivante est refusée jusqu’à la réinitialisation de la fenêtre.
2. Modèle défaillant en transmission directe (400/401) : les groupes auto/* peuvent inclure des modèles en transmission directe provenant d’opencode, qui sont enregistrés dans le catalogue, mais ne disposent d’aucun identifiant actif (par exemple, oc/north-mini-code-free → 401). Le routeur automatique en essaie un, échoue, et l’erreur est propagée avant que le mécanisme de repli ne se déclenche.
3. Amplification liée à la concurrence (429 sous charge) : lorsque plusieurs sessions d’agent ou cron sollicitent auto simultanément, le taux de requêtes cumulé dépasse ce que les fournisseurs gratuits tolèrent, si bien que des appels légitimes sont signalés comme abusifs.

Correctif vérifié (signalé par la communauté, 2026-08-10) : ajustez trois variables d’environnement afin que la rotation, la concurrence et le mécanisme de repli absorbent l’instabilité des offres gratuites au lieu d’échouer :

export OMNIROUTE_ROTATE_ON_400=true           # passer à un autre modèle/fournisseur en cas de 400/401 (ignore les modèles défaillants en transmission directe)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # plafond d'admission explicite pour les requêtes lourdes (non défini par défaut : aucune limite du nombre de requêtes, voir la remarque ci-dessous)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # attente limitée plus longue pour obtenir une capacité de traitement lourd, plutôt qu'une erreur 503 réessayable immédiate

Définissez-les dans l’environnement du processus OmniRoute (le démon, par exemple via le plist LaunchAgent ou systemctl edit), puis redémarrez OmniRoute. L’indicateur de rotation est de loin le levier le plus efficace : il transforme un échec irrécupérable en une nouvelle tentative transparente auprès d’un fournisseur opérationnel du groupe.

Remarque : OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT limite le nombre de requêtes lourdes — à contexte long — exécutées simultanément ; cette limite est un mécanisme de contrôle d’admission, et non un limiteur de débit du fournisseur. Mise à jour concernant la démultiplication des erreurs #503 : cette variable n’est plus définie par défaut (elle ne s’applique désormais que lorsqu’elle est configurée explicitement, comme ci-dessus) — l’admission des requêtes lourdes est plutôt contrôlée par un budget en octets dérivé automatiquement (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES), qui s’ajuste en fonction de la limite de mémoire réelle de l’hôte. Ainsi, un nouveau déploiement devrait rencontrer beaucoup moins de rejets 503 chat_admission_busy sans qu’il soit nécessaire de définir cette variable ; la définir explicitement ici continue néanmoins de fonctionner exactement comme indiqué. Les remplacements explicites du budget en octets sont limités à une plage de 8 MiB à 2 GiB. Une erreur 413 body_exceeds_budget n’est pas transitoire : augmentez ce budget en octets, réduisez OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES ou augmentez la limite de mémoire du processus. Un délestage inflight_bytes_budget correspond à une contention temporaire et peut toujours faire l’objet d’une nouvelle tentative. La limitation du débit propre à chaque fournisseur (open-sse/services/rateLimitManager.ts) est gérée séparément par RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH et RATE_LIMIT_AUTO_ENABLE — consultez .env.example.

Comment vérifier que cela a fonctionné : exécutez votre agent/cron deux fois de suite à quelques instants d’intervalle et confirmez que les deux exécutions réussissent. Avant le correctif, la deuxième exécution renvoie généralement une erreur 429/401. Après le correctif, les échecs éventuels sont réessayés de manière transparente et l’appel aboutit. Vous pouvez également exécuter curl /monitoring/health et surveiller le champ rateLimitedUntil des connexions aux fournisseurs ainsi que circuitBreakers.providerBreakers[].state pour les fournisseurs concernés — l’état peut être CLOSED, DEGRADED, OPEN ou HALF_OPEN (voir src/shared/utils/circuitBreaker.ts), et un fournisseur qui continue d’échouer passera de CLOSED → DEGRADED → OPEN avant que la fenêtre de réinitialisation n’autorise une requête de test (HALF_OPEN).

Si vous voyez toujours une erreur 429 : le compte actif de ce fournisseur a réellement épuisé son quota (et il ne s’agit pas simplement d’une limitation de débit). Ajoutez un deuxième compte pour le même fournisseur dans le tableau de bord OmniRoute → Providers → Accounts, ou ajoutez un autre fournisseur gratuit (par exemple routeway, auggie). La rotation n’est utile que pour les erreurs transitoires de limitation de débit/400/401 ; l’épuisement total d’un quota nécessite un deuxième identifiant d’accès ou un autre fournisseur.

Si vous voyez une erreur 403 sur les modèles de vision (auto/vision, bazaarlink/*) : le compte connecté ne dispose pas d’un forfait payant incluant la vision, ou la clé API ne possède pas les autorisations suffisantes. Vérifiez dans le tableau de bord du fournisseur que la portée de la clé inclut la vision/le multimodal, ou connectez un compte payant et conservez-le comme cible pour la vision.

---

Avertissements lors de npm install (ERESOLVE / peer / deprecated)

Lorsque vous exécutez npm install -g omniroute, vous pouvez voir s’afficher une multitude d’avertissements tels que npm warn ERESOLVE, des notifications concernant les dépendances homologues et des messages deprecated. Ces avertissements sont attendus et sans conséquence. L’installation a réussi si la sortie contient added <N> packages.

Pour supprimer les avertissements de résolution des dépendances homologues, utilisez la forme d’installation prise en charge par OmniRoute :

npm install -g omniroute --legacy-peer-deps

--legacy-peer-deps supprime uniquement les notifications ERESOLVE et celles concernant les dépendances homologues. Les avis d’obsolescence restent visibles, car ils proviennent de paquets tiers transitifs ; ils ne signifient pas que l’installation a échoué.

Les avertissements proviennent de plages de versions de dépendances homologues obsolètes dans des paquets tiers qu’OmniRoute ne contrôle pas :

1. marked-terminal nécessite marked >=1 <16, mais marked@18 a été trouvé — cela fonctionne correctement en pratique ; la plage de dépendances homologues du projet en amont est simplement obsolète.
2. deprecated prebuild-install@7.1.3 — un utilitaire transitif de récupération de binaires natifs. Il n’est pas utilisé pour installer la liaison de transport wreq-js épinglée et ne signifie pas que la configuration du transport du fournisseur de cookies web a échoué.

Aucune action requise — les avertissements ne peuvent pas être entièrement supprimés sans créer des forks des paquets en amont.

---

Gemini Web et Playwright Chromium

Si une requête Gemini Web renvoie 503 avec un message indiquant que Playwright Chromium n’est pas installé, le paquet npm est présent, mais le binaire du navigateur est absent. Playwright sépare délibérément le téléchargement des navigateurs de l’installation du paquet npm ; cette réponse est donc attendue tant que le navigateur n’est pas installé.

Pour une installation npm globale, installez Chromium depuis le répertoire du paquet OmniRoute afin que le cache du navigateur appartienne à la même installation de Playwright :

cd "$(npm root -g)/omniroute"
npx playwright install chromium

Redémarrez OmniRoute après l’installation, puis réessayez la requête Gemini Web. Si vous exécutez OmniRoute depuis une image Docker, utilisez l’image -web (ou la cible de compilation runner-web), qui inclut Chromium et ses dépendances ; l’image de base ne les inclut pas.

---

Solutions rapides

Problème	Solution
La première connexion ne fonctionne pas	Définissez INITIAL_PASSWORD dans .env (aucune valeur par défaut codée en dur)
Le tableau de bord s’ouvre sur le mauvais port	Définissez PORT=20128 et NEXT_PUBLIC_BASE_URL=http://localhost:20128
Aucun journal n’est écrit sur le disque	Définissez APP_LOG_TO_FILE=true et vérifiez que la capture du journal des appels est activée
EACCES : autorisation refusée	Définissez DATA_DIR=/path/to/writable/dir pour remplacer ~/.omniroute
La stratégie de routage n’est pas enregistrée	Mettez à jour vers la dernière version v3.x (le correctif du schéma Zod pour la persistance des paramètres a été publié dans des versions antérieures)
Plantage à la connexion / page blanche	Vérifiez la version de Node.js — consultez Compatibilité avec Node.js ci-dessous
dlopen / slice is not valid mach-o file (macOS)	Exécutez cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute — consultez Recompilation du module natif sous macOS ci-dessous
Échec de récupération (« fetch failed ») du proxy	Vérifiez que la configuration du proxy est définie au niveau approprié — consultez Problèmes de proxy ci-dessous
Docker curl: (56) Recv failure: Connection reset by peer	La liaison de port Docker peut utiliser IPv6. Utilisez -p 127.0.0.1:20128:20128 pour forcer IPv4, ou testez avec curl -4. Consultez IPv6 avec Docker ci-dessous
L’antivirus met README.md en quarantaine	Faux positif — consultez Faux positifs des antivirus ci-dessous
Kaspersky signale l’application de bureau comme un cheval de Troie	Faux positif comportemental dû au programme d’installation non signé — consultez Faux positifs des antivirus ci-dessous

---

Faux positifs des antivirus

Avast/AVG met README.md en quarantaine avec MD:HttpRequest-inf[Susp]

Il s’agit d’un faux positif. Rien n’est infecté et aucune action n’est requise.

Avast et AVG utilisent une heuristique qui signale les fichiers texte brut/Markdown contenant de nombreux liens ressemblant à des requêtes HTTP. Le fichier README.md d’OmniRoute est inclus dans le package npm (il est répertorié dans package.json → files) ; lors d’une installation globale, il se retrouve donc dans node_modules/omniroute/README.md — et contient environ 15 exemples http://localhost:20128/... (les points de terminaison HTTP/SSE de MCP, l’URL A2A .well-known et des extraits curl). Cette densité de liens suffit à déclencher l’heuristique.

Si cela n’a commencé que récemment : la nature du fichier n’a pas changé. Le tableau des points de terminaison du README s’est étoffé (MCP HTTP + SSE + A2A ont été ajoutés), tout comme le nombre d’exemples curl, ce qui lui a fait dépasser le seuil.

Ce fichier est une documentation inerte ne contenant aucun contenu exécutable. Vous pouvez le restaurer depuis la quarantaine en toute sécurité.

Que faire :

1. Arrêter les notifications — excluez le répertoire d’installation dans votre antivirus (Avast : Paramètres → Exceptions), en ajoutant le chemin de votre répertoire global node_modules et/ou le répertoire de données d’OmniRoute (~/.omniroute/).
2. Signaler le faux positif — https://www.avast.com/false-positive-file-form.php, en joignant le fichier README.md mis en quarantaine. C’est la correction qui aide tout le monde, puisque l’heuristique de l’éditeur réagit de manière excessive à un fichier texte.

Pourquoi nous ne « corrigeons » pas cela de notre côté : tous les exemples utilisent http://localhost, et localhost ne peut pas utiliser https sans les contraintes liées aux certificats autosignés. Altérer la documentation pour contourner l’heuristique d’un seul éditeur nuirait à tous les lecteurs pour satisfaire un bogue d’analyseur.

Kaspersky signale l’application de bureau comme PDM:Trojan.Win32.Generic

Il s’agit d’un faux positif provenant d’une heuristique comportementale. Rien n’est infecté. Le préfixe PDM: de Kaspersky signifie que le verdict provient de son module de défense proactive (System Watcher), qui évalue ce que le programme d’installation fait plutôt que de le comparer à des logiciels malveillants connus. Lorsqu’il se déclenche, Kaspersky « annule » l’ensemble de l’installation — en supprimant les fichiers qu’il avait déjà écrits — si bien que l’application finit par être défectueuse ou absente.

Les fichiers qu’il signale sont des composants standard de dépendances open source déclarées et incluses avec l’application de bureau, par exemple :

• resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js et workerProcessEntry.js — Playwright, la bibliothèque d’automatisation de navigateur utilisée pour la connexion aux fournisseurs depuis l’application et les conversations reposant sur un navigateur.
• resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — la liaison native wreq-js dont la version est épinglée, utilisée pour les requêtes HTTP avec empreinte de navigateur auprès des fournisseurs utilisant des cookies web (<arch> vaut x64 ou arm64).

Pourquoi cela se déclenche : le programme d’installation Windows n’est pas encore signé numériquement ; un programme d’installation NSIS non signé ne bénéficie donc d’aucune réputation, et les heuristiques comportementales fonctionnent avec une agressivité maximale. Combiné à une DLL native incluse et à des centaines de fichiers .js écrits sous %LOCALAPPDATA%\Programs\OmniRoute (y compris des répertoires de packages avec suffixe de hachage provenant de la version autonome de Next.js), cela suffit à déclencher l’heuristique. La signature du code est prévue ; d’ici là, le problème peut se reproduire avec les nouvelles versions.

Que faire :

1. Vérifiez d’abord votre téléchargement (afin d’écarter l’hypothèse d’un fichier altéré). Chaque version publie latest.yml, dont le champ sha512 (base64) couvre le programme d’installation OmniRoute.Setup.<version>.exe. Dans PowerShell, depuis le dossier contenant le programme d’installation :

   $b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
     [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
   [Convert]::ToBase64String($b)

   La sortie doit correspondre à latest.yml → sha512. Si ce n’est pas le cas, supprimez le fichier et téléchargez-le à nouveau uniquement depuis la page des versions GitHub.
2. Restaurez et excluez — restaurez depuis la quarantaine les éléments supprimés lors de l’annulation et ajoutez une exclusion pour %LOCALAPPDATA%\Programs\OmniRoute (Kaspersky → Paramètres → Menaces et exclusions), puis réinstallez l’application.
3. Signalez le faux positif — https://opentip.kaspersky.com/. Les signalements de faux positifs envoyés par les utilisateurs accélèrent réellement l’ajout à la liste d’autorisation.

---

Compatibilité avec Node.js

La page de connexion plante ou affiche l’erreur « Module self-registration »

Cause : Vous utilisez une version de Node.js qui ne respecte pas la version minimale sécurisée approuvée par OmniRoute. Le cas le plus courant est l’utilisation d’une ancienne version corrective de Node 22 ou 24, antérieure à la version minimale corrigée requise par OmniRoute pour des raisons de sécurité.

Symptômes :

• La page de connexion affiche un écran vide ou une erreur du serveur
• La console affiche Error: Module did not self-register ou des erreurs similaires liées aux bindings natifs
• La page de connexion affiche une bannière d’avertissement orange indiquant votre version de Node si l’environnement d’exécution ne respecte pas la politique de sécurité prise en charge

Correctif :

1. Installez une version LTS prise en charge de Node.js (recommandation : Node.js 24.x) :

   nvm install 24
   nvm use 24

2. Vérifiez votre version : node --version doit afficher v24.0.0 ou une version ultérieure de la branche LTS 24.x
3. Réinstallez OmniRoute : npm install -g omniroute
4. Redémarrez : omniroute

Versions sécurisées prises en charge : >=22.22.2 <23 ou >=24.0.0 <27. Node.js 24.x LTS (Krypton) et Node.js 26 sont entièrement pris en charge.

npm v11+ : better-sqlite3 n’est pas installé (Cannot find module)

Cause : npm v11 (fourni avec Node.js 24+) bloque par défaut les scripts d’installation des dépendances facultatives. Comme better-sqlite3 figure dans optionalDependencies et nécessite une compilation native (node-gyp rebuild), npm l’ignore silencieusement.

Symptômes :

• Le serveur plante au démarrage avec Cannot find module 'better-sqlite3'
• ls node_modules/better-sqlite3 affiche « No such file or directory »
• npm ls better-sqlite3 affiche (empty)

Correctif :

1. Approuvez les scripts d’installation et réinstallez :

   npm approve-scripts better-sqlite3
   npm install

2. Vous pouvez également installer manuellement la version précompilée :

   npm pack better-sqlite3@13.0.1
   tar -xzf better-sqlite3-*.tgz -C node_modules
   mv node_modules/package node_modules/better-sqlite3
   rm better-sqlite3-*.tgz

3. Vérifiez que cela fonctionne : node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

macOS : dlopen / « slice is not valid mach-o file »

Cause : Après une installation globale avec npm install -g omniroute, le binaire natif de better-sqlite3 inclus dans le package peut avoir été compilé pour une architecture ou une ABI Node.js différente de celle utilisée localement. Ce problème est courant sous macOS (aussi bien sur Apple Silicon que sur Intel) lorsque le binaire précompilé ne correspond pas à votre environnement.

Symptômes :

• Le serveur échoue immédiatement au démarrage avec une erreur dlopen
• L’erreur contient slice is not valid mach-o file
• Exemple complet :

dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)

Correctif — recompilez pour votre environnement local (aucune rétrogradation de Node.js n’est nécessaire) :

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

Remarque : Cette opération recompile le binding natif pour votre version locale de Node.js et l’architecture de votre processeur, ce qui résout l’incompatibilité du binaire. La plage d’environnements d’exécution officiellement prise en charge est >=22.22.2 <23 ou >=24.0.0 <27 (SUPPORTED_NODE_RANGE dans src/shared/utils/nodeRuntimeSupport.ts, alignée sur le champ engines de package.json). Node.js 24.x LTS (Krypton) et Node.js 26 sont entièrement pris en charge avec better-sqlite3 v12.x.

---

Problèmes de proxy

La validation du fournisseur affiche « fetch failed »

Cause : Le point de terminaison de validation de la clé API (POST /api/providers/validate) contournait auparavant la configuration du proxy, provoquant des échecs dans les environnements nécessitant un routage par proxy.

Correction (v3.5.5+) : Ce problème est désormais corrigé. La validation du fournisseur passe par runWithProxyContext, en respectant automatiquement les paramètres de proxy propres au fournisseur et les paramètres globaux.

La vérification de l’état du jeton échoue avec « fetch failed »

Cause : L’actualisation en arrière-plan des jetons OAuth ne résolvait pas la configuration du proxy pour chaque connexion.

Correction (v3.5.5+) : Le planificateur de vérification de l’état des jetons résout désormais la configuration du proxy pour chaque connexion avant de tenter une actualisation. Mettez à jour vers v3.5.5+.

Le proxy SOCKS5 renvoie « invalid onRequestStart method »

Cause : Sous Node.js 22, le répartiteur undici@8 est incompatible avec l’implémentation intégrée de fetch() de Node.

Correction (v3.5.5+) : OmniRoute utilise désormais la propre fonction fetch() d’undici lorsqu’un répartiteur de proxy est actif, garantissant ainsi un comportement cohérent. Mettez à jour vers v3.5.5+.

Proxy MITM sous WSL : les applications de bureau sur l’hôte Windows ne sont pas interceptées

Cause : Le proxy MITM et son certificat d’autorité de certification sont installés dans l’environnement où OmniRoute s’exécute. Sous WSL, cet environnement correspond au système Linux invité, tandis que les applications d’IA de bureau (Kiro, Trae, Copilot, Zed, …) s’exécutent sur l’hôte Windows. Les applications de l’hôte ne font pas confiance au magasin de certificats du système invité et n’acheminent pas leur trafic par le proxy système de celui-ci ; l’interception des applications de bureau ne s’active donc pas.

Recommandation : Exécutez OmniRoute nativement sur le même système d’exploitation que les applications de bureau que vous souhaitez intercepter (Windows pour les applications Windows ; de même pour macOS/Linux). Conserver OmniRoute dans WSL tout en ciblant les applications de l’hôte nécessite d’approuver manuellement le certificat d’autorité de certification généré sur l’hôte Windows et de configurer les paramètres réseau/proxy de chaque application hôte pour utiliser le point de terminaison du proxy WSL — une configuration non prise en charge et fragile.

---

Problèmes liés aux fournisseurs

« Language model did not provide messages »

Cause : Quota du fournisseur épuisé.

Correction :

1. Vérifiez le suivi des quotas dans le tableau de bord
2. Utilisez une combinaison avec des niveaux de secours
3. Passez à un niveau moins cher/gratuit

Limitation du débit

Cause : Quota de l’abonnement épuisé.

Correction :

• Ajoutez une solution de secours : cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
• Utilisez GLM/MiniMax comme solution de secours économique

Jeton OAuth expiré

OmniRoute actualise automatiquement les jetons. Si les problèmes persistent :

1. Tableau de bord → Fournisseur → Reconnecter
2. Supprimez et ajoutez à nouveau la connexion au fournisseur

Kiro avec plusieurs comptes : le deuxième compte invalide le premier

Cause : Le backend de Kiro n’autorise qu’une seule session active par enregistrement de client OIDC. Lorsque deux comptes partagent le même client enregistré (connexions importées avant v3.8.0), l’actualisation du jeton d’un compte invalide le jeton d’actualisation de l’autre.

Correction (v3.8.0+) : Réimportez les connexions concernées. À partir de v3.8.0, chaque nouvelle connexion Kiro créée via Importation de jeton, connexion sociale Google/GitHub ou Importation automatique enregistre automatiquement son propre client OIDC dédié. La connexion est donc entièrement isolée et l’actualisation d’un compte n’a aucun effet sur les autres comptes.

Les connexions importées avant v3.8.0 ne disposent pas d’un enregistrement de client propre à chaque connexion. Ces connexions continuent d’utiliser le point de terminaison d’actualisation partagé de l’authentification sociale. Pour bénéficier de l’isolation, supprimez l’ancienne connexion depuis Tableau de bord → Fournisseurs et ajoutez-la à nouveau via l’un des trois processus d’importation.

Pour obtenir tous les détails et des instructions étape par étape afin d’ajouter deux comptes Kiro côte à côte, consultez docs/guides/KIRO_SETUP.md.

---

Problèmes liés au cloud

Erreurs de synchronisation avec le cloud

1. Vérifiez que BASE_URL pointe vers votre instance en cours d’exécution (par exemple, http://localhost:20128)
2. Vérifiez que CLOUD_URL pointe vers votre point de terminaison cloud (par exemple, https://omniroute.dev)
3. Veillez à ce que les valeurs NEXT_PUBLIC_* correspondent aux valeurs côté serveur

stream=false renvoie une erreur 500 dans le cloud

Symptôme : Unexpected token 'd'... sur le point de terminaison cloud pour les appels sans streaming.

Cause : Le service en amont renvoie une charge utile SSE alors que le client attend du JSON.

Solution de contournement : Utilisez stream=true pour les appels directs au cloud. L’environnement d’exécution local inclut un mécanisme de repli SSE→JSON.

Le cloud indique qu’il est connecté, mais affiche « Invalid API key »

1. Créez une nouvelle clé depuis le tableau de bord local (/api/keys)
2. Lancez la synchronisation avec le cloud : Activer le cloud → Synchroniser maintenant
3. Les clés anciennes ou non synchronisées peuvent toujours renvoyer 401 dans le cloud

---

Problèmes liés à Docker

IPv6 Docker / Réinitialisation de la connexion

Symptômes : curl http://localhost:20128/v1/models renvoie curl: (56) Recv failure: Connection reset by peer. Le tableau de bord et les points de terminaison non authentifiés fonctionnent, mais les points de terminaison authentifiés échouent — cela ressemble à un problème d’authentification, mais ce n’est pas le cas.

Cause : docker run -p 20128:20128 publie à la fois sur 0.0.0.0 (IPv4) et :: (IPv6), mais le processus à l’intérieur du conteneur écoute uniquement sur IPv4. Sur les hôtes où localhost est d’abord résolu en ::1, la connexion arrive sur le port IPv6 publié sans qu’aucun processus n’écoute derrière celui-ci → réinitialisation de la connexion.

Correctif :

1. Diagnostic rapide : Exécutez curl -4 http://localhost:20128/v1/models. Si cela fonctionne avec -4, mais échoue sans cette option, vous avez une incompatibilité de liaison IPv6.
2. Correctif permanent : Liez explicitement le port à IPv4 en utilisant -p 127.0.0.1:20128:20128 dans votre commande docker run :

   docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
     -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

   Cela force la liaison IPv4 et évite également d’exposer le proxy sur toutes les interfaces de l’hôte.

---

L’outil CLI est indiqué comme non installé

1. Vérifiez les champs de l’environnement d’exécution : curl http://localhost:20128/api/cli-tools/runtime/codex | jq
2. Pour le mode portable : utilisez la cible d’image runner-cli (CLI incluses)
3. Pour le mode de montage de l’hôte : définissez CLI_EXTRA_PATHS et montez le répertoire des exécutables de l’hôte en lecture seule
4. Si installed=true et runnable=false : l’exécutable a été trouvé, mais le contrôle d’intégrité a échoué

Validation rapide de l’environnement d’exécution

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

---

Problèmes liés aux coûts

Coûts élevés

1. Consultez les statistiques d’utilisation dans Tableau de bord → Utilisation
2. Remplacez le modèle principal par GLM/MiniMax
3. Utilisez l’offre gratuite (Qoder, Kiro) pour les tâches non critiques
4. Définissez des budgets de coûts pour chaque clé API : Tableau de bord → Clés API → Budget

---

Débogage

Activer les fichiers journaux

Définissez APP_LOG_TO_FILE=true dans votre fichier .env. Les journaux de l’application sont écrits dans logs/. Les artefacts des requêtes sont stockés dans ${DATA_DIR}/call_logs/ lorsque le pipeline de journalisation des appels est activé dans les paramètres. Lorsque la capture du pipeline est activée, définissez CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false pour omettre les charges utiles des fragments de flux, ou ajustez CALL_LOG_PIPELINE_MAX_SIZE_KB pour modifier la taille maximale des artefacts en Ko.

Vérifier l’état des fournisseurs

# Tableau de bord d’état
http://localhost:20128/dashboard/health

# Contrôle d’intégrité de l’API
curl http://localhost:20128/api/monitoring/health

Stockage de l’environnement d’exécution

• État principal : ${DATA_DIR}/storage.sqlite (fournisseurs, combinaisons, alias, clés, paramètres)
• Utilisation : tables SQLite dans storage.sqlite (usage_history, call_logs, proxy_logs) + ${DATA_DIR}/call_logs/ facultatif
• Journaux de l’application : <repo>/logs/... (lorsque APP_LOG_TO_FILE=true)
• Artefacts des journaux d’appels : ${DATA_DIR}/call_logs/YYYY-MM-DD/... lorsque le pipeline de journalisation des appels est activé

L’action Nettoyer l’historique de la page Journaux des requêtes efface call_logs, l’ancien request_detail_logs et le répertoire local d’artefacts ${DATA_DIR}/call_logs/.

---

Problèmes de disjoncteur

Fournisseur bloqué à l’état OPEN

Lorsque le disjoncteur d’un fournisseur est à l’état OPEN, les requêtes sont bloquées jusqu’à l’expiration du délai de récupération.

Solution :

1. Accédez à Tableau de bord → Paramètres → Résilience
2. Consultez la carte du disjoncteur correspondant au fournisseur concerné
3. Cliquez sur Tout réinitialiser pour réinitialiser tous les disjoncteurs, ou attendez l’expiration du délai de récupération
4. Vérifiez que le fournisseur est effectivement disponible avant de procéder à la réinitialisation

Le fournisseur déclenche continuellement le disjoncteur

Si un fournisseur passe à plusieurs reprises à l’état OPEN :

1. Consultez Tableau de bord → Santé → Santé des fournisseurs pour identifier le schéma des échecs
2. Accédez à Paramètres → Résilience → Profils des fournisseurs et augmentez le seuil d’échec
3. Vérifiez si le fournisseur a modifié les limites de son API ou exige une nouvelle authentification
4. Examinez la télémétrie de latence — une latence élevée peut provoquer des échecs dus à l’expiration du délai

---

Problèmes de transcription audio

Erreur « Modèle non pris en charge »

• Utilisez un identifiant de modèle dont le premier segment correspond à un fournisseur pour lequel vous disposez d’identifiants (openai/whisper-1, openrouter/deepgram/nova-3). L’identifiant simple deepgram/nova-3 nécessite une clé Deepgram native.
• Vérifiez que le fournisseur est connecté dans Tableau de bord → Fournisseurs

La transcription est vide ou échoue

• Vérifiez les formats audio pris en charge : mp3, wav, m4a, flac, ogg, webm
• Vérifiez que la taille du fichier respecte les limites du fournisseur (généralement < 25MB)
• Vérifiez la validité de la clé API du fournisseur dans la carte correspondante

---

Débogage du traducteur

Utilisez Tableau de bord → Traducteur pour déboguer les problèmes de conversion de format :

Mode	Quand l’utiliser
Bac à sable	Comparez côte à côte les formats d’entrée et de sortie — collez une requête qui échoue pour voir comment elle est convertie
Testeur de chat	Envoyez des messages en direct et examinez la charge utile complète de la requête et de la réponse, y compris les en-têtes
Banc de test	Exécutez des tests par lots sur différentes combinaisons de formats afin d’identifier les conversions défectueuses
Moniteur en direct	Observez le flux de requêtes en temps réel afin de détecter les problèmes de conversion intermittents

Problèmes de format courants

• Les balises de réflexion ne s’affichent pas — Vérifiez si le fournisseur cible prend en charge la réflexion ainsi que le paramètre de budget de réflexion
• Les appels d’outils sont supprimés — Certaines conversions de format peuvent supprimer les champs non pris en charge ; vérifiez-les en mode Bac à sable
• L’invite système est absente — Claude et Gemini gèrent différemment les invites système ; vérifiez la sortie de la conversion
• Le SDK renvoie une chaîne brute au lieu d’un objet — Résolu dans v1.x ; le dispositif de nettoyage des réponses supprime les champs non standard (x_groq, usage_breakdown, etc.) qui provoquent des échecs de validation Pydantic dans le SDK OpenAI. Si le problème persiste dans v3.x+, veuillez le signaler.
• GLM/ERNIE refuse le rôle system — Résolu dans v1.x ; le normalisateur de rôles fusionne automatiquement les messages système avec les messages utilisateur pour les modèles incompatibles. Si le problème persiste dans v3.x+, veuillez le signaler.
• Le rôle developer n’est pas reconnu — Résolu dans v1.x ; il est automatiquement converti en system pour les fournisseurs autres qu’OpenAI. Si le problème persiste dans v3.x+, veuillez le signaler.
• json_schema ne fonctionne pas avec Gemini — Résolu dans v1.x ; response_format est désormais converti en responseMimeType + responseSchema pour Gemini. Si le problème persiste dans v3.x+, veuillez le signaler.

---

Paramètres de résilience

La limitation automatique du débit ne se déclenche pas

• La limitation automatique du débit s’applique uniquement aux fournisseurs utilisant une clé API (et non OAuth/abonnement)
• Vérifiez que la limitation automatique du débit est activée dans Paramètres → Résilience → Profils de fournisseurs
• Vérifiez si le fournisseur renvoie des codes d’état 429 ou des en-têtes Retry-After

Réglage du backoff exponentiel

Les profils de fournisseurs prennent en charge les paramètres suivants :

• Délai de base — Temps d’attente initial après le premier échec (valeur par défaut : 1s)
• Délai maximal — Limite maximale du temps d’attente (valeur par défaut : 30s)
• Multiplicateur — Facteur d’augmentation du délai à chaque échec consécutif (valeur par défaut : 2x)

Prévention de l’effet de troupeau

Lorsque de nombreuses requêtes simultanées atteignent un fournisseur soumis à une limitation de débit, OmniRoute utilise un mutex et la limitation automatique du débit pour sérialiser les requêtes et éviter les défaillances en cascade. Ce mécanisme est automatique pour les fournisseurs utilisant une clé API.

Les requêtes de chat échouent avec 503 / chat_admission_busy

Symptômes :

• Le point de terminaison des complétions de chat renvoie une réponse 503 pouvant être réessayée, dont le code d’erreur est chat_admission_busy.
• La réponse inclut Retry-After. Depuis la #12135, la valeur est calculée à partir de l’occupation observée — la plus grande valeur entre la fenêtre OMNIROUTE_CHAT_ADMISSION_QUEUE_MS pendant laquelle la requête a déjà attendu et la durée de détention des baux lourds actuels — arrondie à la seconde entière supérieure et plafonnée à 60. Lorsque le mécanisme d’admission est inactif, les valeurs minimales historiques sont conservées : 2 secondes pour le chemin basé sur les octets, 1 seconde pour le chemin basé sur la structure (qui inclut également reason: "structure_limit").
• Cela peut se produire lorsqu’un autre chat lourd ou une réponse en streaming de longue durée est encore en cours.

Le corps de la réponse basée sur les octets est :

{
  "error": {
    "message": "Chat admission capacity is temporarily unavailable. Retry shortly.",
    "type": "server_error",
    "code": "chat_admission_busy"
  }
}

La réponse basée sur la structure utilise le même type et le même code, avec le message Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. et reason: "structure_limit". Avec les seuils par défaut, une requête est considérée comme structurellement lourde lorsqu’elle contient au moins 200 messages, au moins 64 outils ou au moins 32,000 jetons estimés, ou lorsque l’estimation bornée de la structure épuise ses limites de 10,000 nœuds visités ou d’une profondeur de 12.

Cause : Il s’agit d’un délestage de charge délibéré au sein d’OmniRoute, et non d’une défaillance du fournisseur en amont. Chaque processus utilise une protection locale au processus pour réserver une capacité lourde limitée avant de conserver et d’analyser le corps d’une requête volumineuse. Un bail lourd reste détenu pendant toute la durée de vie d’une réponse SSE.

Propagation des #503 : avant ce correctif, la protection limitait la simultanéité à un NOMBRE fixe de requêtes (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, valeur par défaut : 1), indépendamment de la mémoire de l’hôte. Par conséquent, la distribution des agents de programmation (plusieurs sous-agents/CLI, avec des corps dépassant régulièrement 256 Ko) s’effondrait jusqu’à une simultanéité effective d’environ 1 et produisait des erreurs 503 sous une charge parfaitement normale. La protection s’ajuste désormais automatiquement : elle est contrôlée par un budget d’ingestion en OCTETS calculé automatiquement (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) et dimensionné à partir de la limite de mémoire réelle du processus. Elle consulte également un signal en temps réel de pression sur les ressources, afin de ne délester que lorsque l’hôte subit réellement une pression mémoire, et non simplement parce que plusieurs requêtes lourdes sont arrivées simultanément. L’ancienne limite basée sur le nombre (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT) est toujours respectée, mais uniquement si vous la définissez explicitement.

Lorsque la capacité est occupée, une requête lourde attend d’abord jusqu’à OMNIROUTE_CHAT_ADMISSION_QUEUE_MS (valeur par défaut : 2000, 0 désactive l’attente) qu’une place se libère avant de renvoyer la réponse 503 pouvant être réessayée. Cette attente bornée permet aux clients de type agent (OpenCode, Claude Code, Cursor), qui distribuent simultanément de lourdes sous-requêtes, de sérialiser la rafale au lieu d’épuiser tout leur budget de nouvelles tentatives sur des rejets immédiats et d’échouer en cours de tâche. L’occupation actuelle des baux lourds, le budget d’octets calculé et la gravité de la pression en temps réel sont exposés dans GET /api/monitoring/health → chatAdmission (inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled) — vérifiez ces valeurs avant de modifier une variable d’environnement. Paramètres → Résilience → File d’attente des requêtes → Requêtes simultanées ne contrôle pas ce mécanisme ; ce paramètre régit un mécanisme distinct de file d’attente des requêtes du fournisseur.

Correctif :

1. Commencez par réessayer. Les clients doivent respecter Retry-After et utiliser un backoff plutôt que de répéter immédiatement la requête.
2. Vérifiez /api/monitoring/health → chatAdmission avant d’ajuster quoi que ce soit. countCapEnabled: false et une valeur généreuse de maxInflightBytes signifient que le budget calculé automatiquement remplit déjà son rôle ; une valeur pressureSeverity de high/critical signifie que l’hôte manque réellement de mémoire — ce problème ne peut pas être résolu par une variable d’environnement d’admission : il nécessite davantage de RAM ou une charge de travail plus faible.
3. Uniquement si /api/monitoring/health indique que le budget calculé automatiquement est réellement trop faible pour votre hôte (ce qui est rare — il s’adapte déjà des conteneurs aux serveurs physiques), remplacez-le directement avec OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES plutôt que de revenir à l’ancienne limite basée sur le nombre de requêtes.

Consultez la référence des variables d’environnement pour connaître les paramètres d’admission faisant autorité.

---

Taxonomie facultative des défaillances RAG / LLM (16 problèmes)

Certains utilisateurs d’OmniRoute placent la passerelle devant des piles RAG ou d’agents. Dans ces configurations, il est courant d’observer un comportement étrange : OmniRoute semble fonctionner correctement (fournisseurs disponibles, profils de routage corrects, aucune alerte de limitation de débit), mais la réponse finale reste erronée.

En pratique, ces incidents proviennent généralement du pipeline RAG en aval, et non de la passerelle elle-même.

Si vous souhaitez disposer d’un vocabulaire commun pour décrire ces défaillances, vous pouvez utiliser WFGY ProblemMap, une ressource textuelle externe sous licence MIT qui définit seize schémas récurrents de défaillance RAG / LLM. De manière générale, elle couvre :

• la dérive de la récupération et les limites de contexte rompues
• les index et magasins vectoriels vides ou obsolètes
• l’inadéquation entre embeddings et sémantique
• les problèmes d’assemblage des prompts et de fenêtre de contexte
• l’effondrement logique et les réponses excessivement affirmatives
• les défaillances des longues chaînes et de la coordination des agents
• la dérive de la mémoire et des rôles dans les systèmes multi-agents
• les problèmes d’ordre de déploiement et d’amorçage

Le principe est simple :

1. Lorsque vous examinez une mauvaise réponse, consignez :
   • la tâche et la requête de l’utilisateur
   • la combinaison de routes ou de fournisseurs dans OmniRoute
   • tout contexte RAG utilisé en aval (documents récupérés, appels d’outils, etc.)
2. Associez l’incident à un ou deux numéros de WFGY ProblemMap (No.1 … No.16).
3. Enregistrez le numéro dans votre propre tableau de bord, guide opérationnel ou outil de suivi des incidents, à côté des journaux OmniRoute.
4. Utilisez la page WFGY correspondante pour déterminer si vous devez modifier votre pile RAG, votre système de récupération ou votre stratégie de routage.

Le texte intégral et des procédures concrètes sont disponibles ici (licence MIT, texte uniquement) :

README de WFGY ProblemMap

Vous pouvez ignorer cette section si vous n’exécutez pas de pipelines RAG ou d’agents derrière OmniRoute.

---

Problèmes connus de v3.8.0

Problèmes propres à la version v3.8.0 et solutions de contournement actuellement disponibles. Si un correctif est intégré dans un patch ultérieur, l’entrée sera mise à jour ou supprimée.

Échecs d’authentification de la CLI Devin

Symptômes :

• « CLI Devin introuvable » ou « échec de l’authentification » lors de l’appel d’outils reposant sur Devin
• La vérification d’exécution de la CLI indique installed=false

Causes :

• CLI_DEVIN_BIN pointe vers un chemin qui n’existe pas
• La CLI Devin n’est pas installée sur l’hôte

Correctif :

1. Installez la CLI Devin pour votre plateforme
2. Définissez CLI_DEVIN_BIN=/usr/local/bin/devin (ou le chemin réel) dans .env
3. Redémarrez OmniRoute et effectuez un nouveau test depuis Tableau de bord → Outils CLI

Modèle bloqué en période de refroidissement (réinitialisation manuelle)

Symptômes :

• Un modèle reste indiqué comme étant en période de refroidissement même après l’expiration du délai
• Les requêtes continuent d’ignorer le modèle dans le routage combiné alors que l’horodatage est dépassé

Réinitialisation manuelle :

• Tableau de bord : Paramètres → Périodes de refroidissement des modèles → cliquez sur Réactiver sur la carte concernée
• API : DELETE /api/resilience/model-cooldowns avec les en-têtes d’authentification de gestion

Échec de la connexion au fournisseur Command Code avec une erreur 403

Symptômes :

• Erreur 403 lors du test de la connexion au fournisseur Command Code
• La carte du fournisseur indique « non autorisé » après un nouvel ajout

Cause : Le flux OAuth ne s’est pas terminé (rappel non reçu ou jeton non conservé).

Correctif :

• Exécutez omniroute providers depuis la CLI pour relancer le flux OAuth, ou
• Relancez OAuth depuis Tableau de bord → Fournisseurs → Command Code → Reconnecter

ModelScope renvoie des périodes de refroidissement 429 agressives

Symptômes :

• Périodes de refroidissement très courtes ou immédiates sur ModelScope après une petite rafale de requêtes
• Le routage combiné ignore ModelScope plus tôt que prévu

Cause : ModelScope émet des en-têtes Retry-After propres au fournisseur. v3.8.0 inclut une gestion spécifique de ces en-têtes, tandis que les versions antérieures les interprètent incorrectement comme des indications génériques de limitation de débit.

Correctif :

• Vérifiez que vous utilisez v3.8.0 ou une version ultérieure
• Vérifiez que l’option useUpstream429BreakerHints est activée sous Paramètres → Résilience

OMNIROUTE_WS_BRIDGE_SECRET absent en production

Symptômes :

• Erreur 401 pour chaque requête adressée au pont WebSocket Codex/Responses lors de l’exécution sur un hôte de production distant
• La négociation du pont WebSocket se ferme immédiatement après la connexion

Cause : La variable d’environnement OMNIROUTE_WS_BRIDGE_SECRET est absente de l’environnement de production.

Correctif :

1. Générez un secret aléatoire : openssl rand -hex 32
2. Définissez OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> dans l’environnement du serveur de production (ainsi que dans tout client communiquant avec le pont)
3. Redémarrez OmniRoute

API Responses : mode d’arrière-plan dégradé en mode synchrone

Symptômes :

• Avertissement consigné : background mode degraded to synchronous
• Une requête background: true renvoie une réponse synchrone normale au lieu d’un descripteur de tâche en arrière-plan

Cause : v3.8.0 dégrade intentionnellement background: true sur l’API Responses en une exécution synchrone tout en émettant un avertissement. L’exécution asynchrone complète en arrière-plan sera livrée ultérieurement.

Correctif :

• Modifiez le client afin qu’il effectue l’appel sans background, ou
• Attendez une version ultérieure proposant un mode d’arrière-plan entièrement asynchrone (consultez le journal des modifications)

---

Démarrage lent / Délai d’expiration de la vérification de disponibilité

Si la CLI affiche ⚠ Server did not respond within 60s alors que le serveur fonctionne correctement, le délai alloué à la vérification de disponibilité est trop court pour votre environnement.

Cela se produit couramment sous Windows (antivirus, observateurs du système de fichiers) ou dans les conteneurs soumis à de lourdes charges de travail au démarrage.

Solution — augmentez le délai alloué :

# Via une variable d’environnement (persiste entre les démarrages) :
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3 minutes
omniroute serve

# Via une option de la CLI (usage ponctuel) :
omniroute serve --ready-timeout 180000

La valeur par défaut est de 60 000 ms (60 s). L’avertissement est uniquement informatif ; le serveur continue de démarrer en arrière-plan et sera accessible une fois le démarrage terminé.

Consultez docs/reference/ENVIRONMENT.md pour obtenir tous les détails sur OMNIROUTE_READY_TIMEOUT_MS.

---

Toujours bloqué ?

• Tickets GitHub : github.com/diegosouzapw/OmniRoute/issues
• Architecture : consultez docs/architecture/ARCHITECTURE.md pour plus de détails sur le fonctionnement interne
• Référence de l’API : consultez docs/reference/API_REFERENCE.md pour connaître tous les points de terminaison
• Tableau de bord d’état : consultez Tableau de bord → État pour connaître l’état du système en temps réel
• Traducteur : utilisez Tableau de bord → Traducteur pour déboguer les problèmes de format

---

Code source d’OmniRoute (a58000c7685f)