Codex CLI avec une clé API — configuration, modèles et coût d’une session

Le Codex CLI est l’agent de codage open source en terminal d’OpenAI, et il fonctionne aussi bien avec une connexion ChatGPT qu’avec une clé API. La route par clé mérite d’être comprise : elle facture à l’usage, sans abonnement mensuel, et c’est la seule qui permet de pointer la CLI vers un autre fournisseur — ou vers une autre famille de modèles. Ce guide présente la configuration fonctionnelle, la condition qui fait échouer la plupart des passerelles, le coût d’une session et comment payer depuis le Brésil avec Pix.

La seule exigence qui compte

Le Codex CLI utilise la Responses API d’OpenAI, et uniquement celle-ci : le bloc model_providers n’accepte que wire_api = "responses". Une passerelle qui propose seulement /v1/chat/completions ne peut tout simplement pas être configurée — c’est pourquoi une grande partie des endpoints « compatibles OpenAI » échouent ici. Kunavo fournit POST /v1/responses ainsi que l’endpoint de chat, le bloc ci-dessous fonctionne donc sans adaptation.

La configuration

# ~/.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"

Le env_key est le nom de la variable d’environnement, et non la clé : Codex n’enregistre jamais la clé dans le fichier de configuration.

# O Codex lê a chave da variável indicada em env_key.
export KUNAVO_API_KEY="sk-kn-..."     # crie em kunavo.com/app/keys

# Deixe persistente (escolha o arquivo que o seu shell realmente carrega):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explique a estrutura deste repositório"

Créez la clé dans le tableau de bord après vous être inscrit et avoir rechargé 10 $ — elle ne s’affiche qu’une seule fois.

Payer depuis le Brésil — Pix, sans carte internationale

Pour le développeur brésilien, l’obstacle est rarement le fichier TOML : c’est le moyen de paiement. Payer directement l’API OpenAI exige une carte de crédit internationale activée pour les achats à l’étranger. Sur Kunavo, le checkout est traité par Stripe et Pix apparaît comme moyen de paiement pour les personnes payant depuis le Brésil — montant en réaux et compensation immédiate. Les cartes internationales (Visa, Mastercard, American Express), Apple Pay et Google Pay restent disponibles pour ceux qui le préfèrent.

Les tarifs par token sont définis en USD : avec Pix, Stripe affiche la conversion en reais au moment du paiement ; par carte, la conversion suit le taux de l’émetteur (vérifiez l’IOF et les frais de transaction internationale dans l’application de votre banque) — la procédure détaillée du rechargement par Pix figure dans le guide pour payer l’API avec Pix. Le portefeuille est prépayé — rechargement minimum de 10 $, sans abonnement ni renouvellement automatique, avec un solde qui n’expire jamais.

Quel modèle utiliser

Le gpt-5-6-sol est le GPT optimisé pour le code et le choix naturel par défaut de cette CLI, à $2.00 / $12.00 pour 1 M de tokens contre $5.00 / $30.00 au tarif catalogue d’OpenAI — qui facture aujourd’hui un tarif promotionnel de $4.00 / $20.00, disponible au moins jusqu’au 21 novembre 2026 selon la page des tarifs. Les tarifs complets figurent sur la page des tarifs.

Exécuter des modèles Claude dans le Codex CLI

Cela surprend souvent : le Codex CLI est lié au protocole, pas au modèle. Il utilise le format Responses, et tout modèle de chat placé derrière cet endpoint peut répondre. Pointez-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.

# Mesmo bloco de provider, outro modelo — sem chave nova, sem config nova.
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 vers l’API native Anthropic Messages, puis la réponse revient au format Responses. Une réserve honnête : Codex envoie des éléments reasoning opaques qu’un modèle natif Responses est le seul à pouvoir exploiter, et ils sont supprimés lors du passage vers un upstream qui n’est pas GPT. Le modèle perd le brouillon privé du tour précédent ; la transcription visible sur laquelle il s’appuie reste intacte. En pratique, cela réduit légèrement la continuité dans les longues chaînes de raisonnement, mais ne change rien aux boucles courantes modifier-exécuter-corriger.

Si vous voulez spécifiquement Claude, Claude Code a été conçu pour cela et transmet cache_control sans traduction. Mais si vous préférez le sandbox du Codex CLI et souhaitez utiliser Claude derrière celui-ci, cette combinaison est possible.

Combien coûte une session

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

Autrement dit : un rechargement de 10 $ via Pix couvre environ 8 tâches agentiques de 20 étapes. Et les requêtes qui échouent ne sont pas facturées — une erreur 5xx au milieu d’une session ne devient pas une ligne sur la facture.

Quand quelque chose ne fonctionne pas

Avant d’accuser Codex, vérifiez que la clé et l’endpoint répondent :

# Confirme a chave e o endpoint antes de culpar o 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": "Responda OK e nada mais."
  }'

• 404 — le fournisseur n’implémente pas /v1/responses, ou la base_url inclut déjà /responses. Codex ajoute lui-même le chemin : la base se termine par /v1.
• 401 — la variable indiquée dans env_key est vide dans le shell qui a lancé Codex. Vérifiez avec echo $KUNAVO_API_KEY dans ce même terminal.
• 402 — solde insuffisant : rechargez dans billing (le Pix est crédité immédiatement).
• model_not_found — le slug du modèle n’existe pas dans le catalogue ; vérifiez sur /models.

Questions fréquentes