Connecter des modèles externes à Codex

Ce guide présente deux méthodes d’intégration pour les modèles tiers hébergés :

Il convient d’abord de comprendre une limitation importante :

Ce guide s’applique aux clients Codex exécutés localement, notamment Codex CLI, l’extension Codex pour IDE et les clients de bureau qui lisent le même config.toml. À l’heure actuelle, les conversations Codex dans le cloud ne peuvent pas basculer vers un modèle personnalisé au moyen de cette configuration.

Avant de commencer

Installer ou mettre à jour Codex CLI

npm install -g @openai/codex@latest
codex --version

Après la première installation, exécutez Codex au moins une fois :

codex

Cette opération initialise le répertoire de configuration utilisateur.

Emplacements du fichier de configuration Codex

macOS et Linux :

~/.codex/config.toml

Windows :

%USERPROFILE%\.codex\config.toml

Sauvegardez le fichier avant d’apporter des modifications.

macOS / Linux :

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell :

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

Les fournisseurs, MCP et les passerelles de modèles sont différents

Ces concepts répondent à des besoins différents :

• model_provider détermine où Codex envoie les requêtes au modèle ;
• MCP ajoute des outils et du contexte, comme GitHub, des navigateurs ou des bases de données ;
• une passerelle de modèles assure la conversion de protocole, l’authentification, le routage, la journalisation ou la limitation du débit entre Codex et un modèle en amont.

Pour changer le modèle sous-jacent, configurez un fournisseur plutôt que MCP.

Protéger les API key

Ne validez pas de véritables API key dans un dépôt Git et n’affichez pas les clés complètes dans des captures d’écran, des journaux ou des tickets d’assistance.

Pour les fournisseurs configurés manuellement, privilégiez les variables d’environnement :

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch stocke localement la configuration des fournisseurs et modifie la configuration Codex locale lorsque vous changez de fournisseur. Il s’agit d’un outil open source tiers, et non d’un produit OpenAI. Installez-le uniquement depuis le site web officiel de CC Switch ou son dépôt GitHub, et protégez sa base de données locale, sa configuration et ses sauvegardes.

1. Connecter des modèles tiers avec CC Switch

CC Switch est l’option la plus simple pour la plupart des modèles tiers. Il gère les fournisseurs, les API key, les listes de modèles et le routage local, et peut traduire les protocoles en amont incompatibles.

1.1 Problèmes résolus par CC Switch

Les clients Codex modernes envoient des requêtes Responses API, tandis que de nombreux services tiers proposent l’un des éléments suivants :

• OpenAI Chat Completions ;
• Anthropic Messages ;
• des ID de modèles que Codex ne répertorie pas par défaut ;
• des paramètres de raisonnement ou des formats d’événements de streaming propres au fournisseur.

CC Switch peut convertir le chemin de la requête comme suit :

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Un fournisseur qui prend nativement en charge Responses n’a pas besoin de conversion du protocole Chat. Un fournisseur Chat Completions ou Anthropic Messages nécessite un routage local.

1.2 Installer CC Switch

Utilisez uniquement les canaux de distribution officiels :

• Site web officiel de CC Switch
• Dépôt GitHub de CC Switch
• Versions de CC Switch

Sur macOS, Homebrew est recommandé :

brew install --cask cc-switch

Pour effectuer une mise à jour :

brew upgrade --cask cc-switch

Sous Windows, téléchargez le programme d’installation .msi ou l’archive portable depuis Releases.

Sous Linux, téléchargez le paquet .deb, .rpm ou AppImage depuis Releases. Les libellés peuvent varier légèrement d’une version à l’autre : utilisez donc la dernière version stable et considérez les options affichées dans l’application comme faisant autorité.

1.3 Prérequis

Préparez les éléments suivants :

1. Codex est installé et a été lancé au moins une fois ;
2. CC Switch est installé et démarre correctement ;
3. vous disposez d’une API key pour le service de modèles cible ;
4. vous avez vérifié la Base URL, l’ID du modèle et le protocole en amont dans la documentation du fournisseur ;
5. si vous avez besoin des fonctionnalités officielles du compte Codex, effectuez d’abord une connexion officielle.

Vérifiez l’état actuel de connexion à Codex :

codex login status

Connectez-vous si nécessaire :

codex login

La connexion par code d’appareil est également disponible :

codex login --device-auth

1.4 Facultatif : conserver la connexion officielle lors de l’utilisation d’un fournisseur tiers

Cette option est principalement utile si vous souhaitez conserver les fonctionnalités de bureau, les plugins officiels ou les fonctions de contrôle à distance tout en envoyant les requêtes au modèle à un fournisseur tiers. Les utilisateurs de la CLI uniquement qui ne dépendent pas des fonctionnalités du compte officiel peuvent l’ignorer.

Ordre recommandé :

1. sélectionnez OpenAI Official dans le panneau Codex de CC Switch ;
2. lancez Codex et connectez-vous avec un compte officiel ;
3. ouvrez Settings → General → Codex App Enhancements dans CC Switch ;
4. activez Keep official login when switching third-party providers ;
5. ajoutez le fournisseur tiers ou basculez vers celui-ci.

Lorsque cette option est activée, CC Switch tente de conserver :

• ~/.codex/auth.json pour l’état de connexion officiel ;
• ~/.codex/config.toml pour le fournisseur tiers actif, le modèle, le point de terminaison et la configuration d’authentification.

auth.json contient des données de connexion sensibles. Ne le partagez pas et ne le validez pas dans le contrôle de version.

1.5 Ajouter un fournisseur tiers

Ouvrez CC Switch, accédez au panneau Codex de niveau supérieur, puis cliquez sur le bouton d’ajout dans l’angle supérieur droit.

Privilégier un préréglage intégré

Lorsqu’un préréglage existe, utilisez-le et saisissez uniquement l’API key ainsi que les éventuelles valeurs propres au compte. Un préréglage configure généralement :

• la Base URL ;
• le modèle par défaut ;
• le protocole en amont ;
• la nécessité ou non d’un routage local ;
• les correspondances de modèles ;
• certains paramètres de raisonnement.

La liste des préréglages évolue avec CC Switch. Une documentation pérenne ne doit pas coder en dur l’ID de modèle actuel d’un fournisseur ; utilisez la liste de l’application et la documentation officielle du fournisseur.

Créer un fournisseur personnalisé

Lorsqu’aucun préréglage n’est disponible, choisissez une configuration personnalisée et fournissez les informations suivantes :

Le paramètre le plus important est Upstream Format :

Ne sélectionnez pas Responses simplement parce qu’un fournisseur annonce une « compatibilité OpenAI ». De nombreuses API compatibles avec OpenAI implémentent uniquement Chat Completions.

1.6 Saisir correctement la Base URL

Par défaut, CC Switch ajoute le chemin d’API approprié à la Base URL. Dans la plupart des cas, saisissez la racine de l’API indiquée dans la documentation du fournisseur au lieu d’ajouter vous-même de nouveau /chat/completions ou /responses.

Par exemple, si le fournisseur indique :

POST https://api.example.com/v1/chat/completions

vous devrez peut-être saisir :

https://api.example.com

ou, selon le préréglage et la documentation du fournisseur :

https://api.example.com/v1

La présence de /v1 dans la Base URL dépend du fournisseur et du préréglage CC Switch. Utilisez le contrôle de connectivité intégré ou les journaux de routage pour confirmer l’URL finale de la requête.

Utilisez Full URL Mode uniquement lorsque le fournisseur exige le chemin complet d’un point de terminaison non standard.

1.7 Configurer Needs Local Routing et la correspondance des modèles

Activez Needs Local Routing lorsque le fournisseur utilise Chat Completions, Anthropic Messages ou des noms de modèles que Codex ne reconnaît pas par défaut.

Les préréglages orientés Chat l’activent généralement automatiquement. Vérifiez cette option pour les fournisseurs personnalisés.

Une fois l’option activée, une table de correspondance des modèles devient disponible. Les champs courants comprennent :

Points importants :

• utilisez l’ID de modèle exact indiqué dans la documentation du fournisseur ;
• ne devinez pas la taille de la fenêtre de contexte ;
• redémarrez Codex après avoir modifié la liste des modèles ;
• CC Switch génère le catalogue de modèles Codex à partir de ces correspondances ;
• si un relais modifie le domaine ou le nom du modèle, la détection automatique des capacités de raisonnement peut être erronée et doit être vérifiée dans les paramètres avancés.

1.8 Activer le routage local et la prise de contrôle de Codex

Dans CC Switch, ouvrez :

Settings → Routing → Local Routing

Ensuite :

1. activez l’interrupteur principal du routage local ;
2. activez Codex sous Routing Enabled ;
3. confirmez le paramètre Needs Local Routing du fournisseur ;
4. laissez CC Switch en cours d’exécution tant que le fournisseur est utilisé.

La route locale par défaut est généralement :

http://127.0.0.1:15721

Après la prise de contrôle, la configuration Codex active pointe vers la route locale de CC Switch. CC Switch transfère ensuite les requêtes au fournisseur en amont actuellement sélectionné.

Pour un service en amont Chat Completions, le flux est généralement le suivant :

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 Changer de fournisseur et redémarrer Codex

Revenez à la liste des fournisseurs Codex de CC Switch, sélectionnez le fournisseur que vous avez configuré et activez-le.

Redémarrez complètement Codex après le changement, car :

• Codex lit config.toml au démarrage ;
• le menu /model charge généralement son catalogue au démarrage ;
• l’extension IDE ou le client de bureau peut mettre en cache le fournisseur précédent ;
• les sessions existantes peuvent conserver les anciennes métadonnées du modèle.

Les utilisateurs de la CLI peuvent simplement démarrer un nouveau processus :

codex

1.10 Vérifier l’intégration

Dans Codex, exécutez :

/status

Vérifiez le modèle actif, le fournisseur, les autorisations et les informations de contexte.

Ouvrez le sélecteur de modèles :

/model

Inspectez les couches de configuration :

/debug-config

Vérifiez également :

• le fournisseur Codex actif dans CC Switch ;
• les journaux ou statistiques de routage local de CC Switch ;
• l’historique des requêtes et les variations de solde dans le tableau de bord du fournisseur ;
• si ~/.codex/config.toml pointe actuellement vers la route locale.

Ne validez pas la configuration avec une simple salutation. Exécutez au moins un test des capacités d’agent :

1. demandez à Codex de répertorier les fichiers du projet actuel ;
2. demandez-lui de lire et de résumer un fichier ;
3. demandez-lui de modifier un petit fichier ;
4. demandez-lui d’exécuter les tests ;
5. laissez une erreur simple en place et vérifiez qu’il peut utiliser le résultat du test pour poursuivre la correction du projet.

La génération de texte réussie ne prouve pas que les appels d’outils et les workflows d’agent en plusieurs tours sont compatibles.

1.11 Revenir au fournisseur OpenAI officiel

Sélectionnez OpenAI Official dans CC Switch et redémarrez Codex.

Vérifiez l’état de connexion :

codex login status

Si nécessaire, reconnectez-vous :

codex login

Si vous avez besoin à la fois de l’état de connexion officiel et des requêtes vers un modèle tiers, confirmez que l’option Keep official login when switching third-party providers reste activée.

1.12 Limitations et considérations opérationnelles

CC Switch simplifie la configuration, mais n’élimine pas les limitations du service en amont :

• CC Switch doit rester en cours d’exécution pour la conversion Chat ou Messages ;
• la conversion de protocole ne peut pas reproduire toutes les fonctionnalités propres à chaque fournisseur ;
• certains modèles peuvent converser, mais n’effectuent pas d’appels d’outils fiables ;
• Web Search, l’entrée d’images, WebSockets ou le stockage des réponses peuvent être indisponibles ;
• les limites de débit, la facturation et les politiques de conservation des données du fournisseur en amont continuent de s’appliquer ;
• un relais d’API peut de nouveau modifier les requêtes et les réponses ;
• les configurations doivent être retestées après toute mise à niveau de CC Switch, de Codex ou du fournisseur.

CC Switch convient particulièrement au développement local sur ordinateur. Pour les serveurs, la CI ou les automatisations headless de longue durée, privilégiez un fournisseur Responses natif ou une passerelle auto-hébergée.

2. Connecter une API hébergée avec un fournisseur de modèles personnalisé

Configurez directement un fournisseur uniquement lorsque le service prend nativement en charge la Responses API requise par Codex.

Si le service propose uniquement /chat/completions ou Anthropic Messages, utilisez le workflow CC Switch de la section 1. N’essayez pas de résoudre cette incompatibilité avec wire_api = "chat".

2.1 Capacités d’API requises

Un fournisseur adapté à une intégration directe avec Codex doit au minimum prendre en charge :

• POST /responses ;
• les objets JSON de Responses ;
• les événements de streaming SSE de Responses ;
• les appels de fonctions ou d’outils ;
• les paramètres d’outils JSON Schema ;
• la poursuite du traitement après le renvoi des résultats des outils ;
• les requêtes en plusieurs tours ou un équivalent de previous_response_id ;
• une fenêtre de contexte suffisante et des requêtes longues stables ;
• une documentation de l’authentification, des limites de débit et des réponses d’erreur.

La simple génération de texte ne suffit pas à garantir la fiabilité d’un agent Codex.

2.2 Configuration générique

Modifiez la configuration au niveau de l’utilisateur :

~/.codex/config.toml

Ajoutez :

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

N’utilisez pas ces ID de fournisseurs réservés :

openai
ollama
lmstudio

Utilisez plutôt un ID personnalisé tel que third_party ou company_gateway.

2.3 Champs de configuration

La présence de /v1 dans base_url dépend de la documentation du fournisseur. Un point de terminaison final courant est :

https://provider.example.com/v1/responses

2.4 Définir l’API key

Session bash / zsh actuelle :

export THIRD_PARTY_API_KEY="your API key"

fish :

set -gx THIRD_PARTY_API_KEY "your API key"

Session PowerShell actuelle :

$env:THIRD_PARTY_API_KEY = "your API key"

Pour la rendre persistante pour l’utilisateur Windows actuel :

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

Redémarrez le terminal, l’IDE ou le client de bureau après avoir défini une variable d’environnement persistante.

2.5 Tester d’abord le point de terminaison Responses

Avant de lancer Codex, appelez directement le fournisseur :

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

Vérifiez que :

• le point de terminaison ne renvoie pas 404 ;
• la réponse présente une structure de type Responses plutôt qu’un simple tableau choices de Chat Completions ;
• l’ID du modèle est accepté ;
• l’authentification est correcte ;
• les erreurs contiennent des informations de diagnostic utiles.

Testez ensuite séparément :

• stream: true ;
• les appels d’outils ;
• la poursuite du traitement avec les résultats des outils ;
• plusieurs tours ;
• les contextes longs ;
• la concurrence et les limites de débit.

2.6 Valider la configuration Codex

Démarrez en mode strict :

codex --strict-config

--strict-config traite les clés de configuration inconnues comme des erreurs, ce qui facilite l’identification des champs copiés depuis des guides obsolètes.

Dans Codex, exécutez :

/status

Pour inspecter les sources de configuration, exécutez :

/debug-config

Remplacez le fournisseur et le modèle pour une seule exécution sans modifier la configuration par défaut :

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 Catalogues de modèles et Unknown model

Un catalogue de modèles Codex peut décrire :

• la taille de la fenêtre de contexte ;
• les niveaux de raisonnement pris en charge ;
• les modalités d’entrée ;
• les capacités d’appel d’outils ;
• le comportement de troncature ;
• les versions minimales du client.

Lorsque le fournisseur propose un catalogue de modèles compatible avec Codex, enregistrez-le localement et configurez :

model_catalog_json = "~/.codex/provider-models.json"

Lorsqu’aucun catalogue n’existe, définissez une fenêtre de contexte uniquement après avoir confirmé sa valeur réelle :

model_context_window = 131072

Ne copiez pas les métadonnées d’un modèle sans rapport simplement pour supprimer un avertissement. Des métadonnées de capacité ou de contexte incorrectes peuvent entraîner une troncature prématurée, des erreurs de limite en amont ou des appels d’outils défaillants.

2.8 Liste de contrôle complète de la compatibilité

Avant une utilisation en production, testez :

• le texte /responses sans streaming ;
• le streaming SSE de Responses ;
• un appel d’outil ;
• plusieurs appels d’outils séquentiels ou parallèles ;
• les paramètres JSON Schema ;
• la poursuite du traitement avec les résultats des outils ;
• les contextes longs et la compaction automatique ;
• les paramètres de raisonnement ;
• les images ou autres modalités d’entrée ;
• les limites de débit et le comportement des nouvelles tentatives ;
• si un proxy met en mémoire tampon le flux SSE ;
• si le fournisseur supprime ou réécrit des champs d’outils ;
• les politiques de conservation des données, de journalisation et de confidentialité.

2.9 Emplacement de la configuration du fournisseur

Placez model_provider, model_providers et l’authentification du fournisseur dans le fichier au niveau de l’utilisateur :

~/.codex/config.toml

Ne les placez pas dans le fichier au niveau du dépôt :

<project>/.codex/config.toml

Codex ignore les champs locaux au projet susceptibles de rediriger les requêtes au modèle ou de modifier l’authentification du fournisseur. Cela empêche un dépôt non fiable que vous avez cloné de transférer silencieusement les requêtes vers un autre serveur.

3. Gérer plusieurs fournisseurs tiers avec des profils

Les utilisateurs de CC Switch peuvent généralement changer de fournisseur dans l’application et n’ont pas besoin des profils Codex.

Les profils sont utiles lorsque vous configurez manuellement plusieurs fournisseurs Responses natifs. Conservez les définitions des fournisseurs dans la configuration de base et utilisez des fichiers de profil distincts pour sélectionner un fournisseur et un modèle.

~/.codex/config.toml de base :

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

Créez :

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

Créez un autre profil :

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Sélectionnez un profil au lancement de Codex :

codex --profile fast
codex --profile quality

Mode non interactif :

codex exec --profile quality "Review the current changes"

Les fichiers de profil se trouvent dans :

$CODEX_HOME/<profile-name>.config.toml

Le CODEX_HOME par défaut est ~/.codex.

Les versions récentes de Codex utilisent des fichiers de profil distincts et ne lisent plus les anciennes tables [profiles.<name>]. Migrez chaque ancien profil dans son propre fichier <name>.config.toml.

4. En-têtes personnalisés et authentification avancée

4.1 Jetons bearer standard

La plupart des services tiers fonctionnent avec :

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex lit la clé depuis l’environnement et applique l’authentification bearer du fournisseur.

4.2 En-têtes d’API key personnalisés

Certains services exigent :

x-api-key: <key>

Utilisez env_http_headers :

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

La valeur VENDOR_API_KEY est le nom d’une variable d’environnement, et non le secret lui-même.

export VENDOR_API_KEY="your API key"

4.3 En-têtes statiques et paramètres de requête

Ajoutez des en-têtes statiques non sensibles :

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

Ajoutez des paramètres de requête :

query_params = { "api-version" = "2026-08-01" }

Ne placez pas de véritables secrets dans http_headers.

4.4 Authentification reposant sur une commande

Un environnement d’entreprise peut obtenir des jetons de courte durée auprès d’un trousseau, d’un assistant d’identification cloud ou d’une commande interne :

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

La commande doit écrire uniquement le jeton dans la sortie standard.

Ne combinez pas ces méthodes d’authentification :

• [model_providers.<id>.auth] ;
• env_key ;
• experimental_bearer_token ;
• requires_openai_auth.

4.5 Réutiliser l’authentification OpenAI via un proxy

Définissez le paramètre suivant uniquement lorsque le proxy accède toujours à des modèles OpenAI et que Codex doit utiliser l’authentification OpenAI officielle :

requires_openai_auth = true

Ce paramètre ne convient pas à une API key normale de modèle tiers. Lorsqu’il est activé, Codex ignore le env_key du fournisseur.

5. Résolution des problèmes

5.1 CC Switch change de fournisseur, mais Codex utilise toujours l’ancien modèle

Vérifiez chaque élément :

1. le fournisseur Codex souhaité est activé dans CC Switch ;
2. l’interrupteur principal du routage local est activé ;
3. Codex est activé sous Routing Enabled ;
4. Needs Local Routing est activé pour les fournisseurs Chat ou Messages ;
5. CC Switch est toujours en cours d’exécution ;
6. Codex, l’IDE ou le client de bureau a été entièrement redémarré ;
7. /debug-config affiche la source de configuration attendue.

Redémarrez Codex après avoir modifié les correspondances de modèles afin que le menu /model puisse recharger son catalogue.

5.2 404, 400 ou point de terminaison /responses manquant

Les causes courantes comprennent :

• le traitement d’un fournisseur Chat Completions comme un fournisseur Responses natif ;
• l’ajout ou la suppression incorrecte de /v1 ;
• l’ajout de /chat/completions à deux reprises ;
• l’absence d’activation de Full URL Mode pour un point de terminaison non standard ;
• la prise de contrôle de Codex par le routage local qui ne s’effectue pas ;
• une implémentation incomplète de Responses dans la passerelle tierce.

Les utilisateurs de CC Switch doivent inspecter Upstream Format et les journaux de routage. Les utilisateurs d’un fournisseur direct doivent appeler <base_url>/responses avec curl.

5.3 401 Unauthorized ou 403 Forbidden

Vérifiez :

• si l’API key est valide ;
• si elle correspond à la bonne région, au bon projet ou à la bonne offre ;
• si le compte dispose d’un solde et d’autorisations suffisants ;
• si le service attend un jeton bearer ou x-api-key ;
• si le nom de la variable d’environnement correspond exactement à env_key ;
• si CC Switch a enregistré la bonne clé ;
• si un proxy a supprimé l’en-tête d’authentification.

N’écrivez pas une clé complète dans des journaux partagés.

bash / zsh :

printenv THIRD_PARTY_API_KEY

PowerShell :

$env:THIRD_PARTY_API_KEY

5.4 Le modèle ne figure pas dans /model

Vérifiez :

• si Model Mapping dans CC Switch contient l’ID exact du modèle en amont ;
• si le fournisseur a été enregistré et activé ;
• si Codex a été redémarré ;
• si un fournisseur manuel dispose d’un model_catalog_json valide ;
• si le JSON du catalogue est valide ;
• si le fournisseur a renommé ou retiré le modèle.

5.5 Le texte fonctionne, mais Codex ne peut ni lire des fichiers, ni modifier du code, ni exécuter des commandes

Causes possibles :

• le modèle maîtrise mal les appels d’outils ;
• le service en amont n’implémente pas les appels de fonctions ;
• un relais supprime les ID des appels d’outils ;
• les fragments d’appels d’outils en streaming ne sont pas réassemblés correctement ;
• JSON Schema est réécrit ;
• les résultats des outils ne sont pas renvoyés au tour suivant ;
• le contexte du modèle est trop court ;
• le catalogue de modèles annonce des capacités incorrectes.

Testez une véritable boucle « lire → modifier → exécuter les tests → examiner l’échec → corriger » plutôt qu’une simple invite de conversation.

5.6 Le streaming se déconnecte fréquemment

Les utilisateurs de CC Switch doivent d’abord inspecter les journaux de routage local et les réponses en amont. Les causes courantes comprennent :

• la mise en file d’attente en amont ou une longue durée de raisonnement ;
• une passerelle qui n’émet pas rapidement les événements SSE ;
• la mise en mémoire tampon par un CDN, un proxy inverse ou le réseau de l’entreprise ;
• des événements en amont non standard ;
• des problèmes de compatibilité dans une version donnée de CC Switch ou du fournisseur.

Pour un fournisseur direct, vous pouvez augmenter :

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

Des délais d’expiration plus longs peuvent atténuer les problèmes de réseau ou d’inférence lente, mais ils ne peuvent pas corriger une implémentation de protocole incorrecte.

5.7 wire_api = "chat" empêche Codex de démarrer

Cette valeur figure dans d’anciens guides. La configuration Codex actuelle prend uniquement en charge :

wire_api = "responses"

Utilisez CC Switch lorsque le service en amont propose uniquement Chat Completions.

Recherchez d’autres champs obsolètes avec :

codex --strict-config

5.8 La modification de la configuration du projet ne change pas le fournisseur

Les paramètres du fournisseur doivent se trouver dans :

~/.codex/config.toml

Un .codex/config.toml au niveau du projet ne peut pas remplacer les champs qui redirigent les requêtes ou modifient l’authentification du fournisseur, notamment model_provider et model_providers.

5.9 Le terminal fonctionne, mais l’extension IDE ne trouve pas l’API key

Les applications graphiques n’héritent souvent pas des variables exportées temporairement dans un terminal existant.

Vous pouvez notamment :

• lancer l’IDE depuis le terminal dans lequel la variable est définie ;
• rendre la variable persistante dans l’environnement utilisateur du système d’exploitation ;
• quitter complètement l’IDE, puis le rouvrir ;
• utiliser CC Switch pour gérer la configuration locale du fournisseur.

5.10 La connexion officielle ou des fonctionnalités officielles cessent de fonctionner après un changement

Vérifiez :

• si OpenAI Official a de nouveau été sélectionné ;
• si Keep official login when switching third-party providers est activé ;
• si un ancien workflow a remplacé ~/.codex/auth.json ;
• si codex login status réussit.

Si nécessaire, reconnectez-vous :

codex login

Ne partagez pas et ne modifiez pas manuellement un fichier auth.json contenant des jetons d’accès.

5.11 Web Search, les images ou d’autres capacités avancées ne fonctionnent pas

Un fournisseur qui prend en charge le texte et les appels d’outils n’implémente pas nécessairement toutes les capacités de Codex.

Les fournisseurs personnalisés n’annoncent pas Web Search de façon autonome par défaut. Définissez le paramètre suivant uniquement lorsque le fournisseur, le modèle et le point de terminaison le prennent réellement en charge :

supports_standalone_web_search = true

Une activation incorrecte conduit seulement Codex à envoyer des requêtes que le service en amont ne peut pas traiter. Validez séparément l’entrée d’images, WebSockets, le stockage des réponses et les autres fonctionnalités avancées.

6. Choisir une méthode d’intégration

Validez chaque intégration à trois niveaux :

1. Connectivité : elle renvoie du texte de manière fiable ;
2. Utilisation des outils : elle peut lire des fichiers, exécuter des commandes et poursuivre le traitement à partir des résultats des outils ;
3. Réalisation des tâches : elle peut mener à bien une boucle de modification, de test et de correction.

Examinez également :

• la tarification du tiers ;
• les limites de débit ;
• si le code source et les invites sont journalisés ;
• les régions de stockage des données ;
• les exigences de conformité de l’équipe ou de l’entreprise ;
• si les mises à niveau du modèle nécessitent des tests de régression.

Lorsque vous utilisez une API key tierce, l’utilisation est facturée par ce fournisseur ou relais. Elle ne consomme ni ne partage automatiquement les quotas inclus avec ChatGPT Plus, Pro ou un abonnement Codex.

Références

• Principes de base de la configuration de Codex
• Configuration avancée de Codex
• Référence de la configuration de Codex
• Authentification de Codex
• Commandes de développement de Codex
• Modèles Codex
• CC Switch sur GitHub
• Manuel d’utilisation de CC Switch
• CC Switch : ajouter un fournisseur
• CC Switch : conserver la connexion officielle à Codex