API key della CLI Codex — configurazione funzionante per provider personalizzati

Una chiave API Codex è qualsiasi chiave con cui Codex CLI può addebitare i token invece di un piano ChatGPT: una chiave API OpenAI di platform.openai.com oppure una chiave di provider come la sk-kn- di Kunavo, che Codex legge dalla variabile d'ambiente indicata da env_key in un blocco model_providers. Il provider deve offrire l'API Responses: è l'unico requisito riportato di seguito.

Codex CLI è l'agente di programmazione open source da terminale di OpenAI e funziona sia con un accesso ChatGPT sia con una chiave API. Vale la pena comprendere la route con chiave API: addebita per token senza canone mensile ed è l'unica che permette di indirizzare la CLI verso un provider diverso, o persino verso un'intera famiglia di modelli diversa. Questa guida illustra la configurazione operativa, l'unico requisito che mette in difficoltà la maggior parte dei gateway e il costo effettivo di una sessione.

L'unico requisito importante

Codex CLI è più rigido della maggior parte degli strumenti riguardo agli endpoint personalizzati. Il suo blocco model_providers contiene una chiave wire_api e accetta esattamente un valore: responses. Ciò significa che un provider personalizzato deve offrire l'API Responses di OpenAI su POST /v1/responses, non il molto più comune /v1/chat/completions. La maggior parte dei gateway compatibili con OpenAI offre soltanto quest'ultimo, motivo per cui tanti non possono pilotare Codex CLI, qualunque sia il valore di base_url fornito.

Kunavo offre entrambe le superfici, quindi la configurazione seguente funziona così com'è.

La configurazione

Codex legge ~/.codex/config.toml. Due chiavi di primo livello selezionano il modello e il provider; il blocco provider descrive come raggiungerlo:

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

Nota cosa non c'è in quel file: la chiave stessa. env_key indica una variabile d'ambiente e Codex legge la chiave da lì all'avvio, quindi il file di configurazione può essere salvato o condiviso in sicurezza.

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

Crea la chiave nel dashboard dopo esserti registrato e aver ricaricato $10. Viene mostrata una sola volta, quindi conservala subito. Se codex era già in esecuzione in un'altra shell, riavvialo: legge la variabile all'avvio, non a ogni richiesta.

Verifica prima di fare debug

Se qualcosa non funziona, determina se il problema è la chiave, l'endpoint o la CLI. Una richiesta è sufficiente:

# 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."
  }'

Una risposta JSON significa che chiave ed endpoint sono corretti e che qualsiasi problema rimanente riguarda config.toml. Un 401 significa che la chiave è errata o che la variabile è vuota in questa shell. Un 404 su model significa che lo slug non corrisponde al catalogo.

Quale modello impostare

Il valore di model è solo uno slug sullo stesso endpoint, quindi cambiare modello richiede una modifica di una parola: nessuna nuova chiave né nuovo blocco provider.

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

Eseguire modelli Claude in Codex CLI

Questo sorprende molte persone: Codex CLI è vincolato al protocollo, non al modello. Parla il formato wire Responses e risponde qualsiasi modello chat si trovi dietro quell'endpoint. Indirizzalo a claude-opus-5 e funzionerà dall'inizio alla fine, comprese le chiamate agli strumenti: l'agente continuerà a leggere file, proporre modifiche ed eseguire comandi normalmente.

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

Il gateway traduce la richiesta Responses nell'API Anthropic Messages e la risposta nuovamente nel formato Responses. Una precisazione importante: 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 il proprio scratchpad privato del turno precedente; la trascrizione visibile da cui lavora rimane intatta. In pratica, ciò comporta una lieve perdita di continuità nelle lunghe catene di ragionamento e nessun effetto nei normali cicli modifica-esecuzione-correzione.

Stabilire se sia una buona idea è una questione separata dal fatto che funzioni. Se vuoi specificamente Claude, Claude Code è progettato per questo e trasmette cache_control senza tradurlo. Se invece preferisci il sandboxing di Codex CLI e vuoi Claude dietro di esso, questa combinazione è disponibile.

Quanto costa una sessione

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

Poiché le tariffe dell'output differiscono tra le famiglie di modelli molto più di quelle dell'input, le attività con molto output modificano la classifica: inserisci i tuoi numeri nel calcolatore dei costi invece di fidarti di un solo esempio svolto. Le richieste non riuscite non vengono addebitate.

Quando la route con chiave API conviene più di un abbonamento

Un piano ChatGPT include l'utilizzo di Codex a una tariffa mensile fissa; una chiave API addebita solo ciò che esegui. La route con chiave conviene quando programmi a periodi invece che ogni giorno, quando vuoi limiti di spesa per chiave e visibilità sull'utilizzo invece di un'assegnazione opaca, o quando vuoi un modello che l'abbonamento non offre. Conviene meno se sei un utente intensivo quotidiano: a quel volume una tariffa fissa è difficile da battere. Le route non si escludono a vicenda: i profili Codex permettono di mantenerle entrambe e cambiare per attività.

Risoluzione dei problemi

Domande frequenti