Integrazione dell'API di Codex: guida completa alla configurazione

Collegare modelli esterni a Codex è un processo complesso. Questa guida usa Kimi API come esempio pratico per guidarti attraverso la configurazione completa dell'API di Codex su macOS e Windows.

Che cos'è Codex?

Codex è l'agente di coding di OpenAI per lavorare su repository e terminale. Può:

• Scrivere codice: creare funzioni, test, script e funzionalità mirate.

• Comprendere codebase sconosciute: cercare file, tracciare chiamate e spiegare componenti.

• Revisionare il codice: individuare probabili difetti, assunzioni rischiose, test mancanti e problemi di sicurezza.

• Eseguire debug e risolvere problemi: riprodurre errori, proporre modifiche ed eseguire controlli.

• Automatizzare attività di routine: aggiornare file ed eseguire flussi di lavoro documentati con la tua approvazione.

Installare Codex ed effettuare l'accesso

Parte 1: installare Codex CLI

1. Apri Terminal su macOS o PowerShell su Windows.

2. Esegui il comando corrispondente al tuo sistema operativo:

macOS:

Windows:

1. Attendi il termine dell'installazione, quindi chiudi e riapri Terminal o PowerShell.

2. Esegui:

1. Seleziona Accedi con ChatGPT, completa l'accesso dal browser e torna a Terminal o PowerShell.

Parte 2: installare l'app desktop di Codex

1. Visita la pagina ufficiale dell'app desktop di Codex.

2. Scarica l'app desktop di ChatGPT per macOS o Windows.

3. Installa e apri l'app, quindi accedi con il tuo account ChatGPT.

4. Crea un'attività o apri un progetto e seleziona Codex come modalità di lavoro.

5. Digita Say hello in one sentence. e invia il messaggio.

Modelli AI integrati vs API LLM esterne

Dopo aver installato Codex, puoi usare i suoi modelli AI integrati oppure collegare un'API LLM esterna compatibile. L'opzione migliore dipende da quanta configurazione, flessibilità e gestione degli account desideri.

Usare i modelli integrati di Codex

I modelli integrati offrono l'esperienza più semplice. Puoi selezionare un modello disponibile e iniziare a programmare senza eseguire un altro servizio o configurare una chiave API separata.

Vantaggi:

• Configurazione rapida senza passaggi aggiuntivi.

• Integrazione diretta con gli strumenti e le funzionalità di Codex

• Meno servizi e credenziali da gestire

Limiti:

• Puoi scegliere solo tra i modelli disponibili per il tuo account

• Minore flessibilità se vuoi usare un modello di un altro provider

• Richiede un abbonamento GPT e il costo di utilizzo è relativamente alto.

Usa un'API LLM esterna

Un'API esterna offre più scelta di modelli e ti permette di usare un account già esistente con un altro provider. Tuttavia, alcuni modelli richiedono una configurazione aggiuntiva o uno strumento di compatibilità locale prima che Codex possa utilizzarli.

Vantaggi:

• Accesso a modelli di altri provider

• Maggiore flessibilità per diversi task di programmazione

• Controllo separato sull'account API esterno e sull'utilizzo

• Non richiede un abbonamento GPT. Ideale per scenari sensibili ai costi.

Limiti:

• Richiede una chiave API e una configurazione aggiuntiva

• Potrebbe richiedere un router locale che deve rimanere in esecuzione

• Fatturazione, compatibilità, privacy e risoluzione dei problemi dipendono dal provider esterno

Se vuoi la configurazione più veloce, inizia con un modello integrato. Se hai già un account API esterno o vuoi più scelta di modelli, prosegui con la seguente guida. Usa Kimi API come esempio pratico di connessione di un modello esterno a Codex.

Come connettere un'API LLM esterna a Codex: esempio con Kimi

Configurazione su macOS

Passaggio 1: apri il terminale A e verifica Node.js e npm

Dove: premi Command+Space, digita Terminal e premi Invio. Considera questa prima finestra come Terminale A.

Esegui:

Risultato atteso: ogni comando stampa una versione. Output come v22.x.x per Node.js e 10.x.x per npm sono solo esempi, non requisiti minimi.

Se un comando non viene trovato: apri un browser, visita https://nodejs.org/en/download, scarica il pacchetto .pkg LTS per macOS, apri Download nel Finder, fai doppio clic sul pacchetto e accetta le impostazioni predefinite del programma di installazione. Chiudi il Terminale con Command+Q, riapri il Terminale A ed esegui di nuovo entrambi i comandi di versione. Non proseguire finché entrambi i comandi non restituiscono le versioni.

Passaggio 2: crea una chiave API Kimi

Apri la piattaforma Kimi API. Crea una chiave API dalla console, quindi salvala in un password manager o in un gestore di segreti. Se la console mostra la chiave completa una sola volta, copiala prima di lasciare la pagina.

Passaggio 3: imposta MOONSHOT_API_KEY nel Terminale A

Dove: torna al Terminale A.

Esegui:

Sostituisci solo YOUR_KIMI_API_KEY con la chiave Kimi reale. Mantieni invariati i segni di virgolette e il nome della variabile MOONSHOT_API_KEY.

Risultato atteso: il comando export non stampa alcun output. Verifica che un valore esista senza mostrarlo:

Il terminale dovrebbe stampare Kimi key is set.

Passaggio 4: testa Kimi direttamente dal Terminale A

Dove: continua a usare il Terminale A, dove MOONSHOT_API_KEY è impostata.

Esegui:

Risultato atteso: appare una risposta JSON contenente il testo generato in choices[0].message.content.

Passaggio 5: apri il Terminale B e avvia il router nel Terminale A

Dove: con il Terminale A attivo, premi Command+N per aprire una seconda finestra. Chiama la nuova finestra Terminale B. Torna al Terminale A prima di eseguire il comando del router.

Esegui nel Terminale A:

Non sostituire l'URL di base o il modello. $MOONSHOT_API_KEY deve rimanere il riferimento alla variabile, non una seconda copia incollata della chiave.

Possibile richiesta al primo avvio: npx potrebbe mostrare Need to install ... Ok to proceed? (y). Controlla prima il nome del pacchetto e la fonte terza collegata. Digita y e premi Invio solo se accetti quel pacchetto. Non viene affermato che qui sia stata testata una versione esatta del pacchetto.

Risultato atteso: il processo rimane in esecuzione e segnala che è in ascolto su 127.0.0.1:8787. Lascia aperto il Terminale A.

In caso di errore: se npm non riesce a scaricare il pacchetto, verifica l'accesso a Internet e riesegui node --version e npm --version. Se la porta 8787 è già in uso, interrompi l'altro processo locale che la utilizza oppure torna al suo terminale e premi Ctrl+C, quindi riesegui il comando del router.

Passaggio 6: testa localhost dal Terminale B

Dove: clicca sul Terminale B.

Esegui:

Risultato atteso: il Terminale B stampa eventi di streaming simili a Responses o un output contenente un saluto di una frase. La sequenza esatta degli eventi può variare a seconda della versione del router.

Se vedi Connection refused: controlla il Terminale A. Se il router si è interrotto, riesegui il comando del Passaggio 5 e lascialo aperto. Se il Terminale A mostra un 401 a monte, reimposta lì MOONSHOT_API_KEY e riavvia il router.

Passaggio 7: crea e modifica la configurazione Codex su macOS

Dove: continua a usare il Terminale B.

Esegui:

Questi comandi creano, se necessario, il file di configurazione a livello utente, eseguono il backup di un file esistente e aprono ~/.codex/config.toml in TextEdit.

Se il file è vuoto

Incolla la configurazione completa seguente:

Se il file contiene già delle impostazioni

Non incollare la configurazione completa sopra il file esistente. Mantieni le impostazioni non correlate e aggiorna singolarmente le righe richieste.

1. Trova la riga che inizia con model = e sostituisci l'intera riga con:

1. Trova la riga che inizia con model_provider = e sostituisci l'intera riga con:

1. Trova la riga che inizia con model_context_window = e sostituisci l'intera riga con:

1. Trova la riga che inizia con model_supports_reasoning_summaries = e sostituisci l'intera riga con:

Se una di queste quattro impostazioni non esiste già, aggiungi la riga mancante vicino all'inizio del file.

1. Trova ed elimina qualsiasi riga intera che inizia con:

Trova ed elimina anche qualsiasi riga intera che inizia con:

1. Aggiungi la sezione sottostante:

Non rimuovere altre sezioni dei provider, come [model_providers.openai].

Mantieni le impostazioni esistenti non correlate, incluse le preferenze di notify, approvazione, sandbox, progetto e interfaccia. Non copiare la riga notify di un altro utente perché potrebbe contenere un percorso assoluto specifico del computer.

Premi Command+S per salvare il file, quindi chiudi TextEdit.

Passaggio 8: riavvia Codex ed esegui il test completo su macOS

Dove: mantieni il router in esecuzione nel Terminale A. Nel Terminale B, chiudi qualsiasi sessione Codex esistente con Ctrl+C, quindi prepara una cartella usa e getta.

Esegui nel Terminale B:

Test: digita hello. e premi Invio. Una risposta di una frase conferma un percorso di richiesta di base.

Configurazione Windows

Usa due finestre PowerShell indipendenti. PowerShell A memorizza la chiave Kimi della sessione corrente ed esegue il router. PowerShell B testa localhost, modifica la configurazione e avvia Codex. La variabile utente persistente supporta le finestre future; l'assegnazione della sessione corrente rende la chiave immediatamente disponibile in PowerShell A.

Passaggio 1: apri PowerShell A e verifica Node.js e npm

Dove: premi il tasto Windows, digita PowerShell e apri Windows PowerShell. Chiama questa finestra PowerShell A.

Esegui:

Risultato atteso: entrambi i comandi stampano le versioni. Valori come v22.x.x e 10.x.x sono solo esempi, non requisiti minimi.

Se un comando non viene riconosciuto: apri un browser e visita https://nodejs.org/en/download. Scarica il file .msi LTS per Windows, apri Download in Esplora file, fai doppio clic sull'installer, accetta le impostazioni predefinite e assicurati che l'installer mantenga l'opzione che aggiunge Node.js al PATH. Chiudi tutte le finestre di PowerShell, riapri PowerShell A ed esegui di nuovo entrambi i comandi.

Passaggio 2: crea una chiave API Kimi

Apri la Kimi API platform. Crea una chiave API dalla console, poi salvala in un password manager o in un secret manager. Se la console mostra la chiave completa una sola volta, copiala prima di lasciare la pagina.

Passaggio 3: imposta variabili persistenti e per la sessione corrente in PowerShell A

Dove: torna a PowerShell A.

Esegui:

Sostituisci solo YOUR_KIMI_API_KEY in entrambe le righe con la stessa chiave Kimi. Lascia invariati MOONSHOT_API_KEY, User, le virgolette e la punteggiatura. La prima riga memorizza il valore per i processi futuri. La seconda riga lo rende disponibile immediatamente in PowerShell A.

Risultato atteso: entrambi i comandi non restituiscono alcun output. Verifica la presenza senza stampare la chiave:

PowerShell dovrebbe stampare True.

Se stampa False: esegui di nuovo l'assegnazione per la sessione corrente usando virgolette dritte. Se la scrittura a livello User è stata bloccata da una policy, prosegui con il valore della sessione corrente per questa guida e chiedi al tuo amministratore come devono essere memorizzate le variabili d'ambiente utente. Revoca qualsiasi chiave esposta nei log o in testo condiviso.

Passaggio 4: testa Kimi direttamente da PowerShell A

I riferimenti API possono mostrare POST URL, ma non digitare mai POST https://... da solo in PowerShell. Usa Invoke-RestMethod -Method Post come mostrato qui.

Dove: resta in PowerShell A, dove $env:MOONSHOT_API_KEY è impostata.

Esegui:

Non sostituire l'endpoint, il modello o il nome della variabile. PowerShell legge la chiave da $env:MOONSHOT_API_KEY.

Risultato atteso: l'ultima riga stampa un saluto di una frase da choices[0].message.content.

Se ricevi 401: verifica che la chiave provenga dalla console globale .ai, revocala e ricreala se necessario, esegui di nuovo entrambe le assegnazioni del Passaggio 3 e riprova. Se il modello viene rifiutato, verifica che l'ID sia esattamente kimi-k2.7-code e controlla l'accesso al modello nella console Kimi.

Passaggio 5: apri PowerShell B e avvia il router in PowerShell A

Dove: premi di nuovo il tasto Windows, digita PowerShell e apri una seconda finestra di Windows PowerShell. Chiamala PowerShell B. Torna a PowerShell A per il comando del router.

Esegui in PowerShell A:

Lascia invariata $env:MOONSHOT_API_KEY; non incollare la chiave direttamente nel comando.

Possibile prompt al primo avvio: npx potrebbe mostrare Need to install ... Ok to proceed? (y). Verifica il pacchetto e la fonte di terze parti. Digita y e premi Invio solo se lo accetti. Non viene indicata alcuna versione esatta del pacchetto come testata.

Risultato atteso: il processo rimane aperto e segnala che è in ascolto su 127.0.0.1:8787. Tieni aperta PowerShell A.

Se fallisce: esegui node --version e npm --version in PowerShell A. Se uno dei due fallisce, ripeti il Passaggio 1. Se la porta 8787 è occupata, ferma l'altro router con Ctrl+C nella sua finestra, poi esegui di nuovo il comando.

Passaggio 6: testa localhost da PowerShell B

Dove: fai clic su PowerShell B. Non fermare il router in PowerShell A.

Esegui:

Non sostituire l'URL localhost. Punta al router in PowerShell A.

Risultato atteso: PowerShell restituisce un oggetto simile a Responses o un output contenente il saluto. I campi esatti possono variare a seconda della versione del router.

Se la connessione viene rifiutata: controlla PowerShell A e riavvia il comando del Passaggio 5 se il router è terminato. Se PowerShell A mostra un errore di autenticazione upstream, premi Ctrl+C, reimposta $env:MOONSHOT_API_KEY e riavvia il router. Non aggiungere un header di autorizzazione locale per il quick start predefinito di @codeproxy/cli.

Passaggio 7: crea e modifica la configurazione Codex per Windows

Dove: continua a usare PowerShell B. La configurazione del provider deve trovarsi in $HOME\.codex\config.toml, non all'interno di una cartella di progetto.

Esegui:

I comandi creano la directory utente, eseguono il backup di una configurazione esistente, creano il file se assente e lo aprono in Blocco note.

In Blocco note: incolla questa configurazione predefinita completa, rimuovendo eventuali chiavi di modello o provider duplicate e in conflitto se il file le contiene già:

Non sostituire kimi-proxy, l'URL localhost o responses. Premi Ctrl+S e chiudi Blocco note.

Verifica il nome del file: Esegui:

Risultato atteso: Name è esattamente config.toml, non config.toml.txt, e Length è maggiore di zero.

Se Blocco note ha aggiunto .txt: In Blocco note, scegli File → Salva con nome, imposta Tipo file su Tutti i file, digita config.toml e salvalo in $HOME\.codex. Riesegui Get-Item. Se Codex ignora il provider, verifica di aver modificato il percorso a livello utente e rimuovi eventuali chiavi TOML duplicate.

Passaggio 8: riavvia Codex ed esegui il test completo su Windows

Dove: Lascia PowerShell A e il suo router in esecuzione. Chiudi completamente qualsiasi app o sessione Codex. Chiudi PowerShell B, riaprilo con il tasto Windows → digita PowerShell → apri Windows PowerShell, e crea una cartella usa e getta.

Esegui nella finestra PowerShell B riaperta:

Test: Digita hello. e premi Invio. Una risposta di una frase conferma un percorso di richiesta di base.

Usa Kimi nell'app desktop Codex

Prima di continuare, completa i passaggi 1–7 della configurazione per macOS o Windows relativa al router locale e a config.toml. Non è necessario completare prima il test da CLI, ma il router deve rimanere in esecuzione mentre usi Kimi nell'app desktop.

Passaggio 1: mantieni in esecuzione il router locale

Mantieni aperto Terminal A o PowerShell A con @codeproxy/cli in esecuzione su:

Passaggio 2: verifica la configurazione del provider

Apri il file di configurazione di Codex a livello utente.

Su macOS, esegui:

Su Windows, esegui:

Verifica che il file contenga queste impostazioni di primo livello:

Passaggio 3: riavvia completamente l'app desktop

Su macOS, premi Command+Q per chiudere completamente l'app desktop. Chiudere solo la finestra non è sufficiente.

Su Windows, chiudi tutte le finestre dell'app desktop e verifica che l'app non sia più in esecuzione nella barra delle applicazioni.

Riapri l'app desktop e apri una cartella di progetto.

Passaggio 4: mantieni selezionato Custom

Il selettore modelli dell'app desktop potrebbe mostrare Custom invece di Kimi K2.7 Code. È normale.

I provider personalizzati definiti in config.toml non sempre vengono mostrati con il loro nome nell'elenco modelli dell'app desktop. Non selezionare un modello OpenAI come GPT-5.6 Sol se vuoi usare il provider Kimi. Mantieni selezionato Custom.

Potresti anche vedere questo avviso:

Si tratta di un avviso, non di un errore di connessione. Le seguenti impostazioni forniscono già le informazioni sul modello necessarie per il normale utilizzo:

Passaggio 5: verifica il percorso di richiesta dell'app desktop

Invia questo prompt nell'app desktop:

Osserva Terminal A o PowerShell A mentre l'app desktop risponde. Se la finestra di Terminal A riceve una nuova richiesta e l'app desktop restituisce una risposta, l'app desktop sta usando il percorso Kimi locale.

Risoluzione dei problemi di integrazione più comuni

zsh: command not found: POST

POST URL è una notazione della documentazione API, non un comando. Su macOS, copia l'esempio completo di curl. Su Windows, copia l'esempio completo di Invoke-RestMethod -Method Post.

Connessione rifiutata sulla porta 8787

Torna a Terminal A o PowerShell A. Se non è in esecuzione alcun processo del router, imposta la variabile Kimi della sessione corrente e riesegui il comando documentato npx @codeproxy/cli .... Lascia aperta quella finestra, poi ripeti il test su localhost nella finestra B.

Una risposta 401

Leggi la finestra del router per individuare il passaggio che fallisce. Un 401 upstream da Kimi di solito significa che MOONSHOT_API_KEY non è valida, è stata revocata o proviene dall'account regionale sbagliato. Revoca la chiave nella console globale .ai, creane una nuova, reimposta la variabile della sessione corrente e riavvia il router. Il percorso predefinito del router non prevede alcun controllo bearer in ingresso. Un 401 locale con un altro adapter può indicare che il suo CODEX_KIMI_PROXY_KEY opzionale è mancante o non valido.

Errori di parametro o strumento non supportato

Il router potrebbe inoltrare un campo che Kimi non accetta. I campi di sampling devono rimanere non impostati; se vengono inviati, devono usare i valori fissi accettati. Verifica che tool_choice sia auto o none e che l'adapter conservi reasoning_content. Se il test multi-step continua a fallire, smetti di usare quella versione del router e scegline o aggiornane una con supporto esplicito per Kimi.

Codex ignora il provider

Apri direttamente il file utente: esegui open -e "$HOME/.codex/config.toml" su macOS oppure notepad "$HOME\.codex\config.toml" su Windows. Verifica che ci sia un solo model_provider = "kimi-proxy" a livello superiore, una sola tabella provider, l'URL base localhost e wire_api = "responses". Salva, esci completamente da Codex e riavvialo. Non impostare la selezione del provider solo in un .codex/config.toml di progetto.

npx non riesce ad avviare il router

Esegui node --version e npm --version nella finestra A del router. Se uno dei due comandi fallisce, installa il pacchetto Node.js LTS da nodejs.org/download, chiudi e riapri il terminale, quindi riprova. Se npx chiede il permesso di scaricare il pacchetto, verifica il pacchetto e la fonte prima di digitare y.

Vantaggi dell'utilizzo di Kimi API

Utilizzare Kimi nei flussi di lavoro API di Cursor può migliorare la scrittura del codice, il debug e le attività di sviluppo. Le sue funzionalità avanzate aiutano a generare risposte accurate, gestire istruzioni complesse e risolvere i problemi più rapidamente. Ecco i principali vantaggi dell'utilizzo di Kimi nei flussi di lavoro di Cursor per aumentare produttività ed efficienza.

• Comprensione del codice su contesti lunghi

Kimi può elaborare grandi quantità di codice e informazioni contemporaneamente. Riconosce le relazioni tra file diversi e sezioni del progetto in modo più efficace. Di conseguenza, lavorare con codebase ampie o complesse diventa molto più semplice.

• Migliore analisi di documentazione e repository

Documenti di progetto, note tecniche e repository possono essere esaminati rapidamente con Kimi. È più facile trovare i dettagli importanti senza dover controllare manualmente ogni file. Gli sviluppatori possono ottenere una comprensione più chiara dell'intero progetto in meno tempo.

• Sviluppo AI conveniente

Kimi offre un'opzione pratica ed economica per gestire molte attività di sviluppo. Un supporto AI efficace è disponibile senza dipendere interamente da modelli più costosi. I team possono migliorare la produttività complessiva mantenendo le spese sotto controllo.

• Recupero delle informazioni più rapido

Le informazioni utili possono essere individuate rapidamente in codebase, dataset e file di progetto di grandi dimensioni. Si perde meno tempo a cercare risposte o riferimenti tra le risorse. Ci si può concentrare maggiormente su codifica, test e miglioramento del progetto.

• Automazione del flusso di lavoro migliorata

Le attività di sviluppo ripetitive diventano più facili da gestire e completare con Kimi. Può aiutare nella generazione di codice, nella revisione dei contenuti e nelle attività di progetto di routine. I flussi di lavoro quotidiani rimangono organizzati, efficienti e più produttivi nel tempo.

Come Codex migliora il flusso di lavoro di sviluppo

Un flusso di lavoro API Codex CLI configurato collega l'ispezione del repository, la modifica, i comandi e la revisione in un unico contesto. Codex può creare la struttura dei file, spiegare moduli non familiari, riprodurre errori, proporre test ed eseguire controlli approvati. Il supporto per provider esterni aggiunge la possibilità di scegliere il modello ma non elimina la responsabilità della revisione.

Inizia ogni attività con un obiettivo circoscritto. Chiedi a Codex di ispezionare prima di modificare, esamina le modifiche proposte, approva solo i comandi che comprendi, esegui i test del repository e ispeziona il diff finale. Considera il codice generato come un contributo non affidabile finché non supera revisione e verifica.

Conclusione

Un utilizzo affidabile dell'API Codex si ottiene testando ogni livello in ordine: autenticare Codex, chiamare Kimi direttamente, avviare e testare localhost, salvare la configurazione del provider a livello utente, eseguire un prompt di sola lettura e completare un'attività su file e strumenti. Conserva la chiave Kimi reale insieme al router, tieni i segreti fuori dai file condivisi e ferma il router quando hai finito.