# Configurare CLIProxyAPI + Codex: Docker, OAuth e reverse proxy > Canonical: https://vxi.me/it/posts/cliproxyapi-codex-docker-proxy/ > Locale: it-it > Published: 2026-03-30 > Updated: 2026-10-14 > Markdown: https://vxi.me/it/posts/cliproxyapi-codex-docker-proxy.md **Repository di supporto**: la versione one-command deploy di questa guida — deployment Docker, generazione delle chiavi e rendering della configurazione con un solo comando, più un generatore per la configurazione client e un esempio Nginx: kuangyongjie/cliproxyapi-codex-deploy ```bash git clone https://github.com/kuangyongjie/cliproxyapi-codex-deploy.git cd cliproxyapi-codex-deploy ./scripts/setup.sh ``` CLIProxyAPI permette di mettere Codex dietro un endpoint OpenAI-compatible gestito da te. Il percorso pratico è questo: eseguire CLIProxyAPI con Docker, completare l'OAuth di Codex sul proxy, esporre un endpoint `/v1` stabile e infine puntare il client Codex locale a quell'endpoint con la Responses API abilitata. ## Configurazione rapida 1. Distribuisci CLIProxyAPI con Docker o Docker Compose. 2. Rendi persistente la directory di autenticazione del proxy, così lo stato OAuth sopravvive ai riavvii. 3. Esegui il flusso di login OAuth di Codex sul proxy. 4. Esponi il proxy tramite HTTPS mantenendo intatto il percorso `/v1/`. 5. Punta Codex al proxy con un `base_url` personalizzato. 6. Imposta `wire_api = "responses"` e usa una chiave proxy downstream. Il resto della guida spiega perché ciascun passaggio conta, come si incastrano i diversi livelli di autenticazione e quali errori rompono più spesso un setup che, per il resto, sembra sano. Se Codex fa già parte del tuo flusso quotidiano, prima o poi compare una domanda piuttosto ovvia: continui semplicemente a usare il login diretto ufficiale oppure metti Codex dietro un tuo livello proxy e lo trasformi in una parte di un'infrastruttura più ampia che controlli tu? Per una sola macchina e un solo utente, il login diretto resta la soluzione più semplice. Non ha senso fingere il contrario. Installi, accedi e continui a lavorare. Meno componenti, meno servizi e meno punti da diagnosticare. Quando però il workflow cresce, la domanda cambia. Potresti voler far puntare più macchine allo stesso endpoint. Potresti voler mettere Codex, Claude Code e Gemini CLI dietro un unico livello di routing. Oppure potresti voler gestire stato OAuth e policy di accesso lato server, invece di rifare tutto su ogni client. È in quel momento che [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) smette di sembrare un progetto proxy di nicchia e inizia a diventare un pezzo di infrastruttura utile. Quello che mi ha spinto a prendere sul serio questa strada non è stato il desiderio di avere “un setup più elegante”. È stata la constatazione che il login diretto è ottimo su una macchina, ma inizia a frammentarsi quando Codex deve convivere con un VPS, alcuni tool self-hosted e qualche script interno. Lo stato di login rimane su un client, ogni altra app vuole la propria configurazione di endpoint e il consumer successivo significa un'altra tornata di setup. La domanda reale è quindi diventata: se voglio Codex dietro CLIProxyAPI, eseguito con Docker su un server Linux, autenticato lì tramite OpenAI OAuth e poi collegato di nuovo all'app Codex locale, come appare davvero quella catena e dove tende a rompersi? ## Perché mettere Codex dietro un proxy La mia risposta è sostanzialmente questa: se l'obiettivo è la comodità immediata, il login diretto continua a vincere. Se invece vuoi rendere Codex parte di un livello riutilizzabile e controllabile di strumenti AI, l'approccio con proxy vale la pena. Il vantaggio non è che sembra più avanzato. Il vantaggio è che stato di autenticazione, routing, controllo degli endpoint ed estensioni future non restano più legati a una singola installazione client. Una volta che il livello proxy esiste, il beneficio tende ad andare molto oltre Codex. Quello che ottieni davvero è un punto di ingresso riutilizzabile e compatibile con OpenAI che può essere condiviso anche da altri tool self-hosted. Se un progetto permette di impostare un `base_url` personalizzato, è molto probabile che possa stare dietro lo stesso gateway. Codex può essere il primo servizio che colleghi, ma raramente resta l'unico. Un frontend self-hosted, un pannello agent, un servizio interno di script o un'altra app OpenAI-compatible possono riutilizzare lo stesso endpoint invece di mantenere ciascuno il proprio stato di login upstream. È facile non notare cosa venga realmente condiviso. Non si tratta di continuare a copiare uno stesso segreto upstream in sempre più posti. È l'opposto. Lo stato OAuth e i token rimangono centralizzati nel livello proxy, mentre i tool downstream hanno bisogno solo dell'URL del proxy e di una chiave emessa dal proxy. Sembra una piccola differenza di configurazione, ma operativamente è una forma molto diversa rispetto al rifare login e distribuzione di segreti in ogni app o container. Quando aggiungi un altro tool OpenAI-compatible non ti chiedi più “come faccio il login anche qui?”, ma “quale chiave proxy deve usare e deve condividere lo stesso endpoint?”. Per uno sviluppatore indipendente questo cambia anche il modo in cui si gestiscono i segreti. Invece di far conoscere l'autenticazione upstream a ogni macchina e a ogni applicazione, lo stato OAuth sensibile resta centralizzato nel proxy. Client downstream e progetti self-hosted necessitano solo di una chiave proxy e di un endpoint stabile. Aggiungere un nuovo progetto diventa “emettere una nuova chiave downstream e puntarlo al gateway”, non “ripetere da capo tutta la storia di autenticazione upstream”. Esiste anche una via di mezzo molto pratica. Se oggi hai soltanto pochi strumenti interni, puoi inizialmente lasciarne condividere una sola chiave API del proxy per portarli online velocemente. In seguito, quando desideri log più puliti, throttling per progetto o la possibilità di revocare un consumer senza toccare gli altri, separi le chiavi. In altre parole, il livello proxy è utile sia quando oggi ottimizzi per velocità sia quando stai preparando una configurazione più disciplinata per il futuro. ## Dividi la catena in tre parti La cosa che mi ha aiutato di più è stata separare tutto in tre pezzi. Primo, c'è il servizio `CLIProxyAPI` che gira sul server. Secondo, c'è lo stato OAuth di Codex che deve essere realmente memorizzato nella directory auth montata e usata da quel servizio. Terzo, c'è la configurazione locale del client Codex, soprattutto `~/.codex/config.toml` e `~/.codex/auth.json`. Se mantieni distinti questi tre livelli, il setup rimane gestibile. Se li confondi, tutto comincia a sembrare più misterioso di quanto sia realmente. La documentazione del progetto copre già i componenti principali: Codex tramite OAuth, deployment con Docker e Docker Compose e schema della configurazione client locale. Il trucco è capire quale file appartiene a quale livello. `config.yaml` appartiene al servizio proxy. La directory `auth/` montata appartiene allo stato di login salvato dal proxy. I file sotto `~/.codex/` appartengono all'applicazione Codex locale. ## Lato server: deployment Docker e login OAuth Se dovessi configurarlo da zero, manterrei la directory sul server volutamente molto piccola: ```text /opt/cliproxyapi/ ├── docker-compose.yml ├── config.yaml └── auth/ ``` Quella directory `auth/` è più importante di quanto sembri. CLIProxyAPI usa per impostazione predefinita `~/.cli-proxy-api` come directory auth e, con Docker, il punto è montare quel percorso fuori dal container, così lo stato OAuth sopravvive ai riavvii e alle ricostruzioni. Molti casi del tipo “ieri funzionava e dopo il riavvio no” sono semplicemente mancanza di persistenza qui. Per il primo passaggio terrei anche `config.yaml` il più minimale possibile. Il file ufficiale `config.example.yaml` è ampio, ma per un proxy Codex all'inizio servono pochi elementi: ```yaml host: "" port: 8317 auth-dir: "~/.cli-proxy-api" api-keys: - "" remote-management: allow-remote: false secret-key: "" ``` Qui è facile fraintendere due cose. La sezione `api-keys` **non** contiene la credenziale upstream di OpenAI. Contiene le credenziali che i client downstream usano per chiamare il proxy. Questa separazione è in realtà uno degli aspetti migliori del design, perché puoi emettere chiavi diverse per client o progetti diversi. Codex può usarne una, un'altra app self-hosted un'altra e, se una va ruotata o revocata, lo fai nel livello proxy senza rimettere mano al login upstream. E a meno che non ci sia un vero motivo per esporre da remoto il livello di management, lascerei disattivato `remote-management.allow-remote`. Il default è già prudente, ed è la scelta giusta in questo scenario. Per Docker Compose terrei tutto semplice ed esplicito: ```yaml services: cli-proxy-api: image: eceasy/cli-proxy-api:latest container_name: cli-proxy-api restart: unless-stopped ports: - "127.0.0.1:8317:8317" - "127.0.0.1:1455:1455" volumes: - ./config.yaml:/CLIProxyAPI/config.yaml - ./auth:/root/.cli-proxy-api ``` Entrambe le porte sono associate al loopback di proposito. La porta API deve essere raggiungibile solo da Nginx sullo stesso host — la sezione lato client più sotto fa già proxy verso `http://127.0.0.1:8317` — e il listener del callback OAuth ha una storia documentata di binding su tutte le interfacce quando pubblicato apertamente (issue #3463 dell'upstream). Pubblicare queste due porte su Internet per impostazione predefinita trasformerebbe una superficie di login temporanea in una permanente; non trattare la pubblicazione pubblica come il default sicuro. Se la tua topologia di rete richiede davvero un accesso più ampio, definiscilo come eccezione esplicita con restrizioni proprie, non come punto di partenza. Un'ultima nota sul tag dell'immagine: `:latest` è un tag mobile. La mappa dei campi v8 di questa guida è stata verificata il 2026-10-14 contro il branch main del repository upstream — non eseguendo questa immagine. Prima del deploy, conferma che il tag che scarichi corrisponda ancora a quel layout, oppure fissa un digest che hai verificato tu. La porta aggiuntiva `1455` ha un motivo. La documentazione ufficiale del provider indica che Codex OAuth usa un callback locale sulla porta `1455`. Spesso ci si concentra soltanto sulla porta API principale `8317`, ma la parte OAuth del flusso ha aspettative proprie. Il servizio può essere avviato e sano mentre il login continua a fallire semplicemente perché quel callback non è mai stato considerato. Con il container in esecuzione, il comando documentato per il login Codex è: ```bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login ``` Il flag `-no-browser` è particolarmente utile su un server Linux remoto perché stampa l'URL invece di tentare di aprire un browser nel container. È anche il punto in cui conviene essere molto precisi mentalmente: in questa fase **non** stai effettuando il login del client Codex locale. Stai autenticando Codex per il servizio proxy, in modo che il proxy possa successivamente rispondere a richieste compatibili con Codex. C'è una cosa di quel callback che è facile fraintendere su una macchina remota. Il browser gira sul tuo laptop locale, quindi `http://localhost:1455/auth/callback` si risolve al tuo laptop — non al VPS — indipendentemente da come sono mappate le porte del container. Per un setup remoto Linux/VPS, l'ordine che chiude davvero il cerchio è: 1. Sulla tua macchina **locale** (non sul server), apri prima il tunnel: ```bash ssh -N -L 1455:127.0.0.1:1455 @ ``` 2. Esegui il comando di login di questa guida. La CLI stampa l'URL OAuth — con `-no-browser`, il suo stesso codice stampa persino queste istruzioni per il tunnel SSH. 3. Apri quell'URL nel browser locale e completa l'accesso. Il callback verso `localhost:1455` ora viaggia attraverso il tunnel fino al container. Se salti il tunnel, la CLI resterà su «Waiting for Codex authentication callback...» e, dopo circa 15 secondi, proporrà `Paste the Codex callback URL (or press Enter to keep waiting):`. Puoi incollare l'URL completo del callback direttamente dalla barra degli indirizzi del browser — è il percorso manuale proprio della CLI, non un trucco. Se questo passaggio non termina davvero, ciò che viene dopo conta poco. Al primo giro controllerei attentamente due cose: l'output di `docker compose logs -f` e la directory `auth/` montata. Se il flusso OAuth sembra riuscito ma in `auth/` non compare nulla di utile, non hai ancora uno stato proxy affidabile. ## Riferimento ai campi di config.yaml (v8) Il `config.yaml` minimo più sopra in questa guida usa le vecchie grafie top-level (`host`, `port`, `auth-dir`, `api-keys`, `remote-management`). Continuano a caricarsi senza problemi, ma il progetto upstream è passato a un layout `v8` (`config-version: 8`) in cui ogni impostazione vive sotto una sezione nominata. Se copi esempi dall'attuale `config.example.yaml` del repository upstream, vedrai il nuovo layout — ecco quindi una mappa campo per campo delle impostazioni che un setup proxy Codex tocca davvero. Ogni nome di campo è verificato contro il `config.example.yaml` dell'upstream sul branch main (controllato il 2026-10-14). I fork «plus» possono divergere; conferma la loro immagine/versione pinnata e il loro `config.example.yaml` prima di dare per scontato che questo layout valga anche per loro. | Campo (v8) | Vecchia grafia | Cosa fa | |---|---|---| | `config-version: 8` | — | Dichiara il layout v8. Se coesistono entrambe le grafie di un campo, vince il valore v8. | | `server.host` | `host` | Interfaccia di ascolto. Una stringa vuota lega tutte le interfacce. | | `server.port` | `port` | La porta API chiamata dai client. `8317` in questa guida. | | `oauth.auth-dir` | `auth-dir` | Dove viene salvato lo stato OAuth di Codex. Deve corrispondere al mount di `auth/`, altrimenti i login si perdono al riavvio. | | `access.api-keys` | `api-keys` | Chiavi downstream per i tuoi client. **Non** sono credenziali upstream di OpenAI. | | `management.allow-remote` | `remote-management.allow-remote` | Lascialo su `false` a meno che tu non abbia un vero motivo per esporre la Management API. | | `management.secret-key` | `remote-management.secret-key` | Chiave della Management API. Vuota disabilita del tutto la Management API. | | `client.codex.optimize-multi-agent-v2` | — | Opzionale. Ottimizza le richieste di Codex Desktop e codex-tui per setup multi-agent. Default `false`. | Una configurazione minima in stile v8 per il setup di questa guida è così: ```yaml config-version: 8 server: host: "" port: 8317 oauth: auth-dir: "~/.cli-proxy-api" access: api-keys: - "" management: allow-remote: false secret-key: "" ``` Due dettagli meritano di essere detti a parte. Primo: `access.api-keys` è la stessa lista del vecchio `api-keys` — chiavi che consegni ai client downstream, mai segreti upstream. Secondo: `oauth.auth-dir` dentro il container si risolve di default a `/root/.cli-proxy-api`, ed è per questo che il compose monta `./auth` proprio lì. Cambi un lato senza l'altro e torna l'errore «ieri funzionava, dopo il riavvio il login è sparito» della sezione precedente. ## Docker Compose: la via indipendente Il repository di supporto linkato in cima a questa guida automatizza tutto quanto segue in uno script. Se preferisci possedere ogni file e vedere esattamente cosa viene eseguito, ecco la stessa configurazione come progetto compose indipendente — senza script di supporto. Mantieni la stessa piccola directory: ```text /opt/cliproxyapi/ ├── docker-compose.yml ├── config.yaml └── auth/ ``` Il file compose è lo stesso della sezione lato server sopra — le stesse porte legate a `127.0.0.1`, gli stessi mount, assemblato dal `docker-compose.yml` proprio del repository upstream e ridotto a ciò che serve a questa guida. Non lo ripeto qui perché deve esistere esattamente un file da tenere corretto; copialo da sopra. Il mount di `./auth` deve continuare ad atterrare dove punta `oauth.auth-dir`, altrimenti lo stato OAuth si perde a ogni ricostruzione del container. Avvia e osserva l'avvio: ```bash docker compose config docker compose up -d docker compose logs -f ``` Il primo comando merita di diventare un'abitudine: `docker compose config` rende il file effettivo senza avviare nulla — un controllo statico gratuito che intercetta errori di indentazione e percorsi di mount sbagliati prima che diventino misteri a runtime. Poi esegui il login Codex esattamente come nella sezione precedente: ```bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login ``` Un'avvertenza onesta: ogni campo del file compose sopra è verificato contro il `docker-compose.yml` del repository upstream e la configurazione già mostrata in questa guida, ma per questo aggiornamento non ho eseguito questo file esatto su una macchina reale. Se il tuo ambiente differisce — Docker rootless, un data root non standard — i percorsi dei volumi sono la prima cosa da ricontrollare. ## Lato client: configurazione Codex e Nginx Qui arriva la parte che all'inizio sembra leggermente controintuitiva. Anche dopo che il proxy ha completato correttamente l'OAuth Codex, l'app Codex locale deve comunque essere riconfigurata. Secondo la pagina ufficiale CLIProxyAPI per il client Codex, significa modificare `~/.codex/config.toml` e `~/.codex/auth.json`. È utile pensarla come due livelli di chiavi separati. Upstream il proxy conserva il vero stato OAuth e il materiale dei token che gli permette di agire per conto del tuo accesso Codex. Downstream ogni client o applicazione ha bisogno soltanto del permesso di usare il tuo proxy. Questa separazione è esattamente il motivo per cui la configurazione diventa utile quando entra in gioco più di un tool: fai l'autenticazione upstream una volta sola, poi distribuisci in modo controllato l'accesso downstream. Per un server remoto dietro il tuo dominio, considererei `config.toml` il punto in cui dici a Codex di smettere di pensare “OpenAI diretto” e iniziare a pensare “usa il mio provider proxy”: ```toml model_provider = "cliproxyapi" model = "gpt-5-codex" model_reasoning_effort = "high" [model_providers.cliproxyapi] name = "cliproxyapi" base_url = "https://codex-proxy.example.com/v1" wire_api = "responses" ``` Qui ricorrono spesso due errori. Il primo è lasciare `base_url` puntato a un esempio localhost anche se il proxy vive realmente su un server remoto. Il secondo è dimenticare `wire_api = "responses"`. La documentazione CLIProxyAPI usa esplicitamente il wire format `responses` per Codex, quindi omettere quella riga è uno dei modi più semplici per creare comportamenti strani del client che sembrano più complessi da diagnosticare di quanto siano davvero. Poi c'è `auth.json`, che la documentazione ufficiale mantiene volutamente minimale: ```json { "OPENAI_API_KEY": "" } ``` Il valore `` spesso fa esitare un momento, ma il dubbio dovrebbe riguardare **quale** chiave mettere lì, non se sia importante. Deve essere una delle chiavi presenti nell'elenco `api-keys` di `config.yaml`: la chiave proxy downstream del passaggio 6 della configurazione rapida. CLIProxyAPI tratta quelle chiavi come credenziali di autenticazione del client, quindi è ciò che il client Codex locale presenta quando comunica con il proxy. Non è ancora una vera chiave OpenAI upstream; la logica di routing vive in `config.toml`, soprattutto nel blocco provider e nel `base_url` del proxy. Se vuoi anche mettere Nginx davanti al servizio e aggiungere HTTPS, il proxying è lineare. Eviterei invece di essere creativo con il percorso `/v1/`. Mantienilo intatto e non aggiungere rewrite non necessari: ```nginx server { listen 443 ssl http2; server_name codex-proxy.example.com; location /v1/ { proxy_pass http://127.0.0.1:8317/v1/; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` Quando quell'endpoint è stabile, la sua utilità va ben oltre l'app desktop di Codex. Molti tool self-hosted hanno bisogno soltanto di un base URL OpenAI-compatible e di una credenziale simile a una API key. A quel punto il setup smette di essere “un proxy speciale per Codex” e inizia a diventare “il mio gateway AI unificato”. Le variabili d'ambiente attese da questi progetti spesso assomigliano a queste: ```bash OPENAI_BASE_URL=https://codex-proxy.example.com/v1 OPENAI_API_KEY= ``` È qui che l'architettura comincia davvero a ripagare. La parte pesante — OAuth upstream, stato account, routing dei provider ed eventuali policy multi-account — resta dentro CLIProxyAPI. Ogni progetto downstream ha bisogno solo di un endpoint stabile e della propria chiave proxy. Se in seguito cambi upstream, aggiungi altri account, modifichi la strategia di routing o sposti traffico tra tool, fai tutto in un punto invece di toccare ogni client e ogni applicazione. Diventa ancora più utile quando gestisci già tipi diversi di strumenti. Magari Codex copre il workflow di programmazione, un frontend chat self-hosted serve per il prompting quotidiano e un piccolo servizio interno di script o agent gestisce l'automazione. Senza un gateway condiviso, ognuno tende a sviluppare una propria storia di segreti. Con un proxy in mezzo, lo stato upstream di lunga durata vive in un posto solo e il lato downstream diventa molto più semplice: quale progetto riceve quale chiave e quale endpoint deve chiamare. È il punto in cui il setup smette di sembrare “un trucco speciale per Codex” e diventa parte della normale infrastruttura. ## I punti di errore più comuni Nell'uso reale, gli errori più frequenti in genere non riguardano affatto Docker. Sono più spesso cose come: - il container del proxy è attivo, ma la directory `auth/` montata non ha mai ricevuto realmente lo stato OAuth di Codex - la configurazione locale del client è stata modificata, ma `base_url` punta ancora a localhost - il reverse proxy sul dominio esiste, ma `/v1/` manca o è stato riscritto - `wire_api = "responses"` è stato omesso - qualcuno presume che `auth.json` abbia bisogno di un vero segreto OpenAI upstream e reintroduce credenziali che lì non servono Questa è anche la differenza più chiara rispetto al login diretto. Il login diretto è più semplice perché autenticazione e comportamento del client rimangono nello stesso posto. CLIProxyAPI divide invece il sistema tra runtime del servizio, stato OAuth persistente, reverse proxying e configurazione del client. Richiede più lavoro all'inizio, ma restituisce una struttura molto più riutilizzabile quando vuoi che Codex viva dentro un ambiente più ampio invece che come app locale isolata. Quindi vale la pena? Per me la risposta più pulita è questa: il login diretto è migliore quando ottimizzi per “voglio usare Codex adesso su questa macchina”. CLIProxyAPI è migliore quando ottimizzi per “voglio che Codex diventi parte di un mio livello controllato di strumenti AI”. Uno riduce l'attrito. L'altro lascia più spazio per standardizzare, riutilizzare ed estendere in seguito. E questo compromesso diventa molto più interessante nel momento in cui hai più di un consumer della stessa capacità upstream. Quando alcuni tool self-hosted iniziano a condividere lo stesso backend AI, centralizzare autenticazione e chiavi downstream tende a essere molto più pulito che spargere segreti e stato di login in ogni progetto. E una volta imboccata questa seconda strada, conviene trattare `config.yaml` e `auth/` come vero stato, non come file di setup usa e getta. Durante un recovery, la parte dolorosa raramente è scaricare di nuovo l'immagine. È ricostruire i piccoli pezzi di autenticazione e configurazione che si pensava fossero facili da ricreare. Se stai già costruendo un workflow Codex più ampio, [Cosa è cambiato nel nuovo Codex e perché sembra più un ambiente di sviluppo](/it/posts/what-changed-in-the-new-codex/) è una lettura complementare utile. E se questo proxy deve restare per un po' su un VPS, [Backup dei volumi Docker su GitHub: disaster recovery a basso costo per 1Panel](/it/posts/docker-volume-backup-github-sync/) si collega naturalmente al tema, perché stato auth e configurazione smettono di sembrare concetti astratti la prima volta che devi recuperarli in fretta.