Claude Code CLI — Configuration with OmniRoute (Français)

Démarrage rapide

# Lancer Claude Code avec une instance OmniRoute locale (détecte automatiquement le contexte actif)
omniroute launch

# Avec une instance OmniRoute distante (après `omniroute connect <host>`, cela devient automatique)
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Générer les profils par modèle, puis en lancer un
omniroute setup-claude            # écrit dans ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # Claude Code utilisant glm/glm-5.2 via OmniRoute

---

Comment Claude Code se connecte à une passerelle

Claude Code communique avec l’API Anthropic Messages et est dirigé vers un point de terminaison personnalisé au moyen de variables d’environnement (il ne possède pas d’option --base-url) :

Variable	Objectif
ANTHROPIC_BASE_URL	URL racine de la passerelle (Claude Code ajoute /v1/messages). Aucun suffixe /v1.
ANTHROPIC_AUTH_TOKEN	Envoyé sous la forme Authorization: Bearer … — utilisez votre jeton d’accès / clé API OmniRoute
ANTHROPIC_API_KEY	Alternative : envoyé sous la forme x-api-key. Si les deux sont définis, ANTHROPIC_AUTH_TOKEN est prioritaire
ANTHROPIC_MODEL	Imposer un modèle spécifique (remplace la valeur par défaut du sélecteur /model)
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY	1 → le sélecteur natif /model répertorie les modèles claude*/anthropic* provenant de /v1/models
CLAUDE_CODE_MAX_OUTPUT_TOKENS	Limiter le nombre de jetons de sortie par réponse (par ex. 65536)
CLAUDE_CODE_AUTO_COMPACT_WINDOW	Seuil de jetons pour la compaction automatique

Les variables d’environnement ne sont lues qu’une seule fois au démarrage — redémarrez Claude Code après les avoir modifiées.

omniroute launch définit toutes ces variables pour vous : la commande détermine l’URL de base et le jeton à partir du contexte actif (omniroute connect <vps> suivi de omniroute launch fonctionne donc directement), vérifie l’état du serveur, puis exécute claude.

---

Alias de découverte — afficher les modèles non-Claude dans le sélecteur /model

La découverte des modèles de passerelle de Claude Code répertorie uniquement les identifiants commençant par claude ou anthropic. Ainsi, avec CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, le sélecteur natif /model n’affiche normalement que les modèles Claude/Anthropic d’OmniRoute — un modèle kimi/kimi-k2.6 ou glm/glm-5.2 n’apparaît jamais, même si son routage fonctionne correctement.

OmniRoute peut exposer un alias de n’importe quel modèle activé (ainsi que de toute combinaison) sous un identifiant claude/… afin qu’il passe ce filtre et apparaisse dans le sélecteur :

kimi/kimi-k2.6            →  claude/kimi/kimi-k2.6      "Kimi K2.6 (OmniRoute)"
glm/glm-5.2              →  claude/glm/glm-5.2         "GLM 5.2 (OmniRoute)"
<combo "custo-otimizado"> →  claude/combo/custo-otimizado

Lorsque vous sélectionnez l’un de ces modèles dans Claude Code, OmniRoute retire l’enveloppe claude/ pour rétablir l’identifiant réel avant le routage — un véritable identifiant claude/<real-claude-model> (celui du fournisseur OAuth Claude réel) reste toujours inchangé.

Cette fonctionnalité est désactivée par défaut et contrôlée par trois niveaux (le plus spécifique est prioritaire), afin qu’une installation OmniRoute standard ne duplique jamais son catalogue pour les clients qui n’utilisent pas Claude Code :

Niveau	Emplacement
Modèle	Page de détails du fournisseur → option « Expose in Claude Code » par modèle
Fournisseur	Page de détails du fournisseur → option au niveau du fournisseur (couvre tous ses modèles)
Global	Paramètres → Indicateurs de fonctionnalités → EXPOSE_CC_DISCOVERY_ALIASES (désactivé par défaut)

La variable d’environnement EXPOSE_CC_DISCOVERY_ALIASES force l’activation au niveau global et est prioritaire sur le réglage du tableau de bord (l’écran des indicateurs de fonctionnalités affiche une mention « actif via une variable d’environnement » lorsque c’est le cas). Les options par fournisseur et par modèle permettent ensuite d’affiner ce comportement — par exemple, niveau global désactivé + fournisseur Kimi activé expose uniquement les modèles de Kimi.

⚠️ Différence de fenêtre pour les modèles non-Claude. Claude Code suppose une fenêtre de contexte de 200K pour tout identifiant qu’il ne reconnaît pas (il ne peut pas lire la fenêtre réelle depuis /v1/models). Pour un modèle disposant d’une fenêtre plus grande (par ex. les 256K de Kimi K2), définissez CLAUDE_CODE_AUTO_COMPACT_WINDOW sur une valeur inférieure à la fenêtre réelle du modèle afin que la compaction automatique ne se déclenche pas prématurément. Les profils générés ci-dessus le font déjà pour chaque modèle.

---

Bloc d’intégration sur le tableau de bord

La carte de l’outil Claude (Tableau de bord → Code CLI) affiche le fragment settings.json exact pour cette instance, à côté du bouton d’information sur l’alias de découverte, avec un bouton de copie :

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}

L’URL de base est celle résolue par la carte (y compris une valeur de remplacement personnalisée que vous avez saisie), déjà normalisée — sans suffixe /v1 ni barre oblique finale. La clé n’est jamais affichée : le bloc contient un espace réservé, afin qu’une capture d’écran ou un extrait collé ne puisse pas la divulguer. Remplacez-le par votre clé.

Ajoutez CLAUDE_CODE_AUTO_COMPACT_WINDOW sous le même bloc env pour tout modèle dont la fenêtre de contexte réelle n’est pas de 200K — Claude Code suppose une valeur de 200K pour chaque identifiant qu’il ne reconnaît pas, de sorte que la compression automatique se déclenche sinon au mauvais moment (consultez l’avertissement de la section précédente). Le générateur d’extrait accepte également cette valeur, afin qu’un appelant connaissant la fenêtre du modèle cible puisse l’émettre directement.

Source : src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet (générateur pur, testé unitairement) affiché par ClaudeGatewayOnboardingBlock.

---

Profils (CLAUDE_CONFIG_DIR)

Claude Code ne dispose d’aucun fichier de profil natif (contrairement au fichier ~/.codex/<name>.config.toml de Codex). Le mécanisme idiomatique est CLAUDE_CONFIG_DIR — un répertoire de configuration distinct pour chaque profil, chacun avec ses propres settings.json, identifiants, historique et cache.

omniroute setup-claude récupère le catalogue /v1/models en direct et écrit un profil par modèle dans ~/.claude/profiles/<name>/settings.json, en réutilisant les mêmes noms que setup-codex (glm52, kimi-k27, deepseek-pro, …) :

~/.claude/profiles/glm52/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "glm/glm-5.2",
  "effortLevel": "xhigh",
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
    "ANTHROPIC_MODEL": "glm/glm-5.2",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  },
}

Le jeton d’authentification n’est jamais écrit dans le profil. Lancez avec omniroute launch --profile <name> (cette commande injecte ANTHROPIC_AUTH_TOKEN depuis le contexte actif), ou exportez vous-même ANTHROPIC_AUTH_TOKEN et exécutez CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude.

Synchronisation automatique après la découverte des modèles (facultative). OmniRoute peut régénérer automatiquement ces mêmes fichiers ~/.claude/profiles/<name>/settings.json chaque fois qu’une synchronisation des modèles d’un fournisseur modifie le catalogue en direct — ainsi, les modèles nouveaux ou renommés obtiennent des profils sans qu’il soit nécessaire de réexécuter la commande. Cette fonctionnalité est désactivée par défaut : activez-la depuis le tableau de bord Code CLI (« Synchronisation automatique des profils CLI » → Claude Code), ou définissez OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true (elle respecte également CLI_ALLOW_CONFIG_WRITES, activé par défaut). Lorsqu’elle est activée, elle écrit uniquement les fichiers de profil ; elle ne modifie jamais votre configuration Claude active/par défaut, votre authentification ni le fichier ~/.claude/settings.json.

Génération et utilisation des profils

# OmniRoute local
omniroute setup-claude

# VPS distant (intègre l’URL du VPS dans chaque profil)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Seulement certains fournisseurs
omniroute setup-claude --only glm,kimi

# Prévisualisation sans écriture
omniroute setup-claude --dry-run

# Lancer un profil
omniroute launch --profile kimi-k27

---

Niveaux de modèles (facultatif)

Claude Code achemine les requêtes vers différents niveaux de capacités. Associez chacun d’eux à un modèle OmniRoute via les variables d’environnement ou les paramètres si vous souhaitez utiliser des fournisseurs différents selon le niveau :

export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"

Sinon, un seul ANTHROPIC_MODEL (celui défini par les profils) est utilisé pour tout.

---

Mode distant

Une fois que vous avez exécuté omniroute connect <host> (voir Mode distant), omniroute launch et omniroute setup-claude ciblent automatiquement ce serveur distant et utilisent son jeton d’accès limité à sa portée — aucun indicateur supplémentaire n’est nécessaire. Remplacez ces paramètres pour une invocation donnée avec --remote / --api-key.

---

Dépannage

Claude Code ignore la passerelle — vérifiez que ANTHROPIC_BASE_URL ne contient pas /v1 et redémarrez claude (les variables d’environnement ne sont lues qu’une seule fois au démarrage). omniroute launch s’en charge pour vous.

Le sélecteur /model est vide / les modèles de la passerelle sont absents — nécessite Claude Code v2.1.219+ et CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Seuls les identifiants de modèles claude* / anthropic* apparaissent dans le sélecteur ; forcez l’utilisation de tout autre modèle avec ANTHROPIC_MODEL=<id> (c’est ce que font les profils).

400 Ambiguous model 'claude-…' — Claude Code envoie toujours des identifiants de modèles sans préfixe (par ex. claude-opus-4-8). Ainsi, lorsque les fournisseurs Claude Code (cc/…) et Claude (claude/…) sont tous deux connectés, l’identifiant sans préfixe correspond à deux routes et OmniRoute refuse de choisir arbitrairement. Vous pouvez résoudre le problème de l’une des manières suivantes : définissez un identifiant préfixé avec ANTHROPIC_MODEL=cc/claude-opus-4-8, ou activez Préférer Claude Code pour les modèles Claude sans préfixe — via le bouton sur la page du fournisseur Claude, ou OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true (désactivé par défaut ; voir Environnement) — ce qui achemine plutôt les identifiants claude-* sans préfixe vers Claude Code. Les préfixes explicites de fournisseurs sont toujours prioritaires.

Erreurs d’authentification — le profil ne contient aucun jeton. Utilisez omniroute launch --profile (qui l’injecte) ou exportez ANTHROPIC_AUTH_TOKEN.

Les profils ne sont pas isolés — chaque profil utilise un CLAUDE_CONFIG_DIR distinct ; vérifiez que echo $CLAUDE_CONFIG_DIR dans la session pointe vers ~/.claude/profiles/<name>.

---

Code source d’OmniRoute (a58000c7685f)