Comment utiliser Codex avec n'importe quel modèle open source (Mode OSS)

Codex est livré avec les modèles OpenAI par défaut, mais il ne vous y enferme pas. L'interface de ligne de commande (CLI) intègre un mode OSS (Open Source Software) pour les runtimes locaux comme Ollama et LM Studio, ainsi qu'un système de fournisseur personnalisé qui pointe l'agent vers n'importe quel point de terminaison compatible que vous définissez dans un fichier TOML. Cela signifie que vous pouvez exécuter gpt-oss sur votre ordinateur portable, piloter Codex avec une API DeepSeek ou Qwen hébergée, ou basculer entre les fournisseurs par projet.

Ce guide détaille toute la configuration : ce que fait le mode OSS, les clés de configuration exactes, les recettes par modèle, et les compromis que vous acceptez lorsque vous remplacez les modèles d'OpenAI. Tout ce qui suit provient de la documentation officielle de configuration avancée de Codex. Lorsque la documentation est ambiguë, je le signale au lieu de deviner.

Une remarque avant de commencer. Une fois que votre modèle fonctionne dans Codex, le modèle n'est que la moitié du processus. L'autre moitié consiste à vérifier les API que votre agent construit et appelle. C'est là qu'Apidog intervient, et nous aborderons l'association vers la fin.

En bref

Le mode OSS de Codex est une fonctionnalité de l'interface de ligne de commande (CLI). Exécutez codex --oss et Codex communique avec un serveur Ollama ou LM Studio local au lieu d'OpenAI. Définissez oss_provider = "ollama" dans ~/.codex/config.toml pour en faire la valeur par défaut, et passez -m <modèle> pour choisir quel modèle local exécuter. Pour les modèles open-source hébergés (DeepSeek, Qwen, GLM via leurs API), définissez un bloc [model_providers.<id>] avec une base_url et une env_key, puis sélectionnez-le avec model_provider. Le piège : la référence de configuration actuelle liste responses comme la seule valeur wire_api supportée, donc votre point de terminaison doit parler le protocole de l'API Responses.

Qu'est-ce que le mode OSS

Le mode OSS est le raccourci de Codex pour s'exécuter contre des serveurs de modèles open-source locaux. La documentation décrit deux fournisseurs locaux pris en charge :

• Ollama, le populaire runtime de modèle local
• LM Studio, l'application de bureau avec un serveur local intégré

Vous l'activez avec l'indicateur --oss. D'après la référence des commandes développeur Codex :

--oss : Utiliser un fournisseur de modèle open source local. Codex utilise --local-provider, votre oss_provider configuré, ou vous invite à choisir entre LM Studio et Ollama.

Il existe un indicateur complémentaire, --local-provider, qui prend lmstudio ou ollama et annule votre valeur par défaut pour une seule exécution. Si vous ne définissez ni un indicateur ni une valeur par défaut de configuration, l'interface CLI interactive vous invite à choisir. Le codex exec non interactif n'invite pas ; il se termine par une erreur. Donc, pour les scripts et l'intégration continue, définissez toujours le fournisseur explicitement.

Une note d'honnêteté sur les surfaces : la documentation couvre le mode OSS et les fournisseurs personnalisés dans le système config.toml de la CLI. L'extension IDE et le cloud Codex ne sont pas mentionnés comme supportant les fournisseurs locaux dans la documentation de configuration. [VÉRIFIER : si l'extension IDE de Codex lit les model_providers depuis config.toml de la même manière que la CLI ; la documentation ne le précise pas.] Traitez ceci comme un workflow CLI jusqu'à ce qu'OpenAI documente le contraire.

Pourquoi exécuter un modèle open-source dans Codex

Bonne question, puisque Codex est l'agent d'OpenAI. Quelques raisons concrètes :

• Contrôle des coûts. L'inférence locale via Ollama ne coûte rien par jeton. Si vous dépassez vos limites d'utilisation lors de longues sessions d'agent, un modèle local gère le gros du travail tandis que vous réservez les appels hébergés pour les problèmes difficiles.
• Confidentialité et travail en air gap. Certaines bases de code ne peuvent pas quitter la machine. Un modèle local Kimi, GLM ou gpt-oss conserve chaque jeton sur votre matériel. Notre guide pour exécuter Kimi K3 localement couvre ce que cela implique en pratique.
• Préférence de modèle. Les modèles à poids ouverts ont comblé la plupart de l'écart de codage. Les API hébergées de DeepSeek et Qwen sont moins chères que celles d'OpenAI tout en obtenant des scores comparables aux benchmarks de codage, et vous pourriez simplement aimer la façon dont un modèle spécifique écrit du code.
• Une seule interface d'agent, plusieurs modèles. L'expérience utilisateur du terminal, le sandboxing et le flux d'approbation de Codex sont bons. La configuration du fournisseur vous permet de conserver cette interface et de changer le cerveau.

Où se trouve la configuration

Codex stocke son état sous CODEX_HOME, qui est par défaut ~/.codex. Votre configuration au niveau de l'utilisateur est ~/.codex/config.toml, et un dépôt peut contenir des surcharges au niveau du projet dans .codex/config.toml. Tout ce qui suit va dans l'un de ces deux fichiers.

Démarrage rapide : Codex avec Ollama

Le chemin le plus rapide pour un modèle open-source dans Codex est Ollama.

1. Installez Ollama depuis ollama.com et démarrez-le. Il fournit une API compatible OpenAI sur le port 11434.
2. Téléchargez un modèle. La propre version open-weight d'OpenAI est un premier choix naturel ; la page de la bibliothèque gpt-oss propose les variantes 20b et 120b. Nous avons couvert la configuration autonome dans comment exécuter gpt-oss en utilisant Ollama.

ollama pull gpt-oss:20b

3. Exécutez Codex en mode OSS et nommez le modèle :

codex --oss -m gpt-oss:20b

L'indicateur -m/--model annule le modèle configuré, et combiné avec --oss il sélectionne quel modèle local exécuter. Pour une utilisation non interactive :

codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"

4. Faites-en la valeur par défaut pour pouvoir supprimer les drapeaux. Dans ~/.codex/config.toml :

# Fournisseur local par défaut utilisé avec `--oss`
oss_provider = "ollama" # ou "lmstudio"

C'est toute la fonctionnalité pour les modèles locaux. Pas de clé API, pas de bloc de fournisseur personnalisé. LM Studio fonctionne de la même manière : chargez un modèle dans l'application, démarrez son serveur local, et exécutez codex --oss --local-provider lmstudio. Voir lmstudio.ai pour la configuration du serveur.

Fournisseurs personnalisés : connectez Codex à n'importe quel point de terminaison compatible

Le mode OSS couvre Ollama et LM Studio. Pour tout le reste, les API DeepSeek ou Qwen hébergées, un proxy, un serveur vLLM sur votre réseau local, Codex dispose de fournisseurs de modèles personnalisés. La documentation définit un fournisseur comme "la façon dont Codex se connecte à un modèle (URL de base, API filaire, authentification et en-têtes HTTP optionnels)."

Le modèle de la documentation officielle :

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI utilisant le proxy LLM"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Les clés importantes :

Un réglage réseau par fournisseur est également disponible : request_max_retries (par défaut 4), stream_max_retries (par défaut 5), et stream_idle_timeout_ms (par défaut 300000). Les matériels locaux lents bénéficient d'un délai d'inactivité plus long, car un modèle 120b sur un ordinateur portable peut rester silencieux pendant un certain temps entre les jetons.

Deux règles sont directement mentionnées dans la documentation. Premièrement, les identifiants openai, ollama et lmstudio sont réservés ; vous ne pouvez pas écraser les fournisseurs intégrés. Pour changer l'URL de base du fournisseur OpenAI intégré, utilisez openai_base_url au lieu de créer [model_providers.openai]. Deuxièmement, et cela façonne tout : la référence de configuration stipule que pour wire_api, "responses est la seule valeur supportée, et c'est la valeur par défaut si omise."

C'est une réelle contrainte. Les versions précédentes de Codex acceptaient wire_api = "chat" pour les points de terminaison des Chat Completions, et la page d'aperçu des modèles indique toujours que vous pouvez pointer Codex vers des fournisseurs prenant en charge "soit les API Chat Completions, soit les API Responses". La référence et l'aperçu sont en désaccord. [VÉRIFIER : si wire_api = "chat" fonctionne toujours dans la version actuelle de la CLI ; la référence de configuration indique "responses-only", la page des modèles implique que "chat" fonctionne toujours. Tester sur un point de terminaison "chat-only" avant de publier.] Si "responses-only" est confirmé, votre fournisseur a besoin d'un point de terminaison de l'API Responses, ce que la plupart des serveurs compatibles OpenAI exposent maintenant, mais que certaines API hébergées ne font pas encore.

Recettes modèle par modèle

Chaque recette ci-dessous est un bloc de configuration plus la commande à exécuter. Définissez la variable d'environnement de la clé API avant le lancement.

DeepSeek (API hébergée)

DeepSeek a ajouté la prise en charge de l'API Responses parallèlement à sa bêta V4 Flash, ce qui correspond exactement à ce que le protocole filaire de Codex attend. Nous avons couvert ce déploiement dans DeepSeek V4 Flash, l'API Responses et Codex.

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

export DEEPSEEK_API_KEY="sk-..."
codex

Consultez la documentation de l'API DeepSeek pour les identifiants de modèle actuels. [VÉRIFIER : le chemin exact de la base_url que DeepSeek documente pour l'accès au protocole Responses ; le chemin /v1 chat peut différer du chemin Responses.]

Qwen (hébergé via Model Studio)

Model Studio (DashScope) d'Alibaba expose un mode compatible OpenAI pour la famille Qwen 3.8. Le point de terminaison du mode compatible a historiquement été de type Chat Completions. [VÉRIFIER : si le mode compatible de DashScope sert désormais le protocole Responses ; sinon, cette recette dépend de la question wire_api = "chat" ci-dessus.]

model = "qwen3.8-max"
model_provider = "qwen"

[model_providers.qwen]
name = "Qwen via Model Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

Notre guide de l'API Qwen 3.8 couvre les clés, les identifiants de modèle et les tarifs pour la route hébergée.

Kimi, GLM et autres modèles à poids ouverts (locaux via Ollama)

Tout ce que vous pouvez télécharger dans Ollama fonctionne via le mode OSS simple, aucun bloc de fournisseur n'est nécessaire :

ollama pull <modèle>
codex --oss -m <modèle>

Cela couvre les modèles GLM et Qwen à poids ouverts, ainsi que Kimi K3 si votre matériel le supporte (les poids de K3 sont de 594 Go en MXFP4, donc la plupart des gens devraient lire exécuter Kimi K3 localement avant d'essayer). Pour les machines de taille moyenne, gpt-oss:20b ou une version quantifiée de Qwen coder est le choix pratique.

vLLM auto-hébergé ou un serveur LAN

Un serveur vLLM ou similaire compatible OpenAI sur une autre machine est un fournisseur personnalisé, pas un mode OSS :

model_provider = "lan_vllm"

[model_providers.lan_vllm]
name = "vLLM sur le poste de travail"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"

Profils : changer de "cerveau" par tâche

Vous n'êtes pas obligé de choisir une seule configuration. Les profils Codex sont des fichiers TOML séparés à ~/.codex/<nom-du-profil>.config.toml, superposés à votre configuration de base lorsque vous passez --profile. Un profil de modèle local ressemble à ceci :

# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"

codex --profile oss-local
codex exec --profile oss-local "write unit tests for utils/dates.ts"

Gardez votre configuration par défaut sur les modèles OpenAI pour les refactorisations lourdes et lancez --profile oss-local pour les corrections de lint, l'échafaudage de tests et les passes de documentation. Les surcharges ponctuelles fonctionnent aussi sans profil : codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.

Compromis par rapport aux modèles OpenAI

Soyez honnête avec vous-même concernant ce que vous échangez :

• Capacité. gpt-oss:20b n'est pas gpt-5.6-terra. Les modèles locaux échouent plus souvent sur les longues modifications multi-fichiers, et les boucles d'agent amplifient la faiblesse du modèle car chaque étape s'appuie sur la précédente.
• Vitesse. Les API hébergées diffusent rapidement. Un grand modèle local sur du matériel grand public peut être suffisamment lent pour changer votre façon de travailler.
• Fidélité de l'outillage. Les invites et l'appel d'outils de Codex sont réglés pour les modèles OpenAI. Les modèles open-source varient dans la fiabilité avec laquelle ils émettent des appels d'outils, et le protocole filaire "responses-only" réduit le nombre de points de terminaison qualifiés.
• Surface de support. Le mode OSS est un chemin CLI documenté, mais les fournisseurs tiers sont de votre responsabilité : les identifiants de modèle, les limites de débit et les bizarreries de protocole sont entre vous et le fournisseur.

La répartition pragmatique : modèles locaux ou hébergés à bas coût pour les travaux à grand volume et à faible enjeu, modèles de pointe pour les tâches où un échec vous coûterait un après-midi.

Vérifiez les API que votre agent touche

Quel que soit le modèle exécuté dans Codex, le résultat est généralement du code qui appelle ou définit des API, et les modèles open-source hallucinent plus souvent des points de terminaison et des schémas que les modèles de pointe. Repérez cela au niveau de l'API au lieu de le faire en production.

Apidog couvre cet aspect du flux de travail. Pointez le serveur Apidog MCP vers votre projet et votre agent Codex pourra lire la spécification API réelle pendant qu'il écrit du code, au lieu d'inventer des noms de champs. Ensuite, utilisez Apidog CLI dans Codex pour permettre à l'agent d'exécuter vos scénarios de test depuis le terminal après chaque modification : il modifie, il teste, vous examinez un diff validé. Cette boucle est d'autant plus importante, et non moins, lorsqu'un modèle plus petit écrit le code. Téléchargez Apidog pour le connecter ; la CLI et le serveur MCP fonctionnent avec n'importe quel modèle que vous avez configuré.

Dépannage

• codex exec génère une erreur immédiatement en mode OSS. Vous n'avez pas défini de fournisseur. Les exécutions non interactives ne demandent jamais, donc passez --local-provider ollama ou définissez oss_provider dans la configuration.
• Connexion refusée sur le port 11434. Ollama ne fonctionne pas, ou il est lié à une adresse différente. Démarrez l'application ou ollama serve, et confirmez avec curl http://localhost:11434/v1/models.
• Erreurs 404 ou de protocole d'un fournisseur hébergé. Mauvaise forme de base_url, ou le point de terminaison ne parle pas le protocole Responses. Vérifiez si le fournisseur documente un chemin compatible Responses.
• Échecs d'authentification. env_key nomme une variable d'environnement ; Codex lit la clé de votre environnement shell au démarrage. Exportez-la dans le même shell, et rappelez-vous que les shells launchd ou CI peuvent ne pas charger vos fichiers de configuration.
• Les flux s'interrompent au milieu de la génération sur un modèle local lent. Augmentez stream_idle_timeout_ms et stream_max_retries dans le bloc du fournisseur.
• Modifications de configuration ignorées. Vérifiez la présence d'un .codex/config.toml au niveau du projet qui annule votre configuration utilisateur, et rappelez-vous que les profils se superposent aux deux.

FAQ

Le mode Codex OSS fonctionne-t-il dans l'extension IDE ou le cloud Codex ?

La documentation présente le mode OSS et les fournisseurs personnalisés comme faisant partie du système de configuration de la CLI. Le support IDE ou cloud pour les fournisseurs locaux n'est pas documenté, il faut donc considérer cela comme une fonctionnalité de la CLI. [VÉRIFIER avant de compter sur le support IDE.]

Quels modèles fonctionnent le mieux avec Codex en mode OSS ?

Tout ce qu'Ollama ou LM Studio peut servir sur votre matériel. gpt-oss:20b est le choix par défaut à faible friction. Les options de codage open-weight solides incluent la famille Qwen 3.8 et GLM ; pour les modèles géants comme Kimi K3, vérifiez d'abord les exigences matérielles dans notre guide Kimi K3 local.

Puis-je utiliser OpenRouter ou un autre agrégateur avec Codex ?

Tout agrégateur exposant un point de terminaison compatible correspond au modèle [model_providers.<id>] : définissez base_url et env_key, puis sélectionnez-le avec model_provider. La question ouverte est le protocole : la référence de configuration liste responses comme la seule wire_api supportée, alors confirmez que votre agrégateur sert l'API Responses.

Ai-je besoin d'une clé API OpenAI pour exécuter Codex avec un modèle open-source ?

Aucune clé n'est nécessaire pour le mode OSS avec un serveur Ollama ou LM Studio local. Les fournisseurs hébergés personnalisés utilisent leur propre clé via env_key. Vous vous connectez toujours à Codex lui-même comme d'habitude pour tout ce qui touche aux services d'OpenAI.

Exécutez la configuration qui correspond à la tâche. Un gpt-oss local pour les boucles bon marché, DeepSeek ou Qwen lorsque vous voulez une vitesse hébergée à moindre coût, et les modèles de pointe d'OpenAI lorsque le problème est difficile. La configuration de Codex rend les trois accessibles à un simple drapeau, et avec Apidog gérant la vérification côté API, le modèle devient une pièce interchangeable plutôt qu'un engagement.