Codex CLI con chiave API — configurazione, modelli e costo della sessione

Il Codex CLI è l'agente di codice open source da terminale di OpenAI e funziona sia con l'accesso ChatGPT sia con una chiave API. Vale la pena capire il percorso della chiave: addebita per token, senza abbonamento mensile, ed è l'unico che consente di indirizzare la CLI verso un altro provider — o un'altra famiglia di modelli. Questa guida illustra la configurazione funzionante, il requisito che fa fallire la maggior parte dei gateway, il costo di una sessione e come pagare dal Brasile tramite Pix.

L'unico requisito importante

Il Codex CLI usa la Responses API di OpenAI, e solo quella: il blocco model_providers accetta esclusivamente wire_api = "responses". Un gateway che offra solo /v1/chat/completions non può essere configurato — ecco perché molti endpoint “compatibili con OpenAI” falliscono qui. Kunavo offre POST /v1/responses insieme all'endpoint chat, quindi il blocco seguente funziona senza adattamenti.

La configurazione

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

env_key è il nome della variabile d'ambiente, non la chiave: Codex non scrive mai la chiave nel file di configurazione.

# 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"

Crea la chiave nella dashboard dopo esserti registrato e aver ricaricato $10 — viene mostrata una sola volta.

Pagare dal Brasile — Pix, senza carta internazionale

Per lo sviluppatore brasiliano, l’ostacolo raramente è il file TOML: è il metodo di pagamento. Pagare direttamente l’API OpenAI richiede una carta di credito internazionale abilitata agli acquisti all’estero. Su Kunavo il checkout viene elaborato da Stripe e Pix compare come metodo di pagamento per chi paga dal Brasile — importo in reais e compensazione immediata. Le carte internazionali (Visa, Mastercard, American Express), Apple Pay e Google Pay restano disponibili per chi le preferisce.

Le tariffe per token sono definite in USD: con Pix Stripe mostra la conversione in reais al momento del pagamento; con la carta, la conversione segue il tasso dell'emittente (verifica IOF e la commissione per transazioni internazionali nell'app della banca) — la procedura dettagliata per ricaricare tramite Pix è nella guida su come pagare l'API con Pix. Il portafoglio è prepagato — ricarica minima di $10, senza abbonamento né rinnovo automatico, con saldo che non scade mai.

Quale modello usare

gpt-5-6-sol è il GPT ottimizzato per il codice e il modello predefinito naturale di questa CLI, a $2,00 / $12,00 per 1M di token rispetto a $5,00 / $30,00 al prezzo di listino OpenAI — che oggi applica il prezzo promozionale di $4,00 / $20,00, disponibile almeno fino al 21 novembre 2026 secondo la pagina dei prezzi. Le tariffe complete sono nella pagina dei prezzi.

Eseguire modelli Claude nel Codex CLI

Questo spesso sorprende: il Codex CLI è vincolato al protocollo, non al modello. Usa il formato Responses e qualsiasi modello di chat dietro quell'endpoint può rispondere. Indirizzalo a claude-opus-5 e funzionerà dall'inizio alla fine — comprese le chiamate agli strumenti, quindi l'agente continuerà a leggere file, proporre modifiche ed eseguire comandi.

# 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"

Il gateway traduce la richiesta Responses nell'API nativa Anthropic Messages e la risposta nuovamente nel formato Responses. Una precisazione onesta: Codex invia elementi reasoning opachi che solo un modello nativo Responses può consumare, e questi vengono eliminati nel percorso verso un upstream non GPT. Il modello perde la bozza privata del turno precedente; la trascrizione visibile da cui parte rimane intatta. In pratica, questo comporta una perdita limitata di continuità nelle catene di ragionamento lunghe, ma nulla nei normali cicli modifica-esegui-correggi.

Se vuoi specificamente Claude, Claude Code è stato creato per questo e passa cache_control senza traduzione. Ma se preferisci il sandbox del Codex CLI e vuoi Claude dietro di esso, la combinazione è possibile.

Quanto costa una sessione

Le CLI agentiche reinviano il prompt di sistema, la cronologia dell'attività e il contesto dei file a ogni passaggio, quindi i token si accumulano più rapidamente di quanto suggerisca il numero di passaggi. Un passaggio tipico contiene circa 25.000 token di input e 1.200 di output:

In altre parole: una ricarica di $10 tramite Pix copre circa 8 attività agentiche da 20 passaggi. Inoltre, le richieste non riuscite non vengono addebitate — un 5xx nel mezzo di una sessione non diventa una voce in fattura.

Quando qualcosa non funziona

Prima di incolpare Codex, verifica che la chiave e l'endpoint rispondano:

# 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 — il provider non implementa /v1/responses oppure base_url include già /responses. Codex aggiunge il percorso autonomamente: la base termina con /v1.
• 401 — la variabile indicata in env_key è vuota nella shell che ha aperto Codex. Verifica con echo $KUNAVO_API_KEY nello stesso terminale.
• 402 — saldo insufficiente: ricarica in billing (Pix viene accreditato immediatamente).
• model_not_found — lo slug del modello non esiste nel catalogo; verifica in /models.

Domande frequenti