OmniRoute/docs/i18n/fr/docs/guides/USER_GUIDE.md

User Guide (Français)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Langues : 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Guide complet pour configurer les fournisseurs, créer des combinaisons, intégrer des outils CLI et déployer OmniRoute.

---

Table des matières

• Aperçu des tarifs
• Cas d’utilisation
• Configuration des fournisseurs
• Intégration CLI
• Déploiement
• Modèles disponibles
• Fonctionnalités avancées
• Routage automatique (sans configuration)
• Intégration MCP et A2A
• Système de compétences
• Système de mémoire
• Webhooks
• Agents cloud
• Gestion programmatique
• CLI interne
• Application de bureau (Electron)

---

💰 Aperçu des tarifs

Offre	Fournisseur	Coût	Réinitialisation du quota	Idéal pour
💳 ABONNEMENT	Claude Code (Pro)	$20/mo	5 h + hebdomadaire	Utilisateurs déjà abonnés
	Codex (Plus/Pro)	$20-200/mo	5 h + hebdomadaire	Utilisateurs d’OpenAI
	GitHub Copilot	$10-19/mo	Mensuelle	Utilisateurs de GitHub
🔑 CLÉ API	DeepSeek	Paiement à l’usage	Aucune	Raisonnement à faible coût
	Groq	Paiement à l’usage	Aucune	Inférence ultrarapide
	xAI (Grok)	Paiement à l’usage	Aucune	Raisonnement avec Grok 4
	Mistral	Paiement à l’usage	Aucune	Modèles hébergés dans l’UE
	Perplexity	Paiement à l’usage	Aucune	Recherche augmentée
	Together AI	Paiement à l’usage	Aucune	Modèles open source
	Fireworks AI	Paiement à l’usage	Aucune	Images FLUX rapides
	Cerebras	Paiement à l’usage	Aucune	Vitesse à l’échelle d’une tranche
	Cohere	Paiement à l’usage	Aucune	RAG avec Command R+
	NVIDIA NIM	Paiement à l’usage	Aucune	Modèles d’entreprise
	Baidu Qianfan	Paiement à l’usage	Aucune	Modèles ERNIE
💰 ÉCONOMIQUE	GLM-4.7	$0.6/1M	Chaque jour à 10 h	Solution de secours économique
	MiniMax M2.1	$0.2/1M	Fenêtre glissante de 5 h	Option la moins chère
	Kimi K2	$9/mo forfaitaires	10M tokens/mo	Coût prévisible
🆓 GRATUIT	Qoder	$0	Limites du fournisseur	Vérifier le catalogue actuel
	Kiro	$0	~50 crédits/mo	Claude gratuitement

---

🎯 Cas d’utilisation

Cas 1 : « J’ai un abonnement Claude Pro »

Problème : le quota expire sans être utilisé et les limites de débit sont atteintes lors des sessions de programmation intensives

Combinaison : "maximize-claude"
  1. cc/claude-opus-4-7        (utiliser pleinement l’abonnement)
  2. glm/glm-4.7               (solution de secours économique lorsque le quota est épuisé)
  3. if/qwen3.8-max-preview       (solution de secours gratuite en cas d’urgence)

Coût mensuel : $20 (abonnement) + ~$5 (solution de secours) = $25 au total
contre $20 + l’atteinte des limites = frustration

Cas 2 : « Je ne veux rien payer »

Problème : impossible de financer des abonnements, besoin d’une IA fiable pour la programmation

Combinaison : "zero-cost"
  1. if/kimi-k2.7-code          (accès gratuit indiqué ; des limites de débit peuvent s’appliquer)
  2. kr/qwen3-coder-next        (solution de secours gratuite avec Kiro)

Coût mensuel : $0
Qualité : vérifiez le modèle, les limites, la confidentialité et le SLA pour votre charge de travail

Cas 3 : « J’ai besoin de programmer 24 h/24 et 7 j/7, sans interruption »

Problème : délais serrés, aucune interruption de service envisageable

Combinaison : "always-on"
  1. cc/claude-opus-4-7        (meilleure qualité)
  2. cx/gpt-5.5                (deuxième abonnement)
  3. glm/glm-4.7               (économique, réinitialisation quotidienne)
  4. minimax/MiniMax-M2.1      (le moins cher, réinitialisation après 5 h)
  5. if/deepseek-v4-flash       (accès gratuit indiqué ; des limites de débit peuvent s’appliquer)

Résultat : 5 niveaux de secours renforcent la résilience ; la disponibilité des services en amont n’est pas garantie
Coût mensuel : $20-200 (abonnements) + $10-20 (solution de secours)

Cas 4 : « Je veux une IA GRATUITE dans OpenClaw »

Problème : besoin d’un assistant IA dans les applications de messagerie, entièrement gratuit

Combinaison : "openclaw-free"
  1. if/qwen3.8-max-preview     (accès gratuit indiqué ; des limites de débit peuvent s’appliquer)
  2. if/deepseek-v4-flash       (accès gratuit indiqué ; des limites de débit peuvent s’appliquer)
  3. if/kimi-k2.7-code          (accès gratuit indiqué ; des limites de débit peuvent s’appliquer)

Coût mensuel : $0
Accès via : WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 Configuration des fournisseurs

Pour ajouter en masse des connexions par clé API depuis un fichier CSV ou JSON, utilisez Tableau de bord → Fournisseurs → Importer depuis un fichier. Les colonnes sont positionnelles (provider,name,apiKey,baseUrl,priority) ; provider doit déjà exister en tant que fournisseur géré ou nœud compatible. Consultez Importer des fournisseurs depuis un fichier CSV ou JSON.

🔐 Fournisseurs avec abonnement

Claude Code (Pro/Max)

Tableau de bord → Fournisseurs → Connecter Claude Code
→ Connexion OAuth → Actualisation automatique du jeton
→ Suivi des quotas sur 5 heures et hebdomadaire

Modèles :
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Conseil : utilisez Opus pour les tâches complexes et Sonnet pour la rapidité. OmniRoute suit le quota pour chaque modèle !

Les routes compatibles avec Claude et Claude Code conservent l’effort de réflexion max pour les modèles Opus et Sonnet. Les modèles Haiku n’acceptent pas le niveau d’effort max ; OmniRoute réduit donc cette requête à un budget de réflexion élevé avant de l’envoyer au fournisseur en amont.

OpenAI Codex (Plus/Pro)

Tableau de bord → Fournisseurs → Connecter Codex
→ Connexion OAuth (port 1455)
→ Réinitialisation toutes les 5 heures et chaque semaine

Modèles :
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

Tableau de bord → Fournisseurs → Connecter GitHub
→ OAuth via GitHub
→ Réinitialisation mensuelle (le 1er du mois)

Modèles :
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview

💰 Fournisseurs économiques

GLM-4.7 (Réinitialisation quotidienne, 0,6 $/1M)

1. Inscrivez-vous : Zhipu AI
2. Obtenez une clé API depuis Coding Plan
3. Tableau de bord → Ajouter une clé API : Fournisseur : glm, Clé API : your-key

Utilisation : glm/glm-4.7 — Conseil : Coding Plan offre un quota 3 fois supérieur pour un coût divisé par 7 ! Réinitialisation quotidienne à 10 h 00.

MiniMax M2.1 (Réinitialisation toutes les 5 h, 0,20 $/1M)

1. Inscrivez-vous : MiniMax
2. Obtenez une clé API → Tableau de bord → Ajouter une clé API

Utilisation : minimax/MiniMax-M2.1 — Conseil : l’option la moins chère pour les contextes longs (1M de jetons) !

Kimi K2 (Forfait de 9 $/mois)

1. Abonnez-vous : Moonshot AI
2. Obtenez une clé API → Tableau de bord → Ajouter une clé API

Utilisation : kimi/kimi-k2.5 — Conseil : forfait fixe de 9 $/mois pour 10M de jetons, soit un coût effectif de 0,90 $/1M !

Baidu Qianfan / ERNIE

1. Inscrivez-vous : Baidu AI Cloud Qianfan
2. Créez une clé API Qianfan → Tableau de bord → Ajouter une clé API : Fournisseur : qianfan

Utilisation : qianfan/ernie-5.1, qianfan/ernie-x1.1 ou un autre identifiant de modèle Qianfan compatible avec OpenAI.

🆓 Fournisseurs GRATUITS

Les fournisseurs gratuits sans authentification disposent d’un bouton à côté de Aucune authentification requise sur leur page. Sa désactivation désactive le fournisseur, le retire des vues configurée/compacte des fournisseurs et retire ses modèles de /v1/models.

Qoder (9 modèles GRATUITS)

Tableau de bord → Connecter Qoder → Connexion OAuth → L’accès est soumis aux limites actuelles du fournisseur

Modèles : if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

Kiro (Claude GRATUIT)

Tableau de bord → Connecter Kiro → AWS Builder ID ou Google/GitHub → Environ 50 crédits/mois

Modèles : kr/claude-sonnet-4.5, kr/claude-haiku-4.5

---

🎨 Combos

Vous pouvez réorganiser les cartes de combos directement dans Tableau de bord → Combos en faisant glisser la poignée de chaque carte. L’ordre est enregistré dans SQLite et restauré lors du rechargement.

Exemple 1 : Maximiser l’abonnement → Solution de secours économique

Tableau de bord → Combos → Créer

Nom : premium-coding
Modèles :
  1. cc/claude-opus-4-7 (Abonnement principal)
  2. glm/glm-4.7 (Solution de secours économique, 0,6 $/1M)
  3. minimax/MiniMax-M2.7 (Solution de repli la moins chère, 0,3 $/1M)

Utilisation dans la CLI : premium-coding

Exemple 2 : Modèles gratuits uniquement (coût nul)

Nom : free-combo
Modèles :
  1. if/kimi-k2.7-code (accès gratuit indiqué ; des limites du fournisseur peuvent s’appliquer)
  2. kr/qwen3-coder-next (solution de repli gratuite de Kiro)

Coût : actuellement indiqué à 0 $ ; les conditions et la disponibilité peuvent changer

---

🔧 Intégration à la CLI

Cursor IDE

Utiliser Cursor comme client OmniRoute (acheminer les conversations Cursor via OmniRoute) :

Paramètres → Modèles → Avancé :
  URL de base de l’API OpenAI : http://localhost:20128/v1
  Clé API OpenAI : [depuis le tableau de bord OmniRoute]
  Modèle : cc/claude-opus-4-7

Utiliser OmniRoute comme fournisseur Cursor (OmniRoute appelle Cursor en amont) : privilégiez Tableau de bord → Fournisseurs → Cursor → Se connecter avec Cursor. Dans Docker, consultez docs/providers/CURSOR-DOCKER.md.

Claude Code

Modifiez ~/.claude/settings.json :

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}

Utilisez ici le point de terminaison racine compatible avec Claude. N’ajoutez pas /v1 à ANTHROPIC_BASE_URL.

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"

OpenClaw

Modifiez ~/.openclaw/openclaw.json :

{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}

Ou utilisez le tableau de bord : Outils CLI → OpenClaw → Configuration automatique

Cline / Continue / RooCode

Fournisseur : compatible avec OpenAI
URL de base : http://localhost:20128/v1
Clé API : [depuis le tableau de bord]
Modèle : cc/claude-opus-4-7

---

🚀 Déploiement

Installation globale avec npm (recommandée)

npm install -g omniroute

# Créer le répertoire de configuration
mkdir -p ~/.omniroute

# Créer le fichier .env (voir .env.example)
cp .env.example ~/.omniroute/.env

# Démarrer le serveur
omniroute
# Ou avec un port personnalisé :
omniroute --port 3000

La CLI charge automatiquement .env depuis ~/.omniroute/.env ou ./.env.

Mode barre d’état système

Démarrez OmniRoute dans la barre d’état système :

omniroute serve --tray

La commande se termine une fois que le serveur et l’icône de la barre d’état système sont prêts.

Le serveur continue de fonctionner sans le terminal.

Le mode barre d’état système prend en charge macOS, Windows et les sessions Linux graphiques. Il n’ouvre pas automatiquement le tableau de bord.

Utilisez le menu de la barre d’état système pour effectuer les actions suivantes :

• Ouvrir le tableau de bord.
• Ouvrir /dashboard/logs.
• Modifier le démarrage automatique.
• Arrêter OmniRoute.

Ne combinez pas --tray avec les options suivantes :

• --daemon
• --log
• --no-recovery

Ces modes nécessitent une gestion différente des processus.

Activez le démarrage lors de la prochaine connexion à la machine :

omniroute autostart enable

Le démarrage automatique utilise le mode barre d’état système sur macOS, Windows et les sessions Linux graphiques. Sous Linux sans interface graphique, il utilise le service utilisateur systemd existant.

Désactivez le démarrage à la connexion :

omniroute autostart disable

Désinstallation

Lorsque vous n’avez plus besoin d’OmniRoute, nous proposons deux scripts rapides pour une suppression propre :

Commande	Action
npm run uninstall	Supprime l’application du système, mais conserve votre base de données et vos configurations dans ~/.omniroute.
npm run uninstall:full	Supprime l’application ET efface définitivement toutes les configurations, clés et bases de données.

Remarque : pour exécuter ces commandes, accédez au dossier du projet OmniRoute (si vous l’avez cloné), puis lancez-les. Si OmniRoute est installé globalement, vous pouvez également exécuter simplement npm uninstall -g omniroute.

Déploiement sur un VPS

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# Ou : pm2 start npm --name omniroute -- start

Déploiement avec PM2 (faible consommation de mémoire)

Pour les serveurs disposant de peu de RAM, utilisez l’option de limitation de la mémoire :

# Avec une limite de 512 Mo (valeur par défaut)
pm2 start npm --name omniroute -- start

# Ou avec une limite de mémoire personnalisée
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Ou en utilisant ecosystem.config.js
pm2 start ecosystem.config.js

Créez ecosystem.config.js :

module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};

Docker

# Construire l’image (valeur par défaut = runner-cli avec codex/claude/droid préinstallés)
docker build -t omniroute:cli .

# Mode portable (recommandé)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

Pour le mode intégré à l’hôte avec les exécutables CLI, consultez la section Docker de la documentation principale.

Void Linux (xbps-src)

Les utilisateurs de Void Linux peuvent empaqueter et installer OmniRoute nativement à l’aide du framework de compilation croisée xbps-src. Celui-ci automatise la construction de la version autonome de Node.js ainsi que celle des liaisons natives better-sqlite3 requises.

Afficher le modèle xbps-src

# Fichier de modèle pour « omniroute »
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# Déterminer l’architecture du processeur cible pour node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) Installer toutes les dépendances – ignorer les scripts
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Construire le paquet autonome Next.js
	npm run build

	# 3) Copier les ressources statiques dans le paquet autonome
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Compiler la liaison native better-sqlite3
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) Placer la liaison compilée dans le paquet autonome
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) Supprimer les paquets sharp propres à chaque architecture
	rm -rf .next/standalone/node_modules/@img

	# 7) Copier les dépendances d’exécution de pino omises par l’analyse statique de Next.js :
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# Empêcher la suppression des répertoires vides du routeur d’application Next.js par le hook de post-installation
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

Variables d’environnement

Variable	Valeur par défaut	Description
JWT_SECRET	omniroute-default-secret-change-me	Secret de signature JWT (à modifier en production)
INITIAL_PASSWORD	CHANGEME	Mot de passe de la première connexion
DATA_DIR	~/.omniroute	Répertoire des données (base de données, utilisation, journaux)
PORT	valeur par défaut du framework	Port du service (20128 dans les exemples)
HOSTNAME	valeur par défaut du framework	Hôte d'écoute (Docker utilise 0.0.0.0 par défaut)
NODE_ENV	valeur par défaut de l'environnement	Définissez production pour le déploiement
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL de base publique affichée dans le tableau de bord et accessible au serveur (remplace l'ancienne variable BASE_URL)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	URL de base du point de terminaison de synchronisation cloud (remplace l'ancienne variable CLOUD_URL)
API_KEY_SECRET	endpoint-proxy-api-key-secret	Secret HMAC pour les clés API générées
REQUIRE_API_KEY	false	Imposer une clé API Bearer sur /v1/*
ALLOW_API_KEY_REVEAL	false	Autoriser les utilisateurs authentifiés du tableau de bord à afficher à la demande les valeurs complètes des clés API enregistrées
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	Fréquence d'actualisation côté serveur des données mises en cache de Provider Limits ; les boutons de l'interface déclenchent toujours une synchronisation manuelle
DISABLE_SQLITE_AUTO_BACKUP	false	Désactiver les instantanés SQLite automatiques avant les écritures, importations et restaurations ; les sauvegardes manuelles restent disponibles
APP_LOG_TO_FILE	true	Active l'enregistrement sur disque des journaux d'application et d'audit
AUTH_COOKIE_SECURE	false	Forcer l'attribut Secure du cookie d'authentification (derrière un proxy inverse HTTPS)
CLOUDFLARED_BIN	non défini	Utiliser un binaire cloudflared existant au lieu du téléchargement géré
CLOUDFLARED_PROTOCOL	http2	Transport pour les Quick Tunnels gérés (http2, quic ou auto)
OMNIROUTE_MEMORY_MB	512	Limite du tas Node.js en Mo
PROMPT_CACHE_MAX_SIZE	50	Nombre maximal d'entrées dans le cache des prompts
SEMANTIC_CACHE_MAX_SIZE	100	Nombre maximal d'entrées dans le cache sémantique

Pour obtenir la liste complète des variables d'environnement, consultez le README.

---

📊 Modèles disponibles

Afficher tous les modèles disponibles

La liste ci-dessous est issue de open-sse/config/providerRegistry.ts pour la v3.8.0. Les catalogues cloud (Gemini, OpenRouter, etc.) sont synchronisés dynamiquement — pour consulter le catalogue complet en temps réel, ouvrez Tableau de bord → Fournisseurs → [fournisseur] → Modèles disponibles ou appelez GET /api/models/catalog.

Si la liste intégrée d’un fournisseur n’est plus à jour, utilisez Importer depuis /models sur cette page (ou activez la Synchronisation automatique) afin de récupérer le catalogue amont en temps réel. Cela a été vérifié dans la v3.8.50 pour LLM7.io (gemini-3.1-flash-lite) et UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ) ; l’accès anonyme à Pollinations est resté limité en amont lors de la même série de tests.

Claude Code (cc/) — OAuth Pro/Max : cc/claude-opus-4-8, cc/claude-opus-4-7, cc/claude-opus-4-6, cc/claude-opus-4-5-20251101, cc/claude-sonnet-4-6, cc/claude-sonnet-4-5-20250929, cc/claude-haiku-4-5-20251001

Codex (cx/) — OAuth Plus/Pro : cx/gpt-5.5 (+ niveaux d’effort : gpt-5.5-xhigh, gpt-5.5-high, gpt-5.5-medium, gpt-5.5-low), cx/gpt-5.4, cx/gpt-5.4-mini, cx/gpt-5.3-codex, cx/gpt-5.3-codex-spark

GitHub Copilot (gh/) — OAuth : gh/gpt-5.5, gh/gpt-5.4, gh/gpt-5.4-mini, gh/gpt-5-mini, gh/gpt-5.3-codex, gh/claude-opus-4.7, gh/claude-opus-4.6, gh/claude-opus-4-5-20251101, gh/claude-sonnet-4.6, gh/claude-sonnet-4.5, gh/claude-haiku-4.5, gh/gemini-3.1-pro-preview, gh/gemini-3-flash-preview, gh/oswe-vscode-prime

Kiro (kr/) — OAuth GRATUIT : utilisez le catalogue en temps réel affiché sous Tableau de bord → Fournisseurs → Kiro → Modèles disponibles. La disponibilité dépend du compte et de l’offre.

Qoder (if/) — OAuth GRATUIT : if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

GLM (glm/, glm-cn/, zai/, glmt/) — 0,2–0,6 $/1M : glm/glm-5.1, glm/glm-5, glm/glm-5-turbo, glm/glm-4.7, glm/glm-4.7-flash, glm/glm-4.6, glm/glm-4.6v, glm/glm-4.5, glm/glm-4.5v, glm/glm-4.5-air

MiniMax (minimax/, minimax-cn/) — 0,2 $/1M : minimax/MiniMax-M2.7, minimax/MiniMax-M2.7-highspeed, minimax/MiniMax-M2.5, minimax/MiniMax-M2.5-highspeed

Kimi (kimi/, kimi-coding/, kimi-coding-apikey/) — forfait de 9 $/mois ou paiement à l’usage : kimi/kimi-k2.6, kimi/kimi-k2.5

DeepSeek (ds/) — Clé API : ds/deepseek-v4-pro, ds/deepseek-v4-flash

Groq (groq/) — Ultra-rapide : groq/llama-3.3-70b-versatile, groq/meta-llama/llama-4-maverick-17b-128e-instruct, groq/qwen/qwen3-32b, groq/openai/gpt-oss-120b

xAI (xai/) — Grok natif : xai/grok-4.3, xai/grok-4.20-multi-agent-0309, xai/grok-4.20-0309-reasoning, xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — Hébergé dans l’UE : mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Enrichi par la recherche : pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — Open source : together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (gratuit), together/meta-llama/Llama-Vision-Free, together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free, together/deepseek-ai/DeepSeek-R1, together/Qwen/Qwen3-235B-A22B, together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

Fireworks AI (fireworks/) — Inférence rapide : fireworks/accounts/fireworks/models/kimi-k2p6, fireworks/accounts/fireworks/models/minimax-m2p7, fireworks/accounts/fireworks/models/qwen3p6-plus, fireworks/accounts/fireworks/models/glm-5p1, fireworks/accounts/fireworks/models/deepseek-v4-pro

Cerebras (cerebras/) — À l’échelle d’une tranche de silicium : cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — Axé sur la RAG : cohere/command-a-reasoning-08-2025, cohere/command-a-vision-07-2025, cohere/command-a-03-2025, cohere/command-r-08-2024

NVIDIA NIM (nvidia/) — Entreprise : nvidia/z-ai/glm-5.1, nvidia/minimaxai/minimax-m2.7, nvidia/google/gemma-4-31b-it, nvidia/mistralai/mistral-small-4-119b-2603, nvidia/mistralai/mistral-large-3-675b-instruct-2512, nvidia/qwen/qwen3.5-397b-a17b, nvidia/deepseek-ai/deepseek-v4-pro, nvidia/openai/gpt-oss-120b, nvidia/nvidia/nemotron-3-super-120b-a12b

Baidu Qianfan (qianfan/) — ERNIE : qianfan/ernie-5.1, qianfan/ernie-5.0-thinking-latest, qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/) : ollama-cloud/deepseek-v4-pro, ollama-cloud/deepseek-v4-flash, ollama-cloud/kimi-k2.6, ollama-cloud/glm-5.1, ollama-cloud/minimax-m2.7, ollama-cloud/gemma4:31b, ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/) : synchronisé en temps réel depuis Google pour chaque clé API — aucune liste statique. Connectez une clé dans Tableau de bord → Fournisseurs, puis utilisez Modèles disponibles pour importer le catalogue actuel (p. ex. gemini/gemini-3-pro, gemini/gemini-3-flash).

Autres fournisseurs compatibles (sélection) : cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (via aws-bedrock), azure-ai, openrouter (catalogue transmis tel quel), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Chacun conserve sa propre liste de modèles dans providerRegistry.ts et peut être synchronisé automatiquement lorsque le fournisseur expose un point de terminaison /models.

Remarque sur les ID de modèles : OmniRoute utilise les ID natifs des fournisseurs (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning). Certains ID comportent des versions avec des points, car c’est le format attendu par l’API en amont. Si un modèle ne figure pas dans la liste ci-dessus, exécutez omniroute models --search <term> ou appelez GET /api/models/catalog pour confirmer sa disponibilité.

---

🧩 Fonctionnalités avancées

Modèles personnalisés

Ajoutez n’importe quel ID de modèle à n’importe quel fournisseur sans attendre une mise à jour de l’application :

# Via l’API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# Lister : curl http://localhost:20128/api/provider-models?provider=openai
# Supprimer : curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

Vous pouvez également utiliser le tableau de bord : Fournisseurs → [Fournisseur] → Modèles personnalisés.

Remarques :

• OpenRouter et les fournisseurs compatibles avec OpenAI/Anthropic sont gérés uniquement depuis Modèles disponibles. L’ajout manuel, l’importation et la synchronisation automatique alimentent tous la même liste de modèles disponibles ; il n’existe donc pas de section Modèles personnalisés distincte pour ces fournisseurs.
• La section Modèles personnalisés est destinée aux fournisseurs qui ne proposent pas d’importations gérées de modèles disponibles.

Chaînage de pairs OmniRoute

Une autre passerelle OmniRoute peut être ajoutée en tant que fournisseur personnalisé compatible avec OpenAI. Utilisez l’URL de base /v1 du pair et une clé d’API dédiée avec le minimum de privilèges, émise par ce pair.

Pour les chaînes réciproques ou à plusieurs sauts, activez la protection facultative contre les boucles sur chaque passerelle :

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

Seules les requêtes envoyées à une URL de pair explicitement autorisée reçoivent l’en-tête X-OmniRoute-Peer-Trace. Une passerelle rejette un ID d’instance répété ou un nombre maximal de sauts atteint avec la réponse HTTP 508 Loop Detected ; les fournisseurs en amont ordinaires ne reçoivent aucune métadonnée de pair.

Le chaînage de pairs ne constitue ni une réplication de base de données ni un basculement d’hôte. Chaque passerelle conserve un état SQLite, des caches, des compteurs de débit et des sessions indépendants. Utilisez un proxy inverse avec vérification d’intégrité ou un mécanisme de basculement côté client pour une disponibilité active/passive ou active/active, et ne montez jamais une même base de données SQLite dans plusieurs instances OmniRoute en cours d’exécution.

Routes dédiées aux fournisseurs

Acheminez les requêtes directement vers un fournisseur spécifique avec validation du modèle :

POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations

Le préfixe du fournisseur est ajouté automatiquement s’il est absent. Les modèles qui ne correspondent pas renvoient 400.

Configuration du proxy réseau

# Définir le proxy global
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# Proxy par fournisseur
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# Tester le proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

Ordre de priorité : Spécifique à la clé → Spécifique à la combinaison → Spécifique au fournisseur → Global → Environnement.

API du catalogue de modèles

curl http://localhost:20128/api/models/catalog

Renvoie les modèles regroupés par fournisseur avec leurs types (chat, embedding, image).

Synchronisation dans le cloud

• Synchronisez les fournisseurs, les combinaisons et les paramètres entre les appareils
• Synchronisation automatique en arrière-plan avec délai d’expiration et échec rapide
• Privilégiez NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL côté serveur en production

Tunnel rapide Cloudflare

• Disponible dans Tableau de bord → Points de terminaison pour Docker et les autres déploiements auto-hébergés
• Crée une URL temporaire https://*.trycloudflare.com qui redirige vers votre point de terminaison /v1 actuel compatible avec OpenAI
• La première activation installe cloudflared uniquement si nécessaire ; les redémarrages ultérieurs réutilisent le même binaire géré
• Les tunnels rapides ne sont pas restaurés automatiquement après le redémarrage d’OmniRoute ou du conteneur ; réactivez-les depuis le tableau de bord si nécessaire
• Les URL de tunnel sont éphémères et changent chaque fois que vous arrêtez ou démarrez le tunnel
• Les tunnels rapides gérés utilisent par défaut le transport HTTP/2 afin d’éviter les avertissements bruyants liés au tampon UDP de QUIC dans les conteneurs aux ressources limitées
• Définissez CLOUDFLARED_PROTOCOL=quic ou auto si vous souhaitez remplacer le choix de transport géré
• Définissez CLOUDFLARED_BIN si vous préférez utiliser un binaire cloudflared préinstallé plutôt que le téléchargement géré
• Les panneaux Tunnel rapide Cloudflare, Tailscale Funnel et Tunnel ngrok peuvent être affichés ou masqués dans Paramètres → Apparence. Masquer un panneau n’arrête pas un tunnel en cours d’exécution.

Intelligence de la passerelle LLM (Phase 9)

• Cache sémantique — Met automatiquement en cache les réponses non diffusées avec temperature=0 (contournement avec X-OmniRoute-No-Cache: true)
• Idempotence des requêtes — Déduplique les requêtes dans un délai de 5 s via l’en-tête Idempotency-Key ou X-Request-Id
• Suivi de la progression — Événements SSE facultatifs event: progress via l’en-tête X-OmniRoute-Progress: true

---

Atelier de traduction

Accessible via Tableau de bord → Traducteur. Déboguez et visualisez la manière dont OmniRoute traduit les requêtes API entre les fournisseurs.

Mode	Objectif
Atelier	Sélectionnez les formats source/cible, collez une requête et affichez instantanément le résultat traduit
Testeur de chat	Envoyez des messages de chat en direct via le proxy et examinez l’intégralité du cycle de requête/réponse
Banc de test	Exécutez des tests par lots sur plusieurs combinaisons de formats afin de vérifier l’exactitude de la traduction
Moniteur en direct	Observez les traductions en temps réel à mesure que les requêtes transitent par le proxy

Cas d’utilisation :

• Déboguer la raison de l’échec d’une combinaison client/fournisseur spécifique
• Vérifier que les balises de raisonnement, les appels d’outils et les invites système sont correctement traduits
• Comparer les différences de format entre les formats OpenAI, Claude, Gemini et Responses API

---

Stratégies de routage

Configurez via Tableau de bord → Paramètres → Routage. Le tableau de bord présente les six stratégies les plus utilisées ; les combinaisons et le routeur automatique prennent en charge en interne un ensemble plus étendu.

Stratégies visibles dans le tableau de bord (routage au niveau du compte) :

Stratégie	Description
Remplissage prioritaire	Utilise les comptes par ordre de priorité — le compte principal traite toutes les requêtes jusqu’à ce qu’il soit indisponible
Tourniquet	Parcourt tous les comptes avec une limite d’affinité configurable (par défaut : 3 appels par compte)
P2C (choix entre deux)	Sélectionne 2 comptes aléatoires et achemine vers celui en meilleur état — équilibre la charge tout en tenant compte de leur état
Aléatoire	Sélectionne aléatoirement un compte pour chaque requête à l’aide du mélange de Fisher-Yates
Le moins utilisé	Achemine vers le compte dont l’horodatage lastUsedAt est le plus ancien, afin de répartir uniformément le trafic
Optimisé en fonction du coût	Achemine vers le compte ayant la valeur de priorité la plus faible, afin de privilégier les fournisseurs les moins coûteux

Stratégies avancées de combinaison et automatiques (configurables pour chaque combinaison ou via les préfixes auto/* — voir AUTO-COMBO.md) :

• priority — ordre strict, sans tourniquet
• weighted — répartition proportionnelle du trafic selon les pondérations propres à chaque modèle
• fill-first — utilise le premier modèle jusqu’à ce que ses limites soient atteintes
• round-robin / strict-random / random
• p2c (choix entre deux)
• least-used et cost-optimized
• auto — sélection fondée sur un score parmi tous les candidats
• lkgp (dernier fournisseur connu comme fonctionnel) — conserve le dernier fournisseur ayant réussi, puis se rabat sur les règles
• context-optimized — sélectionne le modèle disposant de la plus grande fenêtre de contexte libre
• context-relay — enchaîne des modèles à contexte long pour les échanges suivants

En-tête externe de session persistante

Pour une affinité de session externe (par exemple, des agents Claude Code/Codex derrière des proxys inverses), envoyez :

X-Session-Id: votre-clé-de-session

OmniRoute accepte également x_session_id et renvoie la clé de session effective dans X-OmniRoute-Session-Id.

Si vous utilisez Nginx et envoyez des en-têtes contenant des traits de soulignement, activez :

underscores_in_headers on;

Alias de modèles avec caractères génériques

Créez des motifs génériques pour remapper les noms de modèles :

Motif : claude-sonnet-*     →  Cible : cc/claude-sonnet-4-6
Motif : gpt-*               →  Cible : gh/gpt-5.3-codex

Les caractères génériques prennent en charge * (n’importe quels caractères) et ? (un seul caractère).

Chaînes de repli

Définissez des chaînes de repli globales qui s’appliquent à toutes les requêtes :

Chaîne : production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7

---

Résilience et disjoncteurs

Configurez via Tableau de bord → Paramètres → Résilience.

OmniRoute met en œuvre une résilience au niveau des fournisseurs reposant sur cinq composants :

1. File d’attente et cadencement des requêtes — Régulation des requêtes au niveau du système :

   • Requêtes par minute (RPM) — Nombre maximal de requêtes par minute et par compte
   • Délai minimal entre les requêtes — Intervalle minimal en millisecondes entre les requêtes
   • Nombre maximal de requêtes simultanées — Nombre maximal de requêtes simultanées par compte

2. Délai de récupération de la connexion — Configuration par type d’authentification pour une connexion unique après des échecs autorisant une nouvelle tentative :

   • Délai de récupération de base — Fenêtre de récupération par défaut après des échecs en amont autorisant une nouvelle tentative
   • Utiliser les indications de nouvelle tentative du service en amont — Respecte les indications faisant autorité de Retry-After ou de réinitialisation lorsqu’elles sont fournies
   • Nombre maximal d’étapes de temporisation — Niveau maximal de temporisation exponentielle en cas d’échecs répétés

3. Disjoncteur du fournisseur — Suit les échecs de bout en bout du fournisseur, marque un fournisseur comme dégradé au seuil d’avertissement configuré et ouvre le disjoncteur lorsque le seuil d’échec configuré est atteint :

   • Seuil de dégradation — Nombre d’échecs consécutifs du fournisseur avant le passage à l’état DEGRADED
   • Seuil d’échec — Nombre d’échecs consécutifs du fournisseur avant le passage à l’état OPEN
   • Délai de réinitialisation — Durée avant que le fournisseur soit à nouveau testé
   • CLOSED (Sain) — Les requêtes sont traitées normalement
   • DEGRADED — Les requêtes continuent d’être traitées tandis que le nombre élevé d’échecs est suivi
   • OPEN — Le fournisseur est temporairement bloqué après des échecs répétés
   • HALF_OPEN — Vérification de la récupération du fournisseur

   Les limitations de débit 429 propres à une connexion restent gérées par le délai de récupération de la connexion et ne sont pas comptabilisées par le disjoncteur du fournisseur.

   L’état d’exécution du disjoncteur du fournisseur est affiché uniquement dans Tableau de bord → État de santé.

4. Attente de la fin du délai de récupération — Si toutes les connexions candidates sont déjà en période de récupération, OmniRoute peut attendre la fin de la période la plus proche et relancer automatiquement la même requête cliente.

5. Détection automatique des limites de débit — Lorsque les fournisseurs en amont renvoient des fenêtres d’attente explicites, ces indications remplacent le délai local de récupération de la connexion si ce paramètre est activé.

Conseil de pro : Utilisez la page État de santé pour inspecter et réinitialiser les disjoncteurs actifs des fournisseurs après une panne. La page Résilience permet uniquement de modifier la configuration.

---

Exportation / importation de la base de données

Gérez les sauvegardes de la base de données dans Tableau de bord → Paramètres → Système et stockage.

Action	Description
Exporter la base de données	Télécharge la base de données SQLite actuelle sous forme de fichier .sqlite
Tout exporter (.tar.gz)	Télécharge une archive de sauvegarde complète comprenant : base de données, paramètres, combos, connexions aux fournisseurs (sans identifiants), métadonnées des clés API
Importer une base de données	Téléverse un fichier .sqlite pour remplacer la base de données actuelle. Une sauvegarde préalable à l’importation est automatiquement créée, sauf si DISABLE_SQLITE_AUTO_BACKUP=true

# API : exporter la base de données
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API : tout exporter (archive complète)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API : importer la base de données
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

Validation de l’importation : L’intégrité du fichier importé est vérifiée (contrôle pragma SQLite), ainsi que la présence des tables requises (provider_connections, provider_nodes, combos, api_keys) et sa taille (100 Mo maximum).

Cas d’utilisation :

• Migrer OmniRoute d’une machine à une autre
• Créer des sauvegardes externes pour la reprise après sinistre
• Partager des configurations entre les membres d’une équipe (tout exporter → partager l’archive)

---

Tableau de bord des paramètres

La page des paramètres est organisée en 7 onglets pour faciliter la navigation :

Onglet	Contenu
Général	Outils de stockage système, comportement par défaut, visibilité des tunnels d’endpoint
Apparence	Commandes du thème (clair/sombre/système), visibilité de la barre latérale, options d’affichage des panneaux pour les cartes de tunnel Cloudflare/Tailscale/ngrok
IA	Budget de réflexion (transmission / suppression automatique / personnalisé / adaptatif — voir THINKING_BUDGET.md), prompt système global, statistiques du cache de prompts
Sécurité	Paramètres de connexion/mot de passe, contrôle d’accès par IP, authentification API pour /models, blocage des fournisseurs, protection contre l’injection de prompts
Routage	Stratégie de routage globale (Remplissage prioritaire / Tourniquet / P2C / Aléatoire / Moins utilisé / Coût optimisé), alias de modèles avec caractères génériques, chaînes de repli, valeurs par défaut des combos
Résilience	File d’attente des requêtes, délai de récupération des connexions, configuration du disjoncteur des fournisseurs et comportement d’attente de la fin du délai de récupération
Avancé	Configuration globale du proxy (HTTP/SOCKS5), substitutions du proxy par fournisseur

L’onglet Général ne duplique plus les notes en lecture seule relatives à la journalisation et au cache. Les paramètres de conservation et d’optimisation de la base de données sont conservés via /api/settings/database ; le nettoyage manuel du cache utilise DELETE /api/cache. Les limites du nombre de lignes des journaux de requêtes et de proxy sont contrôlées par CALL_LOGS_TABLE_MAX_ROWS et PROXY_LOGS_TABLE_MAX_ROWS.

---

Gestion des coûts et des budgets

Accessible via Tableau de bord → Coûts.

Onglet	Objectif
Budget	Définir des limites de dépenses par clé API avec des budgets quotidiens/hebdomadaires/mensuels et un suivi en temps réel
Tarification	Afficher et modifier les entrées tarifaires des modèles — coût pour 1 000 tokens d’entrée/sortie par fournisseur

# API : définir un budget
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API : obtenir l’état actuel du budget
curl http://localhost:20128/api/usage/budget

Suivi des coûts : Chaque requête consigne l’utilisation des tokens et calcule le coût à l’aide de la grille tarifaire. Consultez les ventilations dans Tableau de bord → Utilisation par fournisseur, modèle et clé API.

---

Transcription audio

OmniRoute prend en charge la transcription audio via l’endpoint compatible avec OpenAI :

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# Exemple avec curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"

deepgram/nova-3 est la route Deepgram native et nécessite une clé API Deepgram. Si seul OpenRouter est configuré, utilisez openrouter/deepgram/nova-3.

Fournisseurs de reconnaissance vocale (transcription) :

• openai/ (compatible avec Whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (famille Nova)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (variantes de Whisper)
• qwen/

Fournisseurs de synthèse vocale (POST /v1/audio/speech) :

• openai/ (tts-1, tts-1-hd)
• hyperbolic/
• deepgram/ (Aura)
• nvidia/ (Magpie TTS)
• elevenlabs/
• huggingface/
• inworld/
• cartesia/
• playht/
• kie/
• aws-polly/
• xiaomi-mimo/
• coqui/, tortoise/
• qwen/

Formats audio pris en charge pour la transcription : mp3, wav, m4a, flac, ogg, webm. Les formats de sortie TTS dépendent du fournisseur (mp3, wav, opus, pcm, mulaw).

---

Stratégies d’équilibrage des combos

Configurez l’équilibrage de chaque combo dans Tableau de bord → Combos → Créer/Modifier → Stratégie.

Stratégie	Description
Round-Robin	Parcourt les modèles successivement
Priorité	Essaie toujours le premier modèle ; ne bascule qu'en cas d'erreur
Aléatoire	Choisit aléatoirement un modèle de la combinaison pour chaque requête
Pondérée	Achemine proportionnellement selon les poids attribués à chaque modèle
Le moins utilisé	Achemine vers le modèle ayant reçu le moins de requêtes récemment (utilise les métriques de la combinaison)
Optimisée selon le coût	Achemine vers le modèle disponible le moins cher (utilise la grille tarifaire)

Les valeurs globales par défaut des combinaisons peuvent être définies dans Tableau de bord → Paramètres → Routage → Valeurs par défaut des combinaisons. Par défaut, les délais d'expiration des cibles d'une combinaison héritent du délai d'expiration de la requête actuelle. Utilisez Délai d'expiration de la cible (secondes) dans les valeurs par défaut des combinaisons ou dans une combinaison individuelle uniquement lorsqu'une limite plus courte par cible doit déclencher un basculement plus rapide.

Les optimisations de combinaison à latence nulle sont facultatives. Laissez Optimisations à latence nulle désactivé pour empêcher ces fonctionnalités de latence de mettre en concurrence les cibles de basculement, d'ignorer des cibles en fonction de l'historique TTFT ou de compresser les requêtes de basculement ; leur activation permet à la couverture configurée, aux exclusions prédictives selon le TTFT et à la compression proactive du basculement de sacrifier la fidélité du routage et des requêtes au profit d'une latence de fin de distribution plus faible.

Désactivez Tampon de jetons de raisonnement lorsque les fournisseurs en amont imposent des limites strictes max_tokens / maxOutputTokens. Lorsque cette option est activée, le routage des combinaisons n'ajoute une marge pour les modèles de raisonnement qu'aux modèles dont la limite de sortie est connue et laisse inchangée la limite de jetons du client lorsque la valeur tamponnée sûre dépasserait cette limite. Si la limite du client est déjà supérieure à une limite connue, OmniRoute la réduit à cette limite avant d'envoyer la requête en amont.

---

Tableau de bord de l'état de santé

Accessible via Tableau de bord → État de santé. Vue d'ensemble en temps réel de l'état de santé du système avec 6 cartes :

Carte	Informations affichées
État du système	Durée de fonctionnement, version, utilisation de la mémoire, répertoire de données
État de santé des fournisseurs	État d'exécution global du disjoncteur des fournisseurs
Limites de débit	Délais de récupération actifs des connexions par compte avec temps restant
Verrouillages actifs	Verrouillages actifs propres aux modèles et exclusions temporaires
Cache de signatures	Statistiques du cache de déduplication (clés actives, taux de succès)
Télémétrie de latence	Agrégation des latences p50/p95/p99 par fournisseur

Conseil de pro : La page État de santé s'actualise automatiquement toutes les 10 secondes. Utilisez la carte du disjoncteur pour identifier les fournisseurs qui rencontrent des problèmes.

---

🤖 Routage automatique (sans configuration)

OmniRoute intègre un routeur automatique basé sur un score qui sélectionne le meilleur modèle pour chaque requête parmi tous les fournisseurs connectés — aucune combinaison à maintenir. Envoyez simplement la requête avec l’un des préfixes auto/* et OmniRoute assemblera à la volée une combinaison virtuelle, en évaluant les candidats selon la latence, le coût, le taux de réussite, l’adéquation au contexte, l’aptitude du modèle pour la tâche, les échecs récents, le quota et l’état du disjoncteur.

Préfixe	Optimise pour
auto	Équilibre par défaut (latence × coût × taux de réussite)
auto/coding	Tâches de programmation : privilégie Claude, GPT-5, GLM, Kimi, Qwen Coder et les modèles de code DeepSeek
auto/cheap	Coût par jeton le plus faible, avec une latence plus élevée acceptée
auto/fast	Latence la plus faible, sans tenir compte du coût
auto/offline	Fournisseurs locaux uniquement (Ollama, vLLM, llama.cpp) — utile pour les environnements isolés
auto/smart	Priorité à la qualité du raisonnement (Opus, GPT-5 xhigh, R1, raisonnement GLM 5.1)
auto/lkgp	« Dernier fournisseur fonctionnel connu » — reste sur le dernier fournisseur ayant réussi, puis applique les règles de repli

Exemple :

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Refactor this Python function" }],
    "stream": true
  }'

Le routeur automatique est décrit en détail dans AUTO-COMBO.md — notamment comment ajuster les pondérations de score, mettre des fournisseurs sur liste noire et examiner les décisions de routage dans Tableau de bord → Combinaison automatique.

---

🔌 Intégration MCP et A2A

OmniRoute est à la fois un serveur MCP (Model Context Protocol) et un serveur A2A (Agent-to-Agent JSON-RPC 2.0). Tout IDE ou hôte d’agent compatible MCP peut appeler directement les outils OmniRoute — aucune couche intermédiaire supplémentaire n’est requise.

Transports MCP

• SSE : http://localhost:20128/api/mcp/sse
• HTTP avec diffusion en continu : http://localhost:20128/api/mcp/stream
• stdio : omniroute --mcp (pour les extensions d’IDE qui préfèrent stdio)

Connecter Claude Desktop

Modifiez ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou le fichier équivalent sous Windows/Linux :

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

Connecter Cursor / Continue / VS Code MCP

Utilisez l’URL SSE http://localhost:20128/api/mcp/sse ainsi qu’une clé API Bearer générée dans Tableau de bord → Clés API.

Portées

MCP définit actuellement 32 portées nommées. Chaque clé Bearer peut être limitée à des portées spécifiques — consultez MCP-SERVER.md pour la liste de référence des portées et des outils, ainsi que A2A-SERVER.md pour le schéma JSON-RPC.

---

🧠 Système de compétences

OmniRoute propose un framework de compétences extensible (src/lib/skills/) afin que les agents et le point de terminaison A2A puissent exécuter des routines propres à un domaine (par exemple, code-review, summarize, extract-facts, web-research).

• Interface de la marketplace — Parcourez et installez des compétences depuis Tableau de bord → Compétences
• Portées par clé — Limitez les compétences que chaque clé API peut invoquer
• Compétences personnalisées — Déposez un fichier TypeScript dans src/lib/a2a/skills/, enregistrez-le et il devient immédiatement invocable via A2A

Référence complète : SKILLS.md.

---

💾 Système de mémoire

OmniRoute conserve une mémoire conversationnelle à long terme avec une récupération hybride :

• SQLite FTS5 pour la recherche par mots-clés dans les échanges passés
• Base vectorielle Qdrant (facultative) pour le rappel sémantique
• Extraction automatique de faits — les entités, préférences et décisions sont synthétisées après chaque session et stockées dans la table memory_facts
• Les mémoires sont isolées par clé API et par session

Gérez les mémoires dans Tableau de bord → Mémoire (recherche, modification, exportation, purge). L’interface HTTP (/api/memory/*) permet aux agents d’envoyer et d’interroger des faits par programmation — consultez MEMORY.md.

---

🔔 Webhooks

Abonnez-vous aux événements OmniRoute pour bénéficier d’une surveillance et d’une automatisation en temps réel.

• Créez un webhook dans Tableau de bord → Webhooks avec l’URL cible et le secret de signature HMAC
• Événements disponibles : request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
• Chaque charge utile inclut X-OmniRoute-Signature (HMAC-SHA256) à des fins de vérification
• Nouvelles tentatives : 3 tentatives avec temporisation exponentielle, puis placement dans une file d’attente des messages non distribuables

Schéma complet dans WEBHOOKS.md.

---

☁️ Agents cloud

OmniRoute s’intègre aux agents de programmation cloud (OpenAI Codex Cloud, Devin, Jules, Antigravity) afin que vous puissiez distribuer des tâches de longue durée depuis le même tableau de bord que celui utilisé pour gérer votre routage local.

• Créez des tâches dans Tableau de bord → Agents cloud ou via POST /api/v1/agents/tasks
• Suivez le statut, les journaux et les artefacts de chaque tâche
• Utilisez votre propre clé API pour chaque fournisseur — les identifiants ne quittent jamais l’instance OmniRoute

Référence complète : CLOUD_AGENT.md.

---

🛠️ Gestion par programmation

Vous pouvez gérer chaque ressource OmniRoute (fournisseurs, combos, clés, paramètres) via HTTP à l’aide d’une clé Bearer dotée de la portée manage.

Générez la clé dans Tableau de bord → Clés API → Nouvelle clé → Portée : manage, puis :

# Lister les fournisseurs
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Ajouter une connexion à un fournisseur
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# Créer un combo
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# Lister/créer des clés API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

Consultez API_REFERENCE.md pour obtenir le catalogue complet des points de terminaison et les schémas de requête/réponse.

---

💻 CLI interne

OmniRoute fournit une CLI interne (omniroute …) pour la configuration, les diagnostics et le contrôle de l’exécution. Elle est distincte de la page « Outils CLI » du tableau de bord, qui configure des CLI tierces (Claude Code, Cursor, Codex, Cline, …) afin qu’elles puissent communiquer avec OmniRoute.

omniroute setup                    # Assistant interactif (mot de passe, fournisseurs, combinaisons)
omniroute setup --non-interactive  # Adapté à la CI
omniroute doctor                   # Diagnostics d’intégrité (répertoire de données, BDD, fournisseurs, ports)
omniroute providers available      # Répertorie les fournisseurs pris en charge
omniroute providers list           # Répertorie les connexions configurées
omniroute providers test <id>      # Teste en direct une connexion à un fournisseur
omniroute combos list              # Répertorie les combinaisons
omniroute combos switch <name>     # Définit la combinaison par défaut
omniroute models                   # Répertorie les modèles disponibles (--json, --search)
omniroute keys add | list | remove # Gère les clés API depuis le terminal
omniroute backup                   # Crée un instantané de la configuration et de la BDD
omniroute restore [<timestamp>]    # Restaure depuis un instantané
omniroute health                   # État détaillé (disjoncteurs, cache, mémoire)
omniroute quota                    # Utilisation des quotas des fournisseurs
omniroute mcp status               # État du serveur MCP
omniroute a2a status               # État du serveur A2A
omniroute tunnel list|create|stop  # Tunnels Cloudflare/Tailscale/ngrok
omniroute reset-password           # Réinitialise le mot de passe administrateur
omniroute --mcp                    # Démarre le serveur MCP via stdio
omniroute --port 3000              # Démarre le serveur sur un port personnalisé

Conseil : associez omniroute doctor --json à votre outil de surveillance pour recevoir des alertes en cas de connexions défaillantes aux fournisseurs.

---

🖥️ Application de bureau (Electron)

OmniRoute est disponible sous forme d’application de bureau native pour Windows, macOS et Linux.

Installation

# Depuis le répertoire electron :
cd electron
npm install

# Mode développement (connexion au serveur de développement Next.js en cours d’exécution) :
npm run dev

# Mode production (utilise la version autonome) :
npm start

Création des programmes d’installation

cd electron
npm run build          # Plateforme actuelle
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg universel)
npm run build:linux    # Linux (.AppImage)

Sortie → electron/dist-electron/

Fonctionnalités principales

Fonctionnalité	Description
Disponibilité du serveur	Interroge le serveur avant d’afficher la fenêtre (aucun écran vide)
Zone de notification	Réduction dans la zone de notification, modification du port et fermeture depuis son menu
Gestion du port	Modification du port du serveur depuis la zone de notification (redémarre automatiquement le serveur)
Politique de sécurité du contenu	CSP restrictive via les en-têtes de session
Instance unique	Une seule instance de l’application peut s’exécuter à la fois
Mode hors ligne	Le serveur Next.js intégré fonctionne sans connexion Internet

Variables d’environnement

Variable	Valeur par défaut	Description
OMNIROUTE_PORT	20128	Port du serveur
OMNIROUTE_MEMORY_MB	512	Limite du tas Node.js (64–16384 Mo)

📖 Documentation complète : electron/README.md