Come configurare Codex config.toml: API personalizzata, proxy ed errori comuni

Codex conserva tutte le impostazioni in un unico file, config.toml: quale modello usare, quale API chiamare e quanta autonomia concedere all'agente senza chiedere. Il formato è cambiato più volte nel 2026 e molte guide pubblicate a inizio anno mostrano impostazioni che ora impediscono a Codex di avviarsi.

Questa guida propone prima una configurazione funzionante, poi illustra gli aspetti che la maggior parte delle persone modifica: profili, impostazioni di progetto, sandbox e proxy. In fondo trovi un elenco degli errori più probabili e il significato di ciascuno. Verificata sulla documentazione OpenAI e testata con Codex CLI 0.162.1 il 19 ottobre 2026. Gli esempi usano AIHubMix come provider; qualsiasi gateway che supporti l'API OpenAI Responses funziona allo stesso modo.

In breve

• Il file si trova in ~/.codex/config.toml, oppure in C:\Users\<you>\.codex\config.toml su Windows.
• Per un provider personalizzato servono base_url, wire_api = "responses" e env_key. La chiave API va inserita in una variabile d'ambiente.
• Ora i profili sono file separati, ~/.codex/<name>.config.toml, selezionabili con --profile <name>.
• Il file .codex/config.toml di un repository funziona solo nei progetti attendibili e non può modificare il provider.
• Riavvia Codex dopo ogni modifica: il file viene letto solo all'avvio.

Dove si trova config.toml

Le impostazioni principali si trovano in ~/.codex/config.toml. Lo leggono sia la CLI sia l'estensione per l'IDE. Se il file non esiste ancora, crealo.

Ci sono altri due percorsi in cui è possibile aggiungere impostazioni:

• File di profilo, ~/.codex/<name>.config.toml, usati solo quando avvii Codex con --profile <name>.
• File di progetto, .codex/config.toml all'interno di un repository, per condividere le impostazioni con il team.

Se esegui Codex in WSL2 su Windows, legge la home di Linux (/home/<you>/.codex/config.toml), non quella di Windows. Se CODEX_HOME è impostata, Codex usa quella cartella al posto di ~/.codex.

Una configurazione minima funzionante

Questo file completo ~/.codex/config.toml invia le richieste di Codex ad AIHubMix:

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

• model è l'ID del modello da chiamare, mentre model_reasoning_effort ne definisce il livello di ragionamento predefinito.
• model_provider deve corrispondere al nome in [model_providers.<name>]. Non usare openai, ollama o lmstudio: questi nomi sono riservati ai provider integrati di Codex.
• base_url è l'indirizzo API del provider. Al momento Codex accetta come unico valore wire_api = "responses".
• env_key è il nome di una variabile d'ambiente, non la chiave stessa.

Imposta quindi quella variabile con una chiave ottenuta dalla console AIHubMix:

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

Avvia codex da un nuovo terminale e chiedigli qualcosa. Se risponde, il provider funziona. Non importa che tu abbia effettuato l'accesso a Codex: la chiave di codex login non viene mai inviata a un provider personalizzato.

Profili: un file per ogni configurazione

Un profilo contiene solo le impostazioni diverse da quelle della configurazione principale, ad esempio un ragionamento più approfondito e una sandbox di sola lettura per la revisione del codice. Ogni profilo è un file a sé, accanto a config.toml, con le chiavi al livello principale:

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

Questa impostazione è cambiata con Codex 0.134.0. Le guide meno recenti inserivano i profili in config.toml come tabelle [profiles.review] e ne selezionavano uno con profile = "review". Ora Codex si rifiuta di avviarsi con quel selettore. Una tabella [profiles.review] rimasta nel file viene ignorata senza alcun messaggio, quindi le relative impostazioni smettono silenziosamente di funzionare. Per eseguire la migrazione, sposta le chiavi di ogni tabella in ~/.codex/<name>.config.toml, quindi elimina la tabella e la riga profile = .... Per maggiori dettagli, consulta la guida alla configurazione avanzata di OpenAI.

Configurazione di progetto: .codex/config.toml

Un file .codex/config.toml in un repository permette al team di condividere un modello predefinito, un livello di ragionamento o una modalità sandbox. Codex lo legge solo nei progetti contrassegnati come attendibili nel tuo ~/.codex/config.toml personale:

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Un file di progetto non può modificare la destinazione delle richieste. Codex ignora lì model_provider, model_providers, openai_base_url, profile, notify e alcune altre chiavi, mostrando un avviso quando lo fa. Imposta il provider in ~/.codex/config.toml. Il progetto può comunque selezionare il modello; le richieste saranno inviate al tuo provider.

Quale impostazione prevale

Quando la stessa chiave è impostata in più punti, la sezione Nozioni di base sulla configurazione di OpenAI indica quest'ordine, dal più prioritario:

1. Flag della riga di comando, incluse le opzioni -c
2. Il file .codex/config.toml del progetto
3. Il profilo selezionato con --profile
4. Il tuo ~/.codex/config.toml
5. La configurazione di sistema, /etc/codex/config.toml
6. Le impostazioni predefinite integrate di Codex

Nota che il file di progetto ha la precedenza sul profilo. Se un'impostazione del profilo sembra non avere effetto, verifica se il file .codex/config.toml del repository imposta la stessa chiave.

Per modificare un'impostazione solo per una singola esecuzione, usa -c:

codex -c model_reasoning_effort=high

Sandbox e approvazioni

Due chiavi controllano ciò che Codex può fare autonomamente. sandbox_mode definisce quali risorse possono essere toccate dai suoi comandi, mentre approval_policy stabilisce quando si ferma per chiederti il permesso.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

Le due impostazioni sono indipendenti: never disattiva le richieste di conferma, ma non rende meno restrittiva la sandbox. In modalità workspace-write, i comandi non possono accedere alla rete finché non imposti network_access = true.

Con un proxy

Codex non dispone di un'impostazione per il proxy in config.toml. Usa le consuete variabili d'ambiente:

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

La documentazione OpenAI non ne parla, quindi le variabili sono state testate con Codex 0.162.1: le richieste, comprese quelle indirizzate a un provider personalizzato, sono passate tramite HTTPS_PROXY (o ALL_PROXY), mentre gli host elencati in NO_PROXY sono stati raggiunti direttamente. I file PAC non sono supportati, quindi inserisci direttamente l'indirizzo del proxy. Se il proxy aziendale usa un proprio certificato radice, imposta CODEX_CA_CERTIFICATE perché punti al certificato, come descritto nel riferimento alle variabili d'ambiente.

Più modelli in /model

Il selettore /model mostra solo i modelli OpenAI. Per selezionare da lì modelli GLM, Claude, Gemini o DeepSeek, aggiungi un catalogo di modelli: un file JSON indicato dalla chiave di primo livello model_catalog_json. Inserisci questa chiave prima della prima riga [table], altrimenti TOML la considera parte di quella tabella e Codex la ignora.

Il catalogo sostituisce l'elenco integrato e ogni voce richiede molti campi, quindi è meglio generarlo anziché scriverlo a mano. La guida di AIHubMix alla CLI di Codex include uno script che lo crea a partire dai 30 modelli più usati su AIHubMix. L'app desktop potrebbe comunque nascondere i modelli personalizzati nel selettore (openai/codex#19694), quindi cambia modello dal terminale.

Errori comuni e relativo significato

Questi sono i messaggi mostrati da Codex 0.162.1 per ciascun errore.

legacy profile = "..." config is no longer supported
In config.toml è ancora presente la vecchia riga profile = "...". Sposta il profilo nel suo file, come descritto sopra. Eseguire --profile x mentre è presente una vecchia tabella [profiles.x] genera un errore simile: --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
Codex non supporta più l'API Chat Completions. Imposta wire_api = "responses". Un provider che offre solo Chat Completions non funzionerà senza un proxy di traduzione.

model_providers contains reserved built-in provider IDs
Hai chiamato il provider openai, ollama o lmstudio. Rinomina la tabella e imposta model_provider con un altro nome.

approval_policy = "untrusted" is no longer supported
Rimuovi la riga oppure usa on-request.

Missing environment variable: AIHUBMIX_API_KEY
La variabile indicata in env_key non è impostata nel terminale da cui hai avviato Codex. Apri un nuovo terminale oppure esegui source ~/.zshrc, quindi riavvia Codex.

401 Unauthorized dopo alcune righe "Reconnecting..."
La richiesta è stata inviata senza una chiave. Verifica che la tabella del provider contenga env_key. Le credenziali salvate in auth.json non valgono per i provider personalizzati.

Model metadata for ... not found. Defaulting to fallback metadata
Codex non dispone di impostazioni integrate per questo modello, cosa normale per i modelli non OpenAI. Le richieste funzionano comunque. Aggiungi un catalogo di modelli se vuoi impostazioni adeguate e visualizzare il modello in /model.

Ignored unsupported project-local config keys
Il file .codex/config.toml di un repository imposta una chiave utilizzabile solo nella tua configurazione personale, di solito model_provider. Spostala in ~/.codex/config.toml.

missing field base_instructions
A una voce del catalogo dei modelli manca un campo obbligatorio, quindi Codex rifiuta l'intero file. Rigenera il catalogo con lo script invece di modificarlo a mano.

Quando un'impostazione non ha effetto

• Riavvia Codex dopo la modifica.
• Assicurati che le chiavi di primo livello precedano la prima riga [table].
• Controlla il file .codex/config.toml del repository: prevale sulle impostazioni del profilo.
• Controlla che non sia rimasta una tabella [profiles.x].
• Esegui codex doctor, che controlla l'installazione, la configurazione e l'accesso.

Per usare in Codex i modelli di OpenAI, Anthropic, Google, Zhipu, DeepSeek e altri con una sola chiave, AIHubMix li rende disponibili tramite l'API Responses all'indirizzo https://aihubmix.com/v1. Parti dalla configurazione minima qui sopra e aggiungi un catalogo di modelli per passare da un modello all'altro con /model.

Domande frequenti

Dove si trova il file config.toml di Codex?
In ~/.codex/config.toml su macOS e Linux, e in C:\Users<you>.codex\config.toml su Windows. Se CODEX_HOME è impostata, il file si trova invece in quella cartella.

Devo riavviare Codex dopo aver modificato config.toml?
Sì. Codex legge il file all'avvio, quindi chiudi e riapri la sessione del terminale o l'app.

Perché Codex dice «la configurazione dei profili legacy non è più supportata»?
Codex 0.134.0 ha rimosso i profili definiti in config.toml. Sposta ogni profilo in ~/.codex/name.config.toml, elimina le vecchie righe e avvia Codex con --profile name.

Posso ancora usare wire_api = "chat"?
No. Codex accetta solo wire_api = "responses". Un provider che supporta solo Chat Completions richiede un proxy che traduca le richieste nell'API Responses.

Perché il mio provider personalizzato restituisce 401 anche se ho effettuato l'accesso a Codex?
La chiave di accesso in auth.json non viene inviata ai provider personalizzati. Aggiungi env_key alla tabella del provider e imposta quella variabile nel terminale.

Codex usa HTTPS_PROXY?
Sì. In un test con Codex 0.162.1, le richieste sono passate tramite HTTPS_PROXY e hanno ignorato gli host elencati in NO_PROXY. I file PAC non sono supportati.

Perché model_provider viene ignorato in .codex/config.toml del mio progetto?
I file di progetto non possono modificare la destinazione delle richieste, quindi un repository non può reindirizzare il tuo traffico. Inserisci il provider in ~/.codex/config.toml; il file di progetto può comunque impostare il modello.

Fonti

• Nozioni di base sulla configurazione, OpenAI
• Configurazione avanzata, OpenAI
• Riferimento della configurazione, OpenAI
• Guida all'integrazione di Codex CLI, AIHubMix
• Configurazione del proxy per Codex CLI: SOCKS, HTTP e reti aziendali, Daniel Vaughan