Clé API de la CLI Codex — la configuration fonctionnelle avec un fournisseur personnalisé

Une clé API Codex est toute clé avec laquelle Codex CLI peut facturer par token au lieu d'un forfait ChatGPT : une clé API OpenAI provenant de platform.openai.com, ou une clé fournisseur telle que sk-kn- de Kunavo, que Codex lit depuis la variable d'environnement indiquée par env_key dans un bloc model_providers. Le fournisseur doit exposer l'API Responses — c'est l'unique exigence ci-dessous.

Codex CLI est l'agent de codage open source en terminal d'OpenAI ; il fonctionne avec une connexion ChatGPT ou une clé API. La route par clé API est celle qu'il faut comprendre : elle facture par token sans frais mensuels et c'est la seule route qui vous permet de pointer la CLI vers un autre fournisseur — ou vers une famille de modèles entièrement différente. Ce guide présente la configuration opérationnelle, l'unique exigence qui pose problème à la plupart des passerelles et le coût réel d'une session.

L'unique exigence importante

Codex CLI est plus strict que la plupart des outils concernant les endpoints personnalisés. Son bloc model_providers contient une clé wire_api et n'accepte qu'une seule valeur : responses. Cela signifie qu'un fournisseur personnalisé doit exposer l'API Responses d'OpenAI à l'adresse POST /v1/responses — et non l'endpoint beaucoup plus courant /v1/chat/completions. La plupart des passerelles compatibles OpenAI ne proposent que ce dernier, ce qui explique pourquoi tant d'entre elles ne peuvent pas piloter Codex CLI, quelle que soit la valeur de base_url que vous lui fournissez.

Kunavo expose les deux surfaces, le fichier de configuration ci-dessous fonctionne donc tel quel.

La configuration

Codex lit ~/.codex/config.toml. Deux clés de premier niveau sélectionnent le modèle et le fournisseur ; le bloc du fournisseur décrit la manière de le joindre :

# ~/.codex/config.toml
model          = "gpt-5-6-sol"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

Notez ce qui n'est pas présent dans ce fichier : la clé elle-même. env_key désigne une variable d'environnement, et Codex lit la clé dans cette variable au lancement — le fichier de configuration peut donc être validé dans le dépôt ou partagé sans risque.

# Codex reads the key from the variable named by env_key.
export KUNAVO_API_KEY="sk-kn-..."     # create at kunavo.com/app/keys

# Persist it (pick the file your shell actually loads):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explain the structure of this repository"

Créez la clé dans le tableau de bord après vous être inscrit et avoir rechargé 10 $. Elle n'est affichée qu'une seule fois, enregistrez-la donc immédiatement. Si codex fonctionnait déjà dans un autre shell, redémarrez-le — il lit la variable au lancement, et non à chaque requête.

Vérifiez avant de déboguer

En cas de problème, déterminez s'il vient de la clé, de l'endpoint ou de la CLI. Une seule requête suffit :

# Confirm the key and the endpoint before blaming Codex.
curl https://api.kunavo.com/v1/responses \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-sol",
    "input": "Say OK and nothing else."
  }'

Une réponse JSON signifie que la clé et l'endpoint sont corrects et que tout problème restant se trouve dans config.toml. Une erreur 401 signifie que la clé est incorrecte ou que la variable est vide dans ce shell. Une erreur 404 sur model signifie que le slug ne correspond pas au catalogue.

Quel modèle définir

La valeur de model est simplement un slug sur le même endpoint ; changer de modèle revient donc à modifier un seul mot — aucune nouvelle clé, aucun nouveau bloc fournisseur.

gpt-5-6-sol est le GPT optimisé pour le codage et le choix par défaut naturel pour cette CLI, à $2.00 / $12.00 par million de tokens, contre $5.00 / $30.00 — OpenAI facture toutefois actuellement un tarif promotionnel de $4.00 / $20.00, disponible au moins jusqu’au 21 novembre 2026 au tarif catalogue d’OpenAI. Les tarifs complets de chaque modèle figurent sur la page des tarifs.

Exécuter des modèles Claude dans Codex CLI

Cela surprend : Codex CLI est lié au protocole, pas au modèle. Il utilise le format filaire Responses, et le modèle conversationnel situé derrière ce point de terminaison répond. Dirigez-le vers claude-opus-5 et il fonctionne de bout en bout — y compris les appels d’outils ; l’agent continue donc à lire les fichiers, proposer des modifications et exécuter des commandes normalement.

# Same provider block, different model — no new key, no new config.
model          = "claude-opus-5"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

La passerelle traduit la requête Responses en API Anthropic Messages, puis reconvertit la réponse au format Responses. Une réserve importante : Codex envoie des éléments opaques reasoning qu’un modèle natif de Responses est le seul à pouvoir consommer, et ceux-ci sont supprimés avant d’atteindre un fournisseur amont non-GPT. Le modèle perd son bloc-notes privé de la conversation précédente ; la transcription visible sur laquelle il travaille reste intacte. En pratique, cela réduit légèrement la continuité lors des longues chaînes de raisonnement, mais n’a aucun effet sur les boucles ordinaires modification-exécution-correction.

La question de savoir si c’est une bonne idée est distincte de celle de savoir si cela fonctionne. Si vous voulez spécifiquement Claude, Claude Code est conçu pour cela et transmet cache_control sans traduction. Mais si vous préférez le bac à sable de Codex CLI et souhaitez l’utiliser avec Claude, cette combinaison est disponible.

Coût d’une session

Les CLI agentiques renvoient l’invite système, l’historique de la tâche et le nouveau contexte des fichiers à chaque étape ; les tokens s’accumulent donc plus vite que ne le laisse penser le nombre d’étapes. Une étape typique représente environ 25 000 tokens en entrée et 1 200 en sortie :

Comme les tarifs de sortie diffèrent bien davantage entre les familles de modèles que ceux d’entrée, les tâches riches en sorties modifient le classement — saisissez vos propres chiffres dans le calculateur de coûts plutôt que de vous fier à un seul exemple détaillé. Les requêtes échouées ne sont pas facturées.

Quand la clé API est plus avantageuse qu’un abonnement

Un forfait ChatGPT inclut l’utilisation de Codex à un tarif mensuel fixe ; une clé API ne facture que ce que vous exécutez. La clé est avantageuse lorsque vous codez par périodes plutôt que quotidiennement, lorsque vous voulez des limites de dépenses par clé et une visibilité sur l’utilisation au lieu d’une allocation opaque, ou lorsque vous voulez un modèle que l’abonnement ne propose pas. Elle est moins avantageuse si vous êtes un utilisateur quotidien intensif — à ce volume, un tarif fixe est difficile à battre. Les deux options ne s’excluent pas : les profils Codex vous permettent de conserver les deux et de choisir selon la tâche.

Dépannage

Questions fréquentes