Configuration de Codex trop compliquée ? Utilisez un Provider pour simplifier l’intégration des modèles

L’installation de Codex n’est pas difficile, ce qui bloque vraiment facilement est l’intégration : où placer l’API Key, comment écrire config.toml, quelles sont les différences entre Windows et macOS, pourquoi VS Code ne peut pas lire les variables du terminal, s’il faut fixer le modèle…

Si vous voulez seulement faire fonctionner Codex le plus vite possible, vous pouvez réduire la configuration à trois valeurs :

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

Une fois terminé, Codex CLI, Desktop et l’extension VS Code peuvent partager ~/.codex/config.toml, tandis que le modèle est directement sélectionné après le démarrage, sans devoir modifier continuellement la configuration d’intégration pour changer de modèle.

Ci-dessous, nous allons terminer une configuration à partir de zéro.

¶ Préparatifs

Avant de commencer, veuillez confirmer :

Vous êtes inscrit et connecté à Ace Data Cloud
Vous avez créé ou possédez une application utilisable
Node.js et npm sont installés sur votre machine
Vous pouvez utiliser le terminal ou PowerShell
Vous prévoyez d’utiliser au moins l’un parmi Codex CLI, Codex Desktop ou l’extension VS Code

¶ Première étape : obtenir l’API Key Ace Data Cloud

Ouvrez la liste des applications Ace Data Cloud, entrez dans une application utilisable et copiez l’API Key.

Veuillez noter :

L’API Key est un identifiant sensible, ne l’écrivez pas dans un dépôt public
Ne placez pas de vraie Key dans les captures d’écran de tutoriels
Il est recommandé de créer et gérer séparément les identifiants selon l’environnement ou l’usage
En cas de suspicion de fuite, vous devez rapidement la renouveler ou la révoquer

Cet article utilise uniformément la variable d’environnement ACEDATACLOUD_API_KEY, afin d’éviter d’écrire directement des identifiants en clair dans le fichier de configuration Codex.

¶ Deuxième étape : installer Codex CLI

Installez Codex globalement avec npm :

npm install -g @openai/codex

Vérifiez après l’installation :

codex --version

Si un message indique que la commande est introuvable, confirmez d’abord que le répertoire des exécutables globaux npm a été ajouté à PATH, puis rouvrez le terminal.

Si vous utilisez principalement VS Code, vous pouvez également installer l’extension Codex publiée par OpenAI :

code --install-extension openai.chatgpt

Le CLI et l’extension VS Code partagent le fichier de configuration, il est donc recommandé de configurer d’abord le Provider et les variables d’environnement, puis de lancer l’éditeur pour vérifier.

¶ Troisième étape : définir la variable d’environnement de l’API Key

¶ macOS / Linux : session de terminal actuelle

export ACEDATACLOUD_API_KEY="你的 API Key"

Cette commande ne prend effet que pour le Shell actuel et ses processus enfants. La variable disparaîtra après la fermeture du terminal.

¶ macOS / Linux : effet à long terme

Si vous utilisez Zsh :

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

Si vous utilisez Bash :

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

Ne copiez pas aveuglément sur un ordinateur partagé une configuration Shell contenant une vraie Key ; l’environnement d’équipe doit associer des outils de gestion des identifiants et une politique de moindre privilège.

¶ Windows PowerShell

setx ACEDATACLOUD_API_KEY "你的 API Key"

Fermez puis rouvrez PowerShell après l’exécution. setx ne met pas automatiquement à jour les processus déjà ouverts, donc le terminal existant et VS Code peuvent encore ne pas pouvoir lire la nouvelle valeur.

Si vous devez la définir temporairement seulement dans la session PowerShell actuelle :

$env:ACEDATACLOUD_API_KEY="你的 API Key"

¶ Quatrième étape : créer ou modifier config.toml

Codex CLI, Desktop et l’extension VS Code partagent le fichier de configuration suivant :

macOS / Linux : ~/.codex/config.toml
Windows : %USERPROFILE%\.codex\config.toml

Si le répertoire n’existe pas, créez-le d’abord.

macOS / Linux :

mkdir -p ~/.codex

Écrivez ensuite :

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows utilise le même Provider et la même Base URL, mais la commande d’authentification devient PowerShell :

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

Les trois noms dans la configuration doivent rester strictement identiques :

model_provider = "acedatacloud"
[model_providers.acedatacloud]
[model_providers.acedatacloud.auth]

La Base URL doit également inclure intégralement /v1.

¶ Cinquième étape : démarrer Codex et sélectionner un modèle

Après avoir enregistré la configuration, rouvrez le terminal et exécutez :

codex

Après être entré dans Codex, exécutez :

/model

Confirmez que le Provider actuel est acedatacloud, puis sélectionnez un modèle dans la liste disponible.

Il n’est pas nécessaire de fixer model dans la configuration d’intégration. Séparer le Provider et la sélection du modèle peut réduire le coût de modification répétée du TOML lors du changement de modèle. Les modèles réels et les plages disponibles seront mis à jour ; vous devez vous référer à /model et au catalogue en temps réel de la plateforme.

¶ Sixième étape : vérifier avec une requête minimale

Ne demandez pas dès le début à Codex de refactoriser tout le dépôt. Envoyez d’abord une requête simple dont le résultat peut être rapidement évalué, par exemple :

请概括当前项目的目录结构，不要修改任何文件。

Ouvrez ensuite Ace Data Cloud Usage History, confirmez que la requête est arrivée, puis consultez le statut et la consommation.

Si la requête minimale réussit, essayez ensuite progressivement de lire des fichiers, générer des propositions de modification, éditer du code et exécuter des tests.

¶ Points clés de configuration VS Code

L’extension VS Code lit le même ~/.codex/config.toml, mais sa capacité à voir l’API Key dépend de l’environnement du processus dans lequel l’extension s’exécute.

Après la configuration, quittez complètement puis rouvrez VS Code. Sous macOS / Linux, si la variable ne peut toujours pas être lue après un lancement depuis l’interface graphique, vous pouvez exécuter depuis un terminal où la Key a déjà été définie :

code .

Dans les environnements suivants, vous devez configurer la variable du côté où l’extension s’exécute réellement :

Remote SSH : hôte distant
WSL : environnement Linux WSL
Dev Container : environnement du conteneur
Codespaces ou environnement distant similaire : session distante correspondante

Définir la variable uniquement dans le Shell local ne garantit pas que l’extension distante l’obtiendra automatiquement.

¶ Points clés de configuration Codex Desktop

Desktop et le CLI partagent le fichier de configuration, mais une application graphique n’hérite pas nécessairement d’un export exécuté temporairement dans le terminal.

Si Desktop ne peut pas lire la Key :

Définissez la variable d’environnement à long terme ou au niveau système
Quittez complètement Desktop
Redémarrez l’application
Vérifiez à nouveau le Provider et le modèle

¶ Dépannage des erreurs courantes

¶ 1. 401, Unauthorized ou Incorrect API Key

Ordre de vérification :

Vérifiez si l’API Key a été copiée intégralement
Vérifiez si le nom de la variable d’environnement est ACEDATACLOUD_API_KEY
Vérifiez si le processus actuel a été démarré après la définition de la variable
Vérifiez si auth.command correspond au système d’exploitation actuel
Vérifiez si l’identifiant est toujours valide Ne mettez pas la Key complète dans les journaux ou les conversations. Vous pouvez vérifier la variable uniquement en déterminant si elle « existe ».

macOS / Linux：

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell：

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

¶ 2. Le Provider ne devient pas acedatacloud

Confirmez le chemin du fichier de configuration et la hiérarchie TOML. Les erreurs courantes incluent :

Le nom du fichier est écrit comme config.toml.txt
Un autre répertoire utilisateur a été modifié
Les noms de tables ne correspondent pas
Les guillemets ou le format des tableaux sont incorrects
Le client n’a pas été redémarré après l’enregistrement

¶ 3. L’appel de la Base URL échoue

Confirmez que l’adresse est :

https://api.acedata.cloud/v1

N’omettez pas https:// ou le /v1 final, et n’utilisez pas par erreur l’adresse de la page de la console.

¶ 4. La CLI fonctionne, mais VS Code ne fonctionne pas

Il ne s’agit généralement pas d’un problème de configuration du Provider, mais du fait que le processus VS Code n’a pas lu la variable d’environnement. Lancez code . depuis un terminal où la variable est définie, ou redémarrez complètement VS Code après avoir configuré une variable au niveau du système.

¶ 5. Impossible de lire la Key dans WSL, SSH ou un conteneur

La variable d’environnement doit être définie dans l’environnement où Codex ou l’extension s’exécute réellement. setx sur l’hôte Windows ne sera pas automatiquement écrit dans WSL ; les variables locales ne seront pas non plus automatiquement transmises à un hôte SSH distant ou à un conteneur.

¶ 6. Impossible de trouver le modèle que vous souhaitez utiliser

Ne devinez pas manuellement les anciens ID de modèles. Exécutez /model pour voir les options disponibles en temps réel, et vérifiez les autorisations de l’application, le solde et le Provider actuel.

¶ 7. La requête arrive, mais les tâches complexes ne peuvent pas être terminées

Commencez par réduire la portée de la tâche : demandez à Codex d’effectuer uniquement une analyse en lecture seule, de produire un plan, puis autorisez progressivement les modifications et les tests. Une intégration réussie du modèle ne signifie pas que toutes les tâches du dépôt doivent être terminées en une seule fois ; les modifications complexes nécessitent toujours des critères d’acceptation clairs, des tests et une revue humaine.

¶ Liste de contrôle de configuration recommandée

Avant de soumettre la première tâche officielle, confirmez chaque élément :

¶ Un Provider, moins de configurations répétées

L’objectif de cette méthode d’intégration n’est pas d’écrire un segment TOML supplémentaire, mais d’établir des limites stables :

L’API Key est gérée par des variables d’environnement
La connexion au Provider est gérée par config.toml
Les modèles sont sélectionnés dans Codex selon la tâche
Les enregistrements d’appel et la consommation sont consultés de manière centralisée dans la console Ace Data Cloud
La CLI, Desktop et VS Code partagent une même configuration

Lorsque l’authentification, le Provider et la sélection du modèle sont clairement séparés, de nombreux problèmes du type « pourquoi Codex ne fonctionne-t-il encore pas » peuvent être rapidement localisés, sans devoir se reconnecter à répétition, réinstaller ou copier plusieurs configurations.

Ouvrez le centre de configuration Codex pour consulter les guides officiels des différents clients, ou accédez à la liste des applications pour obtenir une API Key.