Comment configurer Codex config.toml : API personnalisée, proxy et erreurs courantes

Codex regroupe ses paramètres dans un seul fichier, config.toml : le modèle à utiliser, l’API à appeler et la marge de manœuvre laissée à l’agent sans demander votre accord. Le format a changé plusieurs fois en 2026, et de nombreux guides publiés plus tôt dans l’année présentent des paramètres qui empêchent désormais Codex de démarrer.

Ce guide commence par une configuration fonctionnelle, puis présente les éléments que la plupart des utilisateurs modifient : les profils, les paramètres de projet, le bac à sable et un proxy. À la fin, vous trouverez une liste des erreurs les plus probables et leur signification. Vérifié à partir de la documentation d’OpenAI et testé avec Codex CLI 0.162.1 le 19 octobre 2026. Les exemples utilisent AIHubMix comme fournisseur ; toute passerelle prenant en charge l’API OpenAI Responses fonctionne de la même manière.

En bref

• Le fichier est ~/.codex/config.toml, ou C:\Users\<you>\.codex\config.toml sous Windows.
• Un fournisseur personnalisé nécessite base_url, wire_api = "responses" et env_key. La clé API doit être stockée dans une variable d’environnement.
• Les profils sont désormais des fichiers distincts, ~/.codex/<name>.config.toml, sélectionnés avec --profile <name>.
• Le fichier .codex/config.toml d’un dépôt ne fonctionne que dans les projets de confiance et ne peut pas modifier le fournisseur.
• Redémarrez Codex après chaque modification ; il ne lit le fichier qu’au démarrage.

Emplacement de config.toml

Vos principaux paramètres se trouvent dans ~/.codex/config.toml. L’interface en ligne de commande et l’extension IDE le lisent toutes les deux. Si le fichier n’existe pas encore, créez-le.

Deux autres emplacements peuvent ajouter des paramètres :

• Fichiers de profil, ~/.codex/<name>.config.toml, utilisés uniquement si vous lancez Codex avec --profile <name>.
• Fichiers de projet, .codex/config.toml dans un dépôt, pour les paramètres qu’une équipe souhaite partager.

Si vous exécutez Codex dans WSL2 sous Windows, il lit le répertoire personnel Linux (/home/<you>/.codex/config.toml), et non celui de Windows. Si CODEX_HOME est défini, Codex utilise ce dossier à la place de ~/.codex.

Une configuration minimale fonctionnelle

Ce fichier ~/.codex/config.toml complet envoie les requêtes de Codex à AIHubMix :

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

• model est l’ID du modèle à appeler, et model_reasoning_effort définit son niveau de raisonnement par défaut.
• model_provider doit correspondre au nom indiqué dans [model_providers.<name>]. N’utilisez pas openai, ollama ou lmstudio : ces noms sont réservés aux fournisseurs intégrés à Codex.
• base_url est l’adresse API du fournisseur. wire_api = "responses" est désormais la seule valeur acceptée par Codex.
• env_key correspond au nom d’une variable d’environnement, pas à la clé elle-même.

Définissez ensuite cette variable avec une clé obtenue dans la console AIHubMix :

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

Lancez codex depuis un nouveau terminal et posez-lui une question. S’il répond, le fournisseur fonctionne. Le fait d’être connecté à Codex n’a aucune importance ici : la clé de codex login n’est jamais envoyée à un fournisseur personnalisé.

Profils : un fichier par configuration

Un profil ne contient que les paramètres qui diffèrent de votre configuration principale, par exemple un raisonnement plus approfondi et un bac à sable en lecture seule pour la révision de code. Chaque profil est un fichier distinct, placé à côté de config.toml, dont les clés sont définies à la racine :

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

Cela a changé avec Codex 0.134.0. Les anciens guides définissaient les profils dans config.toml, sous forme de tables [profiles.review], et en sélectionnaient un avec profile = "review". Codex refuse désormais de démarrer avec ce sélecteur. Une table [profiles.review] oubliée est simplement ignorée, sans aucun message, et ses paramètres cessent donc discrètement de fonctionner. Pour migrer, déplacez les clés de chaque table dans ~/.codex/<name>.config.toml, puis supprimez la table et la ligne profile = .... Consultez le guide de configuration avancée d’OpenAI pour plus de détails.

Configuration du projet : .codex/config.toml

Un fichier .codex/config.toml dans un dépôt permet à une équipe de partager un modèle par défaut, un niveau de raisonnement ou un mode de bac à sable. Codex ne le lit que dans les projets marqués comme fiables dans votre propre fichier ~/.codex/config.toml :

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Un fichier de projet ne peut pas modifier la destination des requêtes. Codex ignore model_provider, model_providers, openai_base_url, profile, notify et quelques autres clés à cet emplacement, et affiche un avertissement lorsqu’il le fait. Gardez votre fournisseur dans ~/.codex/config.toml. Un projet peut tout de même choisir le modèle ; la requête sera envoyée à votre propre fournisseur.

Quel paramètre l’emporte ?

Lorsque la même clé est définie à plusieurs endroits, les principes de base de la configuration d’OpenAI indiquent l’ordre de priorité suivant, du plus prioritaire au moins prioritaire :

1. Les options de la ligne de commande, y compris les redéfinitions -c
2. Le fichier .codex/config.toml du projet
3. Le profil sélectionné avec --profile
4. Votre fichier ~/.codex/config.toml
5. La configuration système, /etc/codex/config.toml
6. Les valeurs par défaut intégrées à Codex

Notez que le fichier de projet a priorité sur le profil. Si un paramètre de profil semble ne rien changer, vérifiez si le fichier .codex/config.toml du dépôt définit la même clé.

Pour modifier un paramètre pour une seule exécution, utilisez -c :

codex -c model_reasoning_effort=high

Bac à sable et autorisations

Deux clés déterminent ce que Codex peut faire de lui-même. sandbox_mode définit les ressources auxquelles ses commandes peuvent accéder, et approval_policy détermine quand il s’arrête pour vous demander votre accord.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

Ces deux paramètres sont indépendants : never supprime les demandes d’autorisation, mais n’assouplit pas le bac à sable. En mode workspace-write, les commandes ne peuvent pas accéder au réseau tant que vous n’avez pas défini network_access = true.

Derrière un proxy

Codex n’a pas de paramètre de proxy dans config.toml. Il utilise les variables d’environnement standard :

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

La documentation d’OpenAI ne les mentionne pas ; elles ont donc été testées avec Codex 0.162.1 : les requêtes, y compris celles adressées à un fournisseur personnalisé, passaient par HTTPS_PROXY (ou ALL_PROXY), tandis que les hôtes indiqués dans NO_PROXY étaient joints directement. Les fichiers PAC ne sont pas pris en charge ; indiquez donc directement l’adresse du proxy. Si le proxy de votre entreprise utilise son propre certificat racine, indiquez son chemin dans CODEX_CA_CERTIFICATE, comme expliqué dans la référence des variables d’environnement.

Plus de modèles dans /model

Le sélecteur /model ne répertorie que les modèles d’OpenAI. Pour y choisir des modèles GLM, Claude, Gemini ou DeepSeek, ajoutez un catalogue de modèles : un fichier JSON indiqué par une clé racine model_catalog_json. Placez cette clé avant la première ligne [table], faute de quoi TOML la considérera comme faisant partie de cette table et Codex l’ignorera.

Le catalogue remplace la liste intégrée et chaque entrée nécessite de nombreux champs ; mieux vaut donc le générer que le rédiger à la main. Le guide AIHubMix pour Codex CLI contient un script qui en crée un à partir des 30 modèles les plus utilisés sur AIHubMix. L’application de bureau peut encore masquer les modèles personnalisés dans son sélecteur (openai/codex#19694) ; changez donc de modèle dans le terminal.

Erreurs courantes et leur signification

Voici les messages affichés par Codex 0.162.1 pour chacune de ces erreurs.

legacy profile = "..." config is no longer supported
Votre fichier config.toml contient encore l’ancienne ligne profile = "...". Déplacez le profil dans son propre fichier, comme indiqué plus haut. Lancer --profile x alors qu’une ancienne table [profiles.x] existe produit une erreur similaire : --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
Codex ne prend plus en charge l’API Chat Completions. Remplacez cette valeur par wire_api = "responses". Un fournisseur qui ne propose que Chat Completions ne fonctionnera pas sans proxy de traduction.

model_providers contains reserved built-in provider IDs
Vous avez nommé votre fournisseur openai, ollama ou lmstudio. Renommez la table et model_provider.

approval_policy = "untrusted" is no longer supported
Supprimez la ligne ou utilisez on-request.

Missing environment variable: AIHUBMIX_API_KEY
La variable indiquée dans env_key n’est pas définie dans le terminal qui a lancé Codex. Ouvrez un nouveau terminal, ou exécutez source ~/.zshrc, puis relancez Codex.

401 Unauthorized after a few "Reconnecting..." lines
La requête a été envoyée sans clé. Vérifiez que la table du fournisseur contient env_key. Les identifiants enregistrés dans auth.json ne s’appliquent pas aux fournisseurs personnalisés.

Model metadata for ... not found. Defaulting to fallback metadata
Codex ne dispose pas de paramètres intégrés pour ce modèle, ce qui est normal pour les modèles autres que ceux d’OpenAI. Les requêtes fonctionnent tout de même. Ajoutez un catalogue de modèles pour disposer de paramètres adaptés et faire apparaître le modèle dans /model.

Ignored unsupported project-local config keys
Le fichier .codex/config.toml d’un dépôt définit une clé qui ne fonctionne que dans votre propre configuration, généralement model_provider. Déplacez-la dans ~/.codex/config.toml.

missing field base_instructions
Une entrée de votre catalogue de modèles ne contient pas un champ obligatoire ; Codex rejette donc l’ensemble du fichier. Régénérez le catalogue avec le script au lieu de le modifier à la main.

Quand un paramètre ne prend pas effet

• Redémarrez Codex après toute modification.
• Veillez à placer les clés racine avant la première ligne [table].
• Vérifiez le fichier .codex/config.toml du dépôt ; il a priorité sur votre profil.
• Vérifiez s’il reste une table [profiles.x].
• Exécutez codex doctor, qui vérifie votre installation, votre configuration et votre connexion.

Pour utiliser OpenAI, Anthropic, Google, Zhipu, DeepSeek et d’autres modèles dans Codex avec une seule clé, AIHubMix les fournit via l’API Responses à l’adresse https://aihubmix.com/v1. Commencez par la configuration minimale ci-dessus, puis ajoutez un catalogue de modèles si vous souhaitez changer de modèle depuis /model.

FAQ

Où se trouve le fichier config.toml de Codex ?
Dans ~/.codex/config.toml sous macOS et Linux, et dans C:\Users<you>.codex\config.toml sous Windows. Si CODEX_HOME est défini, le fichier se trouve plutôt dans ce dossier.

Dois-je redémarrer Codex après avoir modifié config.toml ?
Oui. Codex lit le fichier au démarrage : quittez puis rouvrez la session de terminal ou l’application.

Pourquoi Codex indique-t-il « la configuration des profils hérités n’est plus prise en charge » ?
Codex 0.134.0 a supprimé les profils définis dans config.toml. Déplacez chaque profil dans ~/.codex/name.config.toml, supprimez les anciennes lignes, puis lancez Codex avec --profile name.

Puis-je encore utiliser wire_api = "chat" ?
Non. Codex accepte uniquement wire_api = "responses". Un fournisseur qui ne prend en charge que Chat Completions nécessite un proxy qui traduit les requêtes vers l’API Responses.

Pourquoi mon fournisseur personnalisé renvoie-t-il une erreur 401 alors que je suis connecté à Codex ?
La clé de connexion de auth.json n’est pas envoyée aux fournisseurs personnalisés. Ajoutez env_key à la table du fournisseur et définissez cette variable dans votre terminal.

Codex utilise-t-il HTTPS_PROXY ?
Oui. Lors d’un test avec Codex 0.162.1, les requêtes passaient par HTTPS_PROXY et contournaient les hôtes répertoriés dans NO_PROXY. Les fichiers PAC ne sont pas pris en charge.

Pourquoi model_provider est-il ignoré dans le fichier .codex/config.toml de mon projet ?
Les fichiers de projet ne peuvent pas modifier la destination des requêtes : un dépôt ne peut donc pas rediriger votre trafic. Définissez le fournisseur dans ~/.codex/config.toml ; le fichier du projet peut toujours définir le modèle.

Sources

• Principes de base de la configuration, OpenAI
• Configuration avancée, OpenAI
• Référence de configuration, OpenAI
• Guide d’intégration de Codex CLI, AIHubMix
• Configuration d’un proxy pour Codex CLI : SOCKS, HTTP et réseaux d’entreprise, Daniel Vaughan