Codex CLI con un provider personalizzato: config.toml, modelli GPT e Claude, estensione IDE e soluzioni ai problemi

Codex legge un unico file, ~/.codex/config.toml, condiviso dalla CLI, codex exec e dall'estensione IDE. Un provider personalizzato in quel file indirizza Codex a questo gateway, dove la stessa configurazione esegue modelli GPT e modelli Claude. Le versioni attuali di Codex comunicano solo tramite Responses API (wire_api = "responses"), quindi le vecchie guide che usano wire_api = "chat" non funzionano più.

Installa Codex

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or with a package manager
npm install -g @openai/codex
brew install --cask codex

codex --version

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

L'estensione Codex per VS Code, Cursor e Windsurf si installa dal marketplace delle estensioni dell'editor e usa lo stesso ~/.codex/config.toml della CLI, quindi tutto quanto segue si applica a entrambi.

Usa una chiave del gruppo corretto

Una chiave del gateway appartiene a un solo gruppo, e il gruppo determina quali modelli la chiave può chiamare. Per i modelli GPT, crea la chiave nel gruppo **Codex** nella dashboard. Per i modelli Claude, va bene qualsiasi chiave Claude con pagamento a consumo. Una chiave di un gruppo illimitato richiede un piano attivo; in sua assenza, ogni richiesta fallisce con No active subscription found for this group.

export AIPRIME_CODEX_KEY=key_from_the_codex_group    # GPT models
export AIPRIME_CLAUDE_KEY=key_from_a_claude_group    # Claude models

setx AIPRIME_CODEX_KEY "key_from_the_codex_group"
setx AIPRIME_CLAUDE_KEY "key_from_a_claude_group"
# open a new terminal afterwards

config.toml per i modelli GPT

model_provider = "aiprime"
model = "gpt-6-astra"
model_reasoning_effort = "high"

[model_providers.aiprime]
name = "AI Prime Tech"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CODEX_KEY"
wire_api = "responses"
supports_websockets = false

Esegui Codex con i modelli Claude

Il gateway accetta richieste Responses API per i modelli Claude e le converte, quindi Codex può usare anche Claude. Aggiungi un secondo provider che usi la tua chiave Claude, poi un profilo per passare a quel provider.

[model_providers.aiprime_claude]
name = "AI Prime Tech (Claude)"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CLAUDE_KEY"
wire_api = "responses"
supports_websockets = false

model_provider = "aiprime_claude"
model = "claude-sonnet-5"
model_reasoning_effort = "high"

codex --profile claude
codex exec --profile claude "review the last commit for bugs"

A partire da Codex 0.134.0, ogni profilo ha un proprio file, ~/.codex/<name>.config.toml, con le relative chiavi al livello principale; [profiles.<name>] le tabelle all'interno di config.toml non vengono più lette. Profili e provider possono essere impostati solo nella configurazione utente: il file di progetto .codex/config.toml ignora model_provider e model_providers.

Modelli e intensità del ragionamento

model_reasoning_effort accetta low, medium, high, xhigh o max, a seconda del modello. Non impostare none: questi modelli lo rifiutano con 'none' is not supported. review_model imposta un modello diverso per /review se lo desideri. La dashboard mostra tutti i modelli che il gruppo della tua chiave può chiamare.

Estensione IDE e codex exec

L'estensione IDE legge lo stesso config.toml, ma env_key viene risolto dall'ambiente dell'editor stesso. Un editor avviato dal Dock o dal menu Start non vede le variabili esportate in .bashrc, e Codex quindi fallisce con Invalid API key mentre la CLI funziona. Imposta la variabile a livello di sistema (su Windows setx lo fa), oppure avvia l'editor da un terminale, ad esempio code ..

codex exec esegue una singola attività senza l'interfaccia interattiva, quindi è adatto a script e CI. Usa la stessa configurazione e gli stessi profili:

codex exec "write unit tests for utils.py"
codex exec --profile claude "summarise the changes on this branch"
codex login status        # which authentication method is active

Nuovi tentativi e timeout

Ogni provider ha le proprie impostazioni per i tentativi e lo streaming. I valori predefiniti sono 4 nuovi tentativi per le richieste, 5 riconnessioni dello stream e un timeout di inattività di 5 minuti per ogni stream. I turni di ragionamento lunghi possono restare senza output per un po', quindi aumentare il timeout di inattività aiuta con livelli elevati di intensità del ragionamento.

[model_providers.aiprime]
# ...settings from above...
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000

Risoluzione dei problemi: errori riscontrati dagli utenti di Codex

Gli errori seguenti sono quelli effettivamente prodotti dai client Codex su questo gateway, a partire dai più comuni.

Stai confrontando Codex con Claude Code prima di sceglierne uno? Consulta Claude Code vs Codex.

Domande frequenti

AI Prime Tech è un gateway API indipendente. Non è affiliato ad Anthropic, non è approvato da Anthropic e non è un suo rivenditore. Claude e i nomi dei modelli correlati sono marchi dei rispettivi proprietari.