L'installazione di Codex non è difficile, ciò che realmente può facilmente bloccare è l'integrazione: dove inserire l'API Key, come scrivere config.toml, quali sono le differenze tra Windows e macOS, perché VS Code non riesce a leggere le variabili nel terminale, se il modello debba essere fissato...

Se vuoi solo avviare Codex il prima possibile, puoi ridurre la configurazione a tre valori:

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

Dopo il completamento, Codex CLI, Desktop e l'estensione VS Code possono condividere ~/.codex/config.toml, mentre il modello viene selezionato direttamente dopo l'avvio, senza dover modificare continuamente la configurazione di integrazione per cambiare modello.

Di seguito viene completata una configurazione da zero.

Preparazione

Prima di iniziare, verifica:

  • Di esserti registrato e aver effettuato l'accesso ad Ace Data Cloud
  • Di aver creato o di possedere un'applicazione disponibile
  • Di avere Node.js e npm installati sul computer
  • Di poter usare il terminale o PowerShell
  • Di prepararti a usare almeno uno tra Codex CLI, Codex Desktop o l'estensione VS Code

Primo passo: ottenere la API Key di Ace Data Cloud

Apri l'elenco delle applicazioni Ace Data Cloud, entra in un'applicazione disponibile e copia la API Key.

Tieni presente:

  • La API Key è una credenziale sensibile, non inserirla in repository pubblici
  • Non inserire Key reali negli screenshot dei tutorial
  • Si consiglia di creare e gestire separatamente le credenziali in base all'ambiente o all'utilizzo
  • Se sospetti una compromissione, devi ruotarla o revocarla tempestivamente

Questo articolo utilizza in modo uniforme la variabile d'ambiente ACEDATACLOUD_API_KEY, evitando di scrivere direttamente credenziali in chiaro nel file di configurazione di Codex.

Secondo passo: installare Codex CLI

Installa Codex globalmente tramite npm:

npm install -g @openai/codex

Verifica dopo l'installazione:

codex --version

Se viene indicato che il comando non è stato trovato, verifica prima che la directory degli eseguibili globali di npm sia stata aggiunta a PATH, quindi riapri il terminale.

Se utilizzi principalmente VS Code, puoi anche installare l'estensione Codex pubblicata da OpenAI:

code --install-extension openai.chatgpt

CLI ed estensione VS Code condividono il file di configurazione, pertanto si consiglia di configurare prima Provider e variabili d'ambiente, quindi avviare l'editor per la verifica.

Terzo passo: impostare la variabile d'ambiente della API Key

macOS / Linux: sessione corrente del terminale

export ACEDATACLOUD_API_KEY="你的 API Key"

Questo comando ha effetto solo sulla Shell corrente e sui suoi processi figli. La variabile scomparirà dopo la chiusura del terminale.

macOS / Linux: applicazione permanente

Se utilizzi Zsh:

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

Se utilizzi Bash:

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

Non copiare ciecamente su computer condivisi configurazioni Shell contenenti Key reali; negli ambienti di team, è necessario combinare strumenti di gestione delle credenziali e strategie di privilegio minimo.

Windows PowerShell

setx ACEDATACLOUD_API_KEY "你的 API Key"

Dopo l'esecuzione, chiudi e riapri PowerShell. setx non aggiorna automaticamente i processi già aperti, pertanto il terminale esistente e VS Code potrebbero ancora non riuscire a leggere il nuovo valore.

Se devi impostarla temporaneamente solo nella sessione PowerShell corrente:

$env:ACEDATACLOUD_API_KEY="你的 API Key"

Quarto passo: creare o modificare config.toml

Codex CLI, Desktop e l'estensione VS Code condividono il seguente file di configurazione:

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

Se la directory non esiste, creala prima.

macOS / Linux:

mkdir -p ~/.codex

Quindi scrivi:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows utilizza lo stesso Provider e Base URL, ma il comando di autenticazione cambia in PowerShell:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

I tre nomi nella configurazione devono rimanere rigorosamente coerenti:

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

Anche il Base URL deve includere completamente /v1.

Quinto passo: avviare Codex e selezionare il modello

Dopo aver salvato la configurazione, riapri il terminale ed esegui:

codex

Dopo essere entrato in Codex, esegui:

/model

Verifica che il Provider corrente sia acedatacloud, quindi seleziona un modello dall'elenco disponibile.

Non è necessario fissare model nella configurazione di integrazione. Separare il Provider dalla selezione del modello può ridurre il costo di modificare ripetutamente il TOML quando si cambia modello. I modelli effettivi e l'ambito di disponibilità verranno aggiornati, pertanto devi fare riferimento a /model e al catalogo della piattaforma in tempo reale.

Sesto passo: verificare con una richiesta minima

Non chiedere subito a Codex di effettuare il refactoring dell'intero repository. Invia prima una richiesta semplice, il cui risultato possa essere valutato rapidamente, ad esempio:

请概括当前项目的目录结构，不要修改任何文件。

Successivamente, apri Ace Data Cloud Usage History, verifica che la richiesta sia arrivata e controlla lo stato e il consumo.

Se la richiesta minima ha esito positivo, prova gradualmente a leggere file, generare piani di modifica, modificare codice ed eseguire test.

Punti chiave della configurazione di VS Code

L'estensione VS Code legge lo stesso ~/.codex/config.toml, ma la possibilità di vedere la API Key dipende dall'ambiente del processo in cui l'estensione è in esecuzione.

Dopo la configurazione, chiudi completamente e riapri VS Code. Su macOS / Linux, se la variabile continua a non essere letta dopo l'avvio dall'interfaccia grafica, puoi eseguire dal terminale in cui hai già impostato la Key:

code .

Nei seguenti ambienti, devi configurare la variabile sul lato in cui l'estensione viene effettivamente eseguita:

  • Remote SSH: host remoto
  • WSL: ambiente Linux WSL
  • Dev Container: ambiente container
  • Codespaces o ambienti remoti simili: sessione remota corrispondente

Impostare la variabile solo nella Shell locale non garantisce che l'estensione remota la ottenga automaticamente.

Punti chiave della configurazione di Codex Desktop

Desktop e CLI condividono il file di configurazione, ma le applicazioni grafiche non ereditano necessariamente l'export eseguito temporaneamente nel terminale.

Se Desktop non riesce a leggere la Key:

  1. Imposta la variabile d'ambiente in modo permanente o a livello di sistema
  2. Chiudi completamente Desktop
  3. Riavvia l'applicazione
  4. Controlla nuovamente Provider e modello

Risoluzione degli errori comuni

1. 401, Unauthorized o Incorrect API Key

Ordine di controllo:

  1. Verifica che la API Key sia stata copiata completamente
  2. Verifica che il nome della variabile d'ambiente sia ACEDATACLOUD_API_KEY
  3. Verifica che il processo corrente sia stato avviato dopo l'impostazione della variabile
  4. Verifica che auth.command sia conforme al sistema operativo corrente
  5. Verifica che la credenziale sia ancora valida Non stampare l'intera Key nei log o nelle chat. Puoi controllare la variabile valutando solo “se esiste”.

macOS / Linux:

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell:

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. Il Provider non diventa acedatacloud

Conferma il percorso del file di configurazione e la gerarchia TOML. Gli errori comuni includono:

  • Il nome del file è scritto come config.toml.txt
  • È stata modificata un'altra directory utente
  • Il nome della tabella non è coerente nella scrittura
  • Errori nelle virgolette o nel formato dell'array
  • Il client non è stato riavviato dopo il salvataggio

3. La richiesta Base URL fallisce

Conferma che l'indirizzo sia:

https://api.acedata.cloud/v1

Non omettere https:// o /v1 alla fine, e non usare erroneamente l'indirizzo della pagina della console.

4. La CLI funziona, VS Code non funziona

Di solito non è un problema di configurazione del Provider, ma il processo di VS Code non ha letto la variabile d'ambiente. Avvia code . da un terminale in cui la variabile è stata impostata, oppure riavvia completamente VS Code dopo aver configurato le variabili di sistema.

5. Non è possibile leggere la Key in WSL, SSH o container

La variabile d'ambiente deve essere impostata nell'ambiente in cui Codex o l'estensione viene effettivamente eseguito. setx sull'host Windows non viene scritto automaticamente in WSL; le variabili locali non vengono nemmeno trasmesse automaticamente a host SSH remoti o container.

6. Non riesci a trovare il modello che vuoi usare

Non indovinare manualmente vecchi ID di modello. Esegui /model per visualizzare le opzioni disponibili in tempo reale e controlla i permessi dell'applicazione, il saldo e il Provider corrente.

7. La richiesta arriva ma non riesce a completare attività complesse

Prima riduci l'ambito dell'attività: lascia che Codex esegua solo analisi in lettura e produca un piano, quindi consenti gradualmente modifiche e test. Il fatto che l'integrazione del modello sia riuscita non significa che tutte le attività del repository debbano essere completate in una sola volta; le modifiche complesse richiedono comunque criteri di accettazione chiari, test e revisione umana.

Checklist di configurazione consigliata

Prima di inviare la prima attività ufficiale, conferma ogni elemento:

  • È stata ottenuta una API Key valida dall'elenco delle applicazioni
  • La Key è salvata in ACEDATACLOUD_API_KEY
  • La Key non è stata scritta nel repository Git
  • model_provider è acedatacloud
  • La Base URL è https://api.acedata.cloud/v1
  • auth.command corrisponde al sistema operativo
  • Codex o VS Code è stato completamente riavviato
  • /model può visualizzare il Provider e i modelli
  • La richiesta di test minima ha avuto successo
  • È possibile vedere i record delle chiamate corrispondenti in Usage History

Un Provider, meno configurazioni duplicate

Il punto chiave di questo metodo di integrazione non è scrivere un'altra sezione TOML, ma stabilire confini stabili:

  • La API Key è gestita tramite variabili d'ambiente
  • La connessione del Provider è gestita tramite config.toml
  • I modelli vengono selezionati in Codex in base all'attività
  • I record delle chiamate e il consumo vengono visualizzati in modo unificato nella console Ace Data Cloud
  • CLI, Desktop e VS Code condividono una stessa configurazione

Quando autenticazione, Provider e selezione del modello sono separati chiaramente, molti problemi del tipo “perché Codex non funziona di nuovo” possono essere individuati rapidamente, senza dover accedere ripetutamente, reinstallare o copiare più configurazioni.

Apri il Centro configurazione Codex per consultare le guide ufficiali per i diversi client, oppure vai all'elenco delle applicazioni per ottenere una API Key.

Riferimenti