OmniRoute Wizzard

Assistant de démarrage rapide pour OmniRoute.

OmniRoute Wizzard aide d'abord à démarrer vite avec OmniRoute : s'inscrire en série à des modèles d'IA gratuits ou payants, déclarer les accès, puis brancher les outils de travail sur une même configuration.

Le reste du projet sert de bonus utile : configuration déclarative, versionnable, exports clients, agents locaux, déploiement distant et contrôles. Objectif simple : passer plus vite de "j'ai accès à plusieurs modèles" à "VS Code, Hermes, OpenClaw et Buzz utilisent OmniRoute correctement".

Pourquoi

Démarrer avec OmniRoute commence souvent par une étape très concrète : s'inscrire à plusieurs fournisseurs et modèles d'IA, gratuits ou non, puis mettre ces accès derrière OmniRoute.

Sans wizzard, il faut ensuite refaire plusieurs petites étapes répétitives :

• déclarer les providers et modèles disponibles;
• choisir les modèles ou combos à exposer dans OmniRoute;
• configurer VS Code pour utiliser OmniRoute;
• configurer Hermes, OpenClaw et Buzz avec des formats différents;
• éviter de committer les clés API;
• tester une config avant de l'installer;
• refaire la même configuration sur une autre machine ou un VPS.

OmniRoute Wizzard centralise ces choix dans config/, puis applique la bonne forme pour chaque outil.

Ce que fait le wizzard

• Aide à organiser l'inscription et l'activation en série des modèles IA.
• Centralise les providers, combos, clients et endpoints dans config/.
• Configure Hermes, OpenClaw, Buzz et VS Code Custom Endpoint.
• Génère les fichiers de configuration depuis des YAML lisibles.
• Lance des agents locaux avec Docker Compose.
• Déploie des configurations sur un serveur par SSH/SCP.
• Crée des backups avant remplacement.
• Valide les fichiers déclaratifs avec doctor.
• Garde les secrets hors Git via ${VAR} et ${VAR:-default}.

Installation

Prérequis :

• Python 3.10 ou plus récent;
• ssh et scp pour les déploiements distants;
• Docker Compose seulement pour les agents locaux.

Depuis un clone Git :

git clone https://github.com/OWNER/omniroute_wizzard.git
cd omniroute_wizzard
./install.sh

Installation en une ligne, une fois le dépôt publié sur GitHub :

curl -fsSL https://raw.githubusercontent.com/OWNER/omniroute_wizzard/main/bootstrap.sh \
  | sh -s -- https://github.com/OWNER/omniroute_wizzard.git

Remplacer OWNER par le compte ou l'organisation GitHub.

Depuis un dossier déjà cloné :

./install.sh

Si votre python3 pointe vers une version trop ancienne :

PYTHON=/chemin/vers/python3.12 ./install.sh

Vérifier :

./omniroute_wizzard --help
./omniroute_wizzard doctor

Démarrage rapide

1. S'inscrire en série aux modèles d'IA.

Créer ou compléter les accès chez les providers souhaités, puis renseigner les modèles exposés à OmniRoute dans :

config/providers.yaml
config/combos.yaml

Garder les vraies clés API dans des variables d'environnement, pas dans Git.

2. Paramétrer VS Code pour utiliser OmniRoute.

Par défaut, le wizzard cible :

http://localhost:20128

Configurer l'endpoint :

# config/endpoint.yaml
url: http://localhost:20128
api_key: ${OMNIROUTE_API_KEY:-sk_omniroute}

Vérifier la configuration VS Code :

./omniroute_wizzard doctor --client vscode
./omniroute_wizzard configure vscode --dry-run

3. Paramétrer Hermes, OpenClaw et Buzz pour utiliser OmniRoute.

Vérifier toute la configuration :

./omniroute_wizzard doctor

Générer les configurations clients :

./omniroute_wizzard export hermes --clean
./omniroute_wizzard export openclaw --clean
./omniroute_wizzard export buzz --clean

Exemple de fichier généré pour Hermes :

export/hermes/.hermes/config.yaml

Lancer un agent local si besoin :

./omniroute_wizzard local hermes --dry-run
./omniroute_wizzard local hermes

Configuration déclarative

Le dépôt devient la source de vérité.

config/
├── endpoint.yaml
├── combos.yaml
├── providers.yaml
├── clients/
│   ├── buzz.yaml
│   ├── hermes.yaml
│   ├── openclaw.yaml
│   └── vscode.yaml
└── servers/
    ├── local.yaml
    ├── local-agents.yaml
    └── vps-agents.yaml

Organisation du code

Le code Python vit dans src/omniroute_wizzard/.

src/omniroute_wizzard/
├── cli.py              # commandes et options CLI
├── config.py           # lecture YAML et variables d'environnement
├── security.py         # masquage des secrets
├── adapters/           # rendu par client IA
└── commands/           # workflows CLI

Le principe est volontairement simple :

• cli.py lit la commande demandée;
• config.py charge les YAML;
• un adapter transforme endpoint + client en fichiers;
• une commande décide où écrire, déployer ou vérifier ces fichiers.

Endpoint OmniRoute

url: http://localhost:20128
api_key: ${OMNIROUTE_API_KEY:-sk_omniroute}

Pour un vrai secret :

export OMNIROUTE_API_KEY='...'

Client Hermes

enabled: true
adapter: hermes
target: .hermes/config.yaml
model: dev
reasoning_model: reasoning
fast_model: dev-fast

Client OpenClaw

enabled: true
adapter: openclaw
target: .openclaw/openclaw.json
model: dev
reasoning_model: reasoning
fast_model: dev-fast

Client Buzz

enabled: true
adapter: buzz
target: .config/buzz/omniroute.env
model: dev

Client VS Code

enabled: true
adapter: vscode
target: Library/Application Support/Code/User/chatLanguageModels.json
model: auto/coding
reasoning_model: auto
fast_model: auto/fast

Commandes utiles

Lister ce qui est déclaré :

./omniroute_wizzard show

Valider tout :

./omniroute_wizzard doctor

Valider un client :

./omniroute_wizzard doctor --client vscode

Générer une config sans l'installer :

./omniroute_wizzard export openclaw --clean

Sauvegarder le dossier config/ :

./omniroute_wizzard backup

Agents Docker locaux

Les stacks Docker locales permettent de démarrer Hermes, OpenClaw ou Buzz déjà branchés sur OmniRoute.

Ces conteneurs n'embarquent pas OmniRoute. Ils utilisent l'instance OmniRoute de la machine hôte via :

http://host.docker.internal:20128

Exemples :

./omniroute_wizzard local hermes
./omniroute_wizzard local openclaw
./omniroute_wizzard local buzz

Les fichiers générés sont placés dans runtime/.

Pour contrôler avant lancement :

./omniroute_wizzard local hermes --dry-run

Images surchargeables :

OPENCLAW_IMAGE=my-openclaw:latest ./omniroute_wizzard local openclaw
BUZZ_IMAGE=my-buzz:latest ./omniroute_wizzard local buzz

Configuration VS Code

Le wizzard sait ajouter ou remplacer uniquement le bloc OmniRoute dans chatLanguageModels.json, sans supprimer Gemini, Copilot ou les autres providers.

Simulation :

./omniroute_wizzard configure vscode --dry-run

Application :

./omniroute_wizzard configure vscode

Avec un fichier explicite :

./omniroute_wizzard configure vscode \
  --file "$HOME/Library/Application Support/Code/User/chatLanguageModels.json"

Après modification, recharger VS Code :

Developer: Reload Window

Déploiement sur VPS

Déclarer un serveur :

# config/servers/vps-agents.yaml
host: agents.example.com
user: debian
port: 22
target_dir: ~/.config/omniroute-wizzard

clients:
  - hermes
  - openclaw
  - buzz

restart:
  - systemctl --user restart hermes.service || true
  - systemctl --user restart openclaw.service || true

healthcheck:
  - test -f ~/.hermes/config.yaml
  - test -f ~/.openclaw/openclaw.json

Tester sans rien modifier :

./omniroute_wizzard deploy vps-agents --dry-run

Déployer :

./omniroute_wizzard deploy vps-agents

Déployer un seul client :

./omniroute_wizzard deploy vps-agents --client hermes

Le déploiement :

1. crée un staging distant;
2. rend les configs localement;
3. envoie les fichiers avec scp;
4. sauvegarde chaque fichier distant existant en .bak-YYYYMMDD-HHMMSS;
5. installe la nouvelle version;
6. supprime le staging;
7. exécute les commandes restart;
8. exécute les healthcheck.

Le CLI utilise les commandes système ssh et scp; votre ~/.ssh/config, vos clés, votre agent SSH et vos alias continuent donc de fonctionner.

Secrets

Ne mettez pas de vraie clé API dans config/.

Préférer :

api_key: ${OMNIROUTE_API_KEY}

ou, pour un environnement local sans secret réel :

api_key: ${OMNIROUTE_API_KEY:-sk_omniroute}

Le moteur remplace les formes ${VAR} et ${VAR:-default} au chargement. Si une variable sans valeur par défaut n'est pas définie, la référence reste littérale dans le rendu; cela permet de laisser le secret être résolu sur la machine cible quand le client le supporte.

Ajouter un client IA

Créer un adapter :

src/omniroute_wizzard/adapters/myagent.py

from .base import Adapter


class MyAgentAdapter(Adapter):
    name = "myagent"

    def render(self, client_cfg, endpoint):
        return {
            ".config/myagent/config.json": "..."
        }

Enregistrer l'adapter :

src/omniroute_wizzard/adapters/registry.py

Ajouter la déclaration :

config/clients/myagent.yaml

Puis vérifier :

./omniroute_wizzard doctor --client myagent
./omniroute_wizzard export myagent --clean

Philosophie

OmniRoute Wizzard ne remplace pas OmniRoute. Il réduit la friction autour du démarrage et de la configuration des clients IA.

config/
   ↓
omniroute_wizzard
   ├── doctor
   ├── export
   ├── local
   ├── configure vscode
   ├── deploy
   └── backup

Une fois les choix déclarés dans Git, vous pouvez reconstruire rapidement une machine de développement, préparer un VPS d'agents, ou partager une configuration OmniRoute propre sans copier de secrets.

Roadmap

• Commande diff avant déploiement.
• Vrai sync bidirectionnel.
• Pull des configs distantes.
• Rollback automatique depuis backup.
• Chiffrement SOPS/age pour secrets.
• Bootstrap complet d'un VPS agent.
• Adapters supplémentaires pour autres outils IA.