Integrazione dell'API Codex: guida completa alla configurazione

Kimi Open Platform supporta nativamente Responses API usata da Codex, quindi Codex può utilizzare direttamente i modelli Kimi, senza conversione di protocollo né proxy locale. Questa guida illustra la configurazione completa su macOS e Windows.

Codex è l'agente per la programmazione di OpenAI, pensato per lavorare su repository e terminale. Può:

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

• Comprendere basi di codice sconosciute: cercare file, seguire le chiamate e spiegare i componenti.

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

• Eseguire il debug e risolvere i problemi: riprodurre gli errori, proporre modifiche ed eseguire verifiche.

• Automatizzare le attività di routine: aggiornare file ed eseguire flussi di lavoro documentati previa approvazione.

1. Apri Terminale su macOS o PowerShell su Windows.

2. Esegui il comando per il tuo sistema operativo:

macOS:

Windows:

1. Attendi il completamento dell'installazione, quindi chiudi e riapri Terminale o PowerShell.

2. Esegui:

1. Seleziona Accedi con ChatGPT, completa l'accesso nel browser e torna a Terminale o PowerShell. Per questo accesso è sufficiente un account ChatGPT gratuito; non è richiesto alcun abbonamento a pagamento. Il percorso esterno Kimi configurato in seguito non utilizza la fatturazione OpenAI.

1. Visita la pagina di download ufficiale all'indirizzo https://chatgpt.com/download e scarica l'app desktop per macOS o Windows. Codex è incluso come modalità di lavoro nell'app desktop ChatGPT: l'app da scaricare si chiama ChatGPT.

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

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

4. Inserisci Di' ciao in una frase. e invia il messaggio.

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

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

Vantaggi:

• Configurazione rapida senza ulteriori passaggi di configurazione.

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

• Meno servizi e credenziali da gestire

Limitazioni:

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

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

• Richiede l'accesso con un account ChatGPT. I piani gratuiti includono un accesso limitato a Codex, ma per un uso regolare è generalmente necessario un piano ChatGPT a pagamento (come Plus o Pro) oppure una chiave API OpenAI con fatturazione a consumo.

Un'API esterna offre più modelli tra cui scegliere e ti permette di usare un account esistente presso un altro fornitore. La Kimi Open Platform supporta nativamente la Responses API usata da Codex, quindi la connessione è diretta: non è necessario alcun router locale.

Vantaggi:

• Accesso ai modelli di altri fornitori

• Maggiore flessibilità per diverse attività di programmazione

• Controllo separato dell'account e dell'utilizzo dell'API esterna

• Non è richiesto alcun abbonamento GPT. Ideale per scenari sensibili ai costi.

Limitazioni:

• Richiede una chiave API e una piccola modifica alla configurazione

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

Se desideri la configurazione più rapida, inizia con un modello integrato. Se hai già un account API esterno o vuoi una scelta più ampia di modelli, prosegui con la guida seguente.

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

Nota: la Kimi API è un servizio a pagamento con fatturazione a consumo. Prima di eseguire i test, assicurati che il tuo account disponga di saldo: controllalo o ricaricalo nella sezione Fatturazione della console. Una nuova chiave API da sola non abilita le chiamate se il saldo dell'account è zero.

Codex legge la chiave API da una variabile d'ambiente. Non scrivere la chiave in config.toml.

macOS e Linux:

Per evitare che la chiave finisca nella cronologia della shell, inseriscila come segue:

Questo vale solo per la sessione del terminale corrente. Per renderla persistente, aggiungi il comando export a ~/.zshrc (o a ~/.bashrc se usi bash su Linux). Il file memorizza la chiave in testo semplice: imposta le autorizzazioni di conseguenza.

Windows (PowerShell):

Sostituisci YOUR_KIMI_API_KEY con la chiave copiata nel passaggio 1. Per renderla persistente tra le sessioni, aggiungi KIMI_API_KEY in Impostazioni > Sistema > Informazioni > Impostazioni di sistema avanzate > Variabili d'ambiente.

Apri il file di configurazione di Codex a livello utente: ~/.codex/config.toml su macOS e Linux (su Windows: %USERPROFILE%\.codex\config.toml). Se il file non esiste ancora, crealo.

Aggiungi la configurazione seguente. Se model o model_provider esistono già, sostituiscine i valori ed elimina tutte le righe che iniziano con model_catalog_json = o service_tier = (le righe residue di altre configurazioni possono sovrascrivere i metadati del modello o il routing):

Se la chiave API è stata creata sulla piattaforma cinese (platform.moonshot.cn), usa invece https://api.moonshot.cn/v1 come valore di base_url: le chiavi non sono intercambiabili tra le due piattaforme.

Mantieni invariate le impostazioni esistenti non correlate (come notify, approvazione, sandbox, progetto e preferenze dell'interfaccia) e non rimuovere altre sezioni dei fornitori, come [model_providers.openai].

Funzione di ogni impostazione:

Codex legge config.toml solo all'avvio, quindi esci completamente da tutte le sessioni Codex in esecuzione. Poi accedi alla directory del progetto e avvia Codex:

Dopo l'avvio, verifica che Codex CLI indichi kimi-k3 come modello corrente:

Invia una richiesta semplice, ad esempio hello. Una risposta normale conferma che Codex è connesso tramite la Kimi Responses API.

Per confermare che la risposta provenga effettivamente da Kimi, verifica che nella sessione sia indicato kimi come provider, ad esempio digitando /status nella sessione Codex. Internamente, Codex invia le richieste a POST https://api.moonshot.ai/v1/responses.

L'app desktop usa la stessa configurazione a livello utente della CLI. Completa prima i passaggi 1-3 precedenti, quindi:

Su macOS, premi Command+Q per chiudere completamente l'app desktop. Non basta chiudere solo la finestra.

Su Windows, chiudi tutte le finestre dell'app desktop e verifica che l'app non sia più in esecuzione nell'area di notifica.

Riapri l'app desktop affinché ricarichi ~/.codex/config.toml, quindi apri una cartella di progetto.

Apri il selettore dei modelli e seleziona kimi-k3. L'interfaccia potrebbe mostrare Custom anziché il nome del modello: è previsto. I provider personalizzati definiti in config.toml non vengono sempre visualizzati per nome nell'elenco dei modelli desktop, ma le richieste continueranno a usare il kimi-k3 configurato.

Invia una richiesta semplice, come hi: una risposta normale indica che la connessione di base funziona:

Ora invia un'attività che sfrutti le capacità agent di Codex:

Se Desktop continua a generare una risposta finale dopo il ritorno dei risultati degli strumenti, le chiamate al modello e agli strumenti funzionano correttamente.

Le sessioni Codex si connettono a un daemon app-server in background, il cui ambiente viene acquisito all'avvio del daemon, non all'avvio di una sessione. Se il daemon era già in esecuzione quando hai impostato KIMI_API_KEY, non vedrà la variabile anche se il terminale corrente la mostra come impostata. Su macOS, scrivi la variabile nell'ambiente della sessione GUI e riavvia il daemon:

Quindi avvia di nuovo Codex. Su Windows, disconnettiti e accedi nuovamente, oppure riavvia completamente l'app desktop, dopo aver impostato la variabile a livello di sistema.

La chiave API non è valida oppure la chiave e base_url appartengono a piattaforme diverse: le chiavi API create su platform.kimi.ai funzionano solo con https://api.moonshot.ai/v1, mentre quelle create su platform.moonshot.cn funzionano solo con https://api.moonshot.cn/v1. Verifica inoltre che KIMI_API_KEY sia disponibile nell'ambiente usato per avviare Codex o Desktop. Per la CLI, controllala nel terminale da cui avvii Codex:

La richiesta include il parametro search_context_size, che non è ancora supportato: rimuovilo. Codex non invia questo parametro per impostazione predefinita e lo strumento web_search integrato funziona subito.

base_url non è corretto: assicurati che sia esattamente https://api.moonshot.ai/v1 (con il suffisso /v1). Se in precedenza ti sei connesso tramite CC Switch o un altro router locale, verifica anche che base_url non punti più a un indirizzo locale come http://127.0.0.1:....

Hai raggiunto un limite di frequenza o di concorrenza. Controlla le quote del tuo piano nella sezione Limits della console della piattaforma Kimi API.

kimi-k3 non è incluso nel catalogo di modelli integrato di Codex. Questo avviso è previsto e non influisce sull'utilizzo: model_context_window = 1048576 del Passaggio 3 garantisce già che la finestra di contesto venga considerata pari a 1M.

Codex legge config.toml solo all'avvio: chiudilo e riavvialo. Verifica inoltre di aver modificato il file ~/.codex/config.toml a livello utente e che nessun flag -c o profilo lo stia sovrascrivendo. Se in precedenza ti sei connesso tramite CC Switch, disattiva anche Codex in Impostazioni > Routing: altrimenti continuerà a riscrivere config.toml, sovrascrivendo la nuova configurazione.

L'uso di Kimi nei flussi di lavoro API di Codex può migliorare le attività di programmazione, debug e sviluppo. Le sue funzionalità avanzate aiutano a generare risposte accurate, gestire istruzioni complesse e risolvere i problemi più rapidamente. Ecco i principali vantaggi dell'uso di Kimi nei flussi di lavoro di Codex per aumentare produttività ed efficienza.

• Comprensione del codice con contesto esteso

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

• Documentazione e analisi del repository migliori

Con Kimi è possibile esaminare rapidamente documenti di progetto, note tecniche e repository. I dettagli importanti sono più facili da trovare senza dover consultare manualmente ogni file. Gli sviluppatori possono comprendere meglio l'intero progetto in meno tempo.

• Sviluppo con IA conveniente

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

• Recupero delle informazioni più rapido

Le informazioni utili possono essere individuate rapidamente in codebase, set di dati e file di progetto di grandi dimensioni. Si dedica meno tempo alla ricerca di risposte o riferimenti nelle risorse. È così possibile concentrarsi maggiormente su programmazione, test e miglioramento del progetto.

• Automazione del flusso di lavoro migliorata

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

Un flusso di lavoro API Codex CLI configurato riunisce in un unico contesto l'ispezione del repository, le modifiche, i comandi e la revisione. Codex può creare lo scheletro dei file, spiegare moduli poco familiari, riprodurre i malfunzionamenti, proporre test ed eseguire verifiche approvate. Il supporto per provider esterni amplia la scelta dei modelli, ma non elimina la responsabilità della revisione.

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

Un utilizzo affidabile di Codex API deriva dal test di ogni livello nell'ordine corretto: crea e finanzia il tuo account Kimi, imposta la chiave API nell'ambiente, salva la configurazione del provider a livello utente, riavvia Codex e verifica con un prompt semplice prima di passare alle attività degli agenti IA. Conserva la chiave nella variabile d'ambiente anziché in config.toml e non pubblicare mai una chiave reale.