Documentation/Guide d'intégration

Configurer Codex via le fournisseur universel de CC Switch

À propos de ce document

Ce document explique comment utiliser la fonctionnalité de fournisseur universel (Universal Provider) de CC Switch pour connecter l'outil en ligne de commande OpenAI Codex à une passerelle API désignée et faire prendre effet à la configuration.

Versions applicables : CC Switch v3.16.x et versions ultérieures.

Source des informations : le manuel utilisateur et le code source du dépôt officiel de CC Switch. Le logiciel évolue rapidement. Si l'interface du produit diffère de la description de ce document, l'affichage réel dans l'application fait foi.

Terminologie

Terme Description
Codex Assistant de programmation IA en ligne de commande fourni par OpenAI. Une fois installé, exécutez la commande codex dans le terminal pour le démarrer.
CC Switch Outil de bureau multiplateforme de gestion de la configuration, destiné à gérer les endpoints de service et les identifiants d'outils tels que Codex, Claude Code et Gemini CLI. CC Switch ne fournit aucune capacité d'IA par lui-même et se charge uniquement de générer et de basculer les fichiers de configuration.
Fournisseur (Provider) Partie qui fournit la capacité d'inférence des modèles. Il peut s'agir du service officiel d'un éditeur de modèles, ou d'une passerelle API construite en propre ou achetée.
API Key Chaîne de clé utilisée pour l'authentification, commençant généralement par sk-.
Fournisseur universel (Universal Provider) Fonctionnalité de CC Switch. Une seule configuration peut être synchronisée en même temps vers les trois outils Claude Code, Codex et Gemini CLI. Elle convient aux passerelles qui prennent en charge plusieurs protocoles d'API à la fois (par exemple NewAPI).
Fournisseur propre à l'application Configuration de fournisseur qui ne s'applique qu'à un seul outil, par opposition au fournisseur universel.

Avant de commencer

Configuration requise

Système d'exploitation Version minimale Architecture
Windows Windows 10 x64
macOS macOS 12 (Monterey) Intel (x64) / Apple Silicon (arm64)
Linux Ubuntu 22.04 / Debian 11 / Fedora 34 et versions équivalentes x64 / ARM64

Node.js 18 ou une version ultérieure est également requis. Les étapes d'installation sont indiquées à la « Tâche 1 ».

Informations à obtenir au préalable

Avant de commencer la configuration, veuillez obtenir les quatre informations suivantes auprès du fournisseur du service API. S'il en manque une seule, la configuration ne peut pas être terminée.

Élément Description Exemple
Adresse API (Base URL) Adresse de service de la passerelle https://seedrouter.net
API Key Clé d'authentification sk-xxxxxxxxxxxx
Nom du modèle Identifiant du modèle utilisé côté Codex gpt-5.6-sol
Prise en charge du protocole Indique si la passerelle prend en charge le protocole OpenAI Responses Pris en charge / Non pris en charge

Point clé : le quatrième point détermine si ce document s'applique. Dans la configuration que le fournisseur unifié génère pour Codex, le protocole de communication est fixé à wire_api = "responses" et ne peut pas être modifié. Si la passerelle ne prend pas en charge le protocole Responses et ne prend en charge que le protocole Chat Completions, vous ne pouvez pas utiliser le fournisseur unifié. Utilisez à la place la solution F de la section « Dépannage ».

Ouvrir le terminal

Ce document demande à plusieurs reprises d'exécuter des commandes dans le terminal. Voici comment l'ouvrir :

  • Windows : appuyez sur Win + R, saisissez powershell, puis appuyez sur Entrée.
  • macOS : appuyez sur Command + Espace, saisissez terminal, puis appuyez sur Entrée.
  • Linux : utilisez l'application de terminal fournie avec la distribution.

Tâche 1 : installer Node.js

À propos de cette tâche

Codex est distribué via npm, le gestionnaire de paquets de Node.js. Même avec l'installation en un clic de CC Switch, vous devez d'abord disposer d'un environnement d'exécution Node.js.

Procédure

  1. Accédez au site officiel de Node.js.

  2. Téléchargez le programme d'installation marqué LTS (support à long terme). Ne téléchargez pas la version Current.

  3. Exécutez le programme d'installation et terminez l'installation avec les options par défaut, sans modifier aucun paramètre.

    Si vous utilisez macOS et que Homebrew est déjà installé, vous pouvez aussi exécuter brew install node dans le terminal.

  4. Fermez toutes les fenêtres de terminal actuellement ouvertes, puis ouvrez une nouvelle fenêtre de terminal.

  5. Exécutez successivement les commandes suivantes pour vérifier l'installation :

    node --version
      npm --version

Résultat

Les deux commandes affichent chacune un numéro de version (par exemple v22.14.0 et 10.9.2), et la version de Node.js est au moins v18, ce qui indique que l'installation a réussi.

Remarque : si le message « n'est pas reconnu en tant que commande interne ou externe » ou « command not found » s'affiche, c'est en général parce que la fenêtre du terminal n'a pas été rouverte. Une commande nouvellement installée ne prend effet que dans une nouvelle session de terminal.

Tâche 2 : installer CC Switch

À propos de cette tâche

CC Switch est un logiciel gratuit et open source, distribué uniquement par les deux canaux suivants :

Avertissement : tout site ou client « CC Switch » qui demande un paiement, une recharge ou des identifiants de connexion à un compte n'est pas un canal officiel. Ne le téléchargez pas et ne l'utilisez pas.

Procédure

Windows

  1. Ouvrez la page Releases GitHub et, sous l'entrée de la dernière version, trouvez CC-Switch-v3.16.x-Windows.msi dans la zone Assets.

  2. Téléchargez-le, double-cliquez pour exécuter le programme d'installation, puis suivez les invites pour terminer l'installation.

    Si un double-clic ne produit aucune réaction, le fichier est bloqué par la stratégie de sécurité du système. Cliquez avec le bouton droit sur le fichier, sélectionnez Propriétés, cochez Débloquer dans la zone Sécurité en bas de l'onglet Général, cliquez sur OK, puis relancez-le.

    Si vous ne souhaitez pas l'installer sur le système, vous pouvez aussi télécharger la version sans installation CC-Switch-v3.16.x-Windows-Portable.zip, la décompresser, puis exécuter directement CC-Switch.exe.

macOS

Utilisez l'une des méthodes suivantes :

  • Méthode 1 (recommandée si Homebrew est déjà installé) : exécutez dans le terminal

    brew install --cask cc-switch

  • Méthode 2 : téléchargez CC-Switch-v3.16.x-macOS.dmg, double-cliquez pour l'ouvrir, puis faites glisser l'icône CC Switch dans le dossier « Applications ».

    Remarque : la version macOS est signée et notariée par Apple. Vous pouvez l'installer et l'ouvrir directement. L'invite « le développeur ne peut pas être vérifié » n'apparaît pas, et aucune opération supplémentaire de levée de quarantaine n'est nécessaire.

Linux

Choisissez selon la distribution :

  • Debian / Ubuntu : téléchargez le paquet .deb, puis exécutez

    sudo dpkg -i CC-Switch-v3.16.x-Linux-*.deb
      sudo apt-get install -f

  • Arch Linux : paru -S cc-switch-bin

  • Autres distributions : téléchargez le .AppImage, exécutez chmod +x pour ajouter le droit d'exécution, puis lancez-le directement.

Résultat

Après le lancement de CC Switch, la fenêtre principale s’affiche normalement et l’icône CC Switch apparaît dans la zone de notification (en bas à droite sous Windows, à droite de la barre des menus sous macOS), ce qui indique que l’installation a réussi.

Au premier lancement, si vous êtes invité à importer la configuration des outils CLI existants, il est recommandé de choisir l’importation. Cette opération enregistre la configuration actuelle en tant que fournisseur par défaut et n’entraîne aucune perte de configuration.

Tâche 3 : installer Codex

À propos de cette tâche

Vous pouvez effectuer l’installation depuis l’interface graphique de CC Switch ou en ligne de commande. Si c’est votre première utilisation, la méthode A est recommandée.

Procédure

Méthode A : installation via CC Switch (recommandée)

  1. Lancez CC Switch.

  2. Accédez à Settings > About.

  3. Dans la zone Local Environment Check, consultez l’état de la ligne Codex.

  4. Si Not detected s’affiche, cliquez sur le bouton Install à droite de cette ligne.

    L’installation s’exécute silencieusement en arrière-plan, la progression s’affiche sur le bouton et, une fois l’opération terminée, le numéro de version est actualisé automatiquement.

Remarque : les mises à niveau ultérieures s’effectuent également dans cette interface. Lorsqu’une nouvelle version est détectée, vous pouvez effectuer une mise à niveau individuelle, ou cliquer sur Upgrade All pour un traitement par lot.

Méthode B : installation en ligne de commande

  1. Ouvrez le terminal.

  2. Exécutez la commande suivante :

    npm install -g @openai/codex

    Si le téléchargement est trop lent, vous pouvez utiliser un miroir à la place :

    npm install -g @openai/codex --registry=https://registry.npmmirror.com

    Pour utiliser le miroir de façon durable, exécutez d’abord une fois la commande suivante afin d’appliquer le réglage global :

    npm config set registry https://registry.npmmirror.com

Résultat

Après avoir fermé puis rouvert le terminal, exécutez la commande suivante :

codex --version

L’affichage du numéro de version indique que l’installation a réussi.

Remarque : à ce stade, la configuration du fournisseur n’est pas encore terminée, et lancer directement codex provoque une erreur en l’absence d’identifiants valides ; ce comportement est attendu. La configuration s’effectue dans la tâche 4.

Tâche 4 : créer un fournisseur unifié

À propos de cette tâche

Dans cette tâche, vous créez dans CC Switch une configuration de fournisseur unifié et la synchronisez avec la liste des fournisseurs de Codex.

Procédure

  1. Lancez CC Switch.

  2. Dans le sélecteur d’applications en haut, passez à Codex.

    Passer au panneau Claude ou Gemini permet également d’accéder à l’entrée du fournisseur unifié ; les trois partagent la même configuration.

  3. Cliquez sur le bouton ＋ en haut à droite pour ouvrir le panneau d’ajout de fournisseur.

  4. En haut du panneau, sélectionnez l’onglet Unified Provider.

    Restriction : les panneaux OpenCode, OpenClaw, Hermes et Claude Desktop ne prennent pas en charge le fournisseur unifié, et cet onglet n’y est pas affiché. Si vous ne voyez pas cet onglet, passez d’abord au panneau Claude, Codex ou Gemini.

  5. Cliquez sur Add Unified Provider.

  6. Renseignez les champs du formulaire selon le tableau suivant :

    Champ Instructions de remplissage
    Select Preset Type Si la passerelle est NewAPI, sélectionnez NewAPI ; dans les autres cas, ou en cas de doute, sélectionnez Custom Gateway. Les deux comportent exactement les mêmes champs ; seules les valeurs par défaut diffèrent.
    Name Nom d’identification personnalisé, par exemple Passerelle NewAPI. Ce nom s’affichera sur la carte de fournisseur de Codex.
    API Address Saisissez le Base URL obtenu au préalable. Pour les règles de saisie, reportez-vous plus bas à « Règles de traitement de l’adresse API ».
    API Key Saisissez la clé obtenue au préalable. Vous pouvez cliquer sur l’icône d’œil à droite pour basculer l’affichage en clair.
    Official Website Facultatif. Une fois renseignée, elle permet d’y accéder directement depuis la carte du fournisseur.
    Notes Facultatif. Il est recommandé d’y noter l’origine de la clé, sa période de validité et d’autres informations de ce type.
    Enabled Apps Comprend trois interrupteurs : Claude Code, OpenAI Codex et Gemini. Vous devez activer OpenAI Codex. Si cette passerelle sert également aux deux autres outils, vous pouvez aussi les activer.
    Model Configuration > Codex > Model Saisissez le nom du modèle obtenu au préalable, par exemple gpt-5.6-sol.
    Model Configuration > Codex > Reasoning Effort Intensité du raisonnement. Les valeurs possibles sont low, medium ou high. En l’absence d’exigence particulière, indiquez high.

    Remarque : le formulaire de fournisseur unifié ne fournit pas le bouton « Fetch Models ». Le nom du modèle doit être saisi manuellement et est sensible à la casse.

  7. Cliquez sur Add.

Résultat

L'interface indique « Unified provider added and synced ». CC Switch a alors généré une carte de fournisseur du même nom dans la liste des fournisseurs de Codex ; si d'autres applications ont été cochées, une carte est également générée dans les listes correspondantes.

Point clé : la synchronisation n'équivaut pas à l'activation. À ce stade, la configuration n'a pas encore été écrite dans le fichier de configuration d'exécution de Codex ; vous devez poursuivre avec la tâche 5.

Règles de traitement de l'adresse API

Lorsque CC Switch génère la configuration pour Codex, il traite l'adresse API saisie comme suit :

Forme de l'adresse saisie Résultat du traitement
Domaine seul, sans chemin, par exemple https://seedrouter.net Complétée automatiquement en https://seedrouter.net/v1
Se termine déjà par /v1, par exemple https://seedrouter.net/v1 Utilisée telle quelle
Contient un autre chemin, par exemple https://api.example.com/openai Utilisée telle quelle, sans ajout de /v1

Le critère est le suivant : une fois /responses ajouté à l'adresse traitée, le résultat doit être le chemin d'endpoint réellement utilisable sur la passerelle. Avant la saisie, il est recommandé de confirmer l'adresse d'endpoint complète auprès du fournisseur de service, puis d'en déduire à rebours, d'après le tableau ci-dessus, ce qu'il faut saisir. Une adresse incorrecte entraîne le renvoi de 404 par la requête.

Tâche 5 : activer le fournisseur et faire prendre effet à la configuration

À propos de cette tâche

Une fois la carte de fournisseur générée, vous devez l'activer manuellement pour que la configuration soit écrite dans le fichier de configuration de Codex. Codex ne prend pas en charge le rechargement à chaud de la configuration ; après l'activation, vous devez redémarrer le terminal.

Procédure

  1. Fermez le panneau d'ajout de fournisseur.

  2. Dans le sélecteur d'applications en haut, passez à Codex.

  3. Dans la liste des fournisseurs, trouvez la carte du même nom créée lors de la tâche 4.

  4. Cliquez sur le bouton Enable de la carte.

    La carte s'affiche avec une bordure bleue et le libellé « Currently Enabled », ce qui indique que la configuration a été écrite.

  5. Fermez complètement la fenêtre de terminal en cours, puis ouvrez une nouvelle fenêtre de terminal.

    Point clé : il s'agit ici de fermer l'intégralité de la fenêtre de terminal, et non de quitter le processus codex pour relancer ensuite la commande codex. Les modalités de prise d'effet varient selon les outils :

    Outil Prise d'effet après changement de fournisseur
    Claude Code Prise d'effet immédiate, rechargement à chaud pris en charge
    Gemini CLI Prise d'effet immédiate, la configuration est relue à chaque requête
    Codex Il faut fermer le terminal, puis le rouvrir
    OpenCode / OpenClaw Il faut fermer le terminal, puis le rouvrir

  6. Dans le nouveau terminal, exécutez :

    codex

  7. Après le démarrage, saisissez une phrase de test, par exemple « Bonjour, veuillez vous présenter brièvement ».

Résultat

Le modèle renvoie normalement une réponse, ce qui indique que la configuration est terminée et que Codex est connecté à la passerelle spécifiée.

Référence : fichiers de configuration générés

CC Switch suit le principe d'intrusion minimale. Une fois le fournisseur activé, la configuration est écrite directement dans le fichier de configuration propre à Codex ; même si vous désinstallez CC Switch, Codex peut continuer à fonctionner normalement.

Les fichiers concernés sont les suivants. Dans les chemins, ~ désigne le répertoire de l'utilisateur actuel : sous Windows, C:\Users\<nom d'utilisateur>\ ; sous macOS et Linux, /Users/<nom d'utilisateur>/ ou /home/<nom d'utilisateur>/.

~/.codex/auth.json — stocke les identifiants :

{
        "OPENAI_API_KEY": "<API Key>"
      }

~/.codex/config.toml — stocke la configuration du modèle et de l'endpoint :

model_provider = "cliproxyapi"
      model = "gpt-5.6-sol"
      model_reasoning_effort = "max"
      sandbox_mode = "workspace-write"
      model_context_window = 372000
      model_auto_compact_token_limit = 334800
      model_auto_compact_token_limit_scope = "total"
      service_tier = "priority"
      
      [model_providers.cliproxyapi]
      name = "SeedRouter"
      base_url = "https://seedrouter.net/v1"
      wire_api = "responses"
      requires_openai_auth = true
      experimental_bearer_token = "sk-xxxxxxxxxx"

Les données de CC Switch lui-même sont stockées dans le répertoire ~/.cc-switch/. Le fichier de base de données est cc-switch.db, les sauvegardes automatiques se trouvent dans le sous-répertoire backups/, et les 10 plus récentes sont conservées.

Opérations de maintenance

Modifier la configuration

Pour modifier l'API Key, le nom du modèle ou l'adresse du service :

  1. Cliquez sur le bouton ＋, puis passez à l'onglet Unified Provider.

  2. Sur la carte cible, cliquez sur l'icône d'édition.

  3. Modifiez les champs correspondants.

    En mode édition, le bas du formulaire comporte la zone Config JSON Preview, qui permet de vérifier, avant la synchronisation, le contenu qui sera réellement écrit dans chaque application.

  4. Cliquez sur Save and Sync.

  5. Confirmez l'opération dans la boîte de dialogue de confirmation. Cette opération écrase la configuration des fournisseurs associés dans Claude, Codex et Gemini.

  6. Fermez le terminal, puis rouvrez-le.

Opérations sur les cartes de fournisseurs

Opération Description
Sync Renvoie manuellement la configuration actuelle vers chaque application associée, afin de corriger une configuration incohérente.
Copy Crée une copie à partir de la configuration actuelle, afin de configurer une clé de secours.
Edit Modifie le contenu de la configuration.
Delete Supprime le fournisseur unifié et supprime en même temps les cartes de fournisseurs associés générées dans Claude, Codex et Gemini.

Basculement rapide

Faites un clic droit sur l'icône CC Switch dans la zone de notification, puis cliquez directement sur le nom du fournisseur cible dans le sous-menu Codex pour basculer, sans ouvrir l'interface principale. Après le basculement, vous devez également redémarrer le terminal.

Dépannage

A. Réponse 401 ou 403 : échec de l'authentification

Cause possible Solution
La copie de l'API Key contient des espaces ou des sauts de ligne en trop Copiez-collez à nouveau, en faisant attention à la sélection
L'API Key a expiré ou le quota est épuisé Confirmez l'état de la clé auprès du fournisseur du service
L'API Key ne correspond pas à l'adresse de l'API Vérifiez que les deux proviennent du même service

B. Réponse 404, ou message indiquant que l'endpoint n'existe pas

Dans la plupart des cas, l'adresse de l'API est incorrecte après traitement. Revérifiez-la en vous reportant à « Tâche 4 > Règles de traitement de l'adresse de l'API », et confirmez l'adresse complète de l'endpoint auprès du fournisseur du service.

C. Aucun changement après modification de la configuration

Le terminal n'a pas été redémarré. Fermez complètement la fenêtre du terminal, puis rouvrez-la. C'est le problème le plus fréquent lors de l'utilisation de Codex.

D. Un avertissement de conflit de variables d'environnement s'affiche en haut de l'interface

Le système contient des variables d'environnement telles que OPENAI_API_KEY. Les variables d'environnement ont priorité sur les fichiers de configuration et écrasent la configuration écrite par CC Switch, ce qui envoie les requêtes vers le mauvais endpoint ou avec la mauvaise clé.

Marche à suivre :

  1. Cliquez sur Expand dans la bannière d'avertissement pour afficher le nom, la valeur et l'origine des variables en conflit.
  2. Cochez les variables à supprimer, ou cliquez sur Select All.
  3. Cliquez sur Delete Selected et confirmez.

Avant la suppression, CC Switch enregistre automatiquement une sauvegarde dans ~/.cc-switch/env-backups/. Pour restaurer, rétablissez manuellement le contenu à partir du fichier JSON de ce répertoire.

E. Le terminal indique que la commande codex n'existe pas

Cause possible Solution
Le terminal n'a pas été rouvert après l'installation Fermez toutes les fenêtres de terminal, puis rouvrez-les
Node.js n'est pas correctement installé Revenez à la tâche 1 et vérifiez que npm --version produit une sortie normale
Le répertoire global de npm n'est pas ajouté au PATH Réinstallez via Settings > About > Local Environment Check de CC Switch

F. La passerelle ne prend en charge que le protocole Chat Completions

Le protocole de communication du fournisseur unifié est fixé à Responses. Il ne s'applique pas à ce cas : vous devez utiliser un fournisseur spécifique à l'application.

  1. Dans CC Switch, passez au panneau Codex et cliquez sur le bouton ＋.
  2. Restez sur l'onglet Codex Provider à gauche, et ne passez pas au fournisseur unifié.
  3. Dans la liste déroulante des préréglages, sélectionnez le fournisseur correspondant. DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Bailian, ModelScope, SiliconFlow, Doubao Seed, Xiaomi MiMo, Novita AI, etc. sont tous des préréglages de type Chat Completions.
  4. Une fois ce type de préréglage sélectionné, CC Switch active automatiquement l'interrupteur « Requires Local Route Mapping » et configure la table de mapping des modèles. Le proxy local effectue la conversion de protocole, sans réglage manuel.
  5. Saisissez l'API Key, cliquez sur Add, puis activez ce fournisseur et redémarrez le terminal.

G. Revenir à la connexion par compte officiel

  1. Dans le panneau Codex, ajoutez un fournisseur à partir du préréglage « OpenAI Official ».
  2. Activez ce fournisseur et redémarrez le terminal.
  3. Terminez l'authentification en suivant la procédure de connexion propre à Codex.

Une fois cette opération terminée, vous pouvez basculer librement entre la connexion officielle et un fournisseur tiers.

Référence de choix : Unified Provider et App-specific Provider

Cas d'usage Solution recommandée
Un seul gateway sert simultanément Claude Code, Codex et Gemini CLI, et prend en charge le protocole Responses Unified Provider
Vous n'utilisez que l'outil Codex Les deux conviennent ; le chemin de configuration de l'App-specific Provider est plus court
Le gateway ne prend en charge que le protocole Chat Completions App-specific Provider, associé aux préréglages intégrés
Chaque outil se connecte à un prestataire différent App-specific Provider, à configurer chacun séparément
Vous devez configurer OpenCode, OpenClaw ou Hermes App-specific Provider : ces trois outils ne prennent pas en charge Unified Provider

Précautions de sécurité

  1. L'API Key a la même sensibilité que les identifiants du compte. Ne la transmettez pas dans des outils de messagerie instantanée, ne la partagez pas par capture d'écran et ne la soumettez pas à un dépôt de code.
  2. Obtenez le paquet d'installation de CC Switch uniquement depuis le site officiel de CC Switch ou le dépôt GitHub officiel.
  3. En cas de changement d'appareil ou de suspicion de fuite de la clé, remplacez-la immédiatement.
  4. La fonction d'export de configuration de CC Switch écrit l'ensemble des informations des fournisseurs en clair dans un fichier de sauvegarde .sql. Conservez soigneusement le fichier exporté et évitez de le placer dans un répertoire partagé.

Référence rapide

1. Installer Node.js  nodejs.org, choisir la version LTS
      2. Installer CC Switch           ccswitch.io ou GitHub Releases
      3. Installer Codex               CC Switch > Settings > About > Local Environment Check > Install
      4. Créer un Unified Provider     Passer au panneau Codex > ＋ > Unified Provider > Add Unified Provider
                                       Renseigner le nom, l'adresse API et l'API Key
                                       Activer le commutateur OpenAI Codex et renseigner le nom du modèle
      5. Activer le fournisseur        Panneau Codex > carte cible > Enable
      6. Redémarrer le terminal       Fermer complètement la fenêtre du terminal, puis la rouvrir
      7. Vérifier                      Exécuter la commande codex et envoyer un message de test

Lorsque vous signalez un problème, joignez une capture d'écran complète des informations d'erreur ainsi que l'adresse API renseignée à la tâche 4 (la partie clé doit être masquée), afin de raccourcir le délai de dépannage.

Obtenir une API Key SeedRouter Retour à l'accueil de la documentation