Codex CLI

Codex CLI può collegarsi a HiAPI tramite l’importazione con un clic di CC Switch, oppure puoi configurarlo manualmente (passaggio 9). I passaggi seguenti usano gpt-6-astra come esempio; HiAPI usa il protocollo OpenAI Responses. Questo tutorial è stato verificato su Mac con Codex CLI 0.162.1; i passaggi per Mac sono il percorso principale e quelli per Windows sono riportati a parte. Puoi saltare l’installazione dei software che hai già.

1. Installare Node.js

Installa LTS 22.19 o successivo come descritto in Configurazione di Node.js e saltalo se ce l’hai già. Poi esegui i due comandi seguenti in un terminale; basta vedere i numeri di versione:

node --version
npm --version

2. Installare Codex CLI

Nel terminale appena aperto esegui ciascuna riga:

npm install -g @openai/codex
codex --version

Basta vedere un numero di versione di codex-cli; la configurazione manuale (passaggio 9) richiede la 0.134 o successiva. In Windows PowerShell usa npm.cmd install -g @openai/codex e codex.cmd --version.

3. Installare e aprire CC Switch

Scarica, installa e apri CC Switch come descritto in Installazione di CC Switch e importazione con un clic; se ce l’hai già, basta aprirlo.

Se hai già dei provider, annota prima il nome della scheda contrassegnata “In use” nella pagina Codex e, quando serve, esporta un backup SQL come descritto in Eseguire il backup della configurazione attuale.

4. Scegliere una chiave API HiAPI

Scegli o crea una chiave come descritto in Ottieni una chiave API e annotane il nome. Non serve copiare la chiave qui: l’importazione la trasporta.

5. Preparare l’importazione con un clic sul web

1. Apri la pagina di connessione Codex di HiAPI e scegli API Key setup → Codex → Command line → gpt-6-astra → macOS. Su Windows scegli Windows come sistema.

2. Fai clic su Import to CC Switch, scegli dal menu a tendina API Key il nome della chiave che hai annotato e verifica che in basso compaia Responses API · https://api.hiapi.ai/v1.

3. Fai clic su Prepare import, poi su Open CC Switch; consentilo quando il browser lo chiede.

Gli screenshot di ogni passaggio sono in Preparare l’importazione nella pagina di connessione.

6. Confermare l’importazione in CC Switch

Nella finestra “Confirm provider import” controlla i punti seguenti, lascia disattivato Switch to this provider immediately after import, poi fai clic su Import:

Tornando alla pagina Codex in CC Switch, la scheda HiAPI - gpt-6-astra significa che l’importazione è riuscita (non è ancora attiva). Vedi gli screenshot in Confermare l’importazione in CC Switch.

7. Attivare HiAPI

1. Aspetta prima che il task in corso di Codex sia terminato. Nella pagina Codex → Direct di CC Switch, fai clic sul pulsante Switch / Enable della scheda HiAPI - gpt-6-astra; HiAPI è attivo solo quando la scheda è contrassegnata “In use”. Vedi gli screenshot in Attivare HiAPI.
2. Chiudi completamente e riapri Codex perché la nuova configurazione abbia effetto. CLI e Desktop possono condividere la configurazione locale di Codex; per tornare più tardi al provider originale, passa alla sua scheda qui e riapri il client.

8. Aprire Codex, scegliere un modello e iniziare

1. Apri un nuovo terminale e vai nella cartella di progetto che vuoi usare, oppure creane prima una vuota:

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
codex

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
codex.cmd

2. La prima volta chiede se considerare attendibile la directory: verifica che il percorso sia la cartella appena scelta, poi conferma come indicato e mantieni i permessi predefiniti. Con l’importazione con un clic esegui codex direttamente; non aggiungere --profile hiapi, che serve alla configurazione manuale.

3. Nella casella di input di Codex digita /model e premi Invio. Usa i tasti freccia per scegliere GPT-6 Astra / gpt-6-astra e premi Enter; se c’è un livello di ragionamento, scegline uno e conferma, poi premi Esc per tornare indietro.

① Usa i tasti freccia per scegliere GPT-6-Astra; ② premi Enter per confermare.

4. Invia “Ciao, presentati in una frase.” Una risposta normale significa che il collegamento funziona. Se i Registri delle richieste nella console HiAPI mostrano questa richiesta, sta passando da HiAPI. Dopodiché scrivi semplicemente nella casella di input ciò che vuoi ottenere.

9. Configurazione manuale (senza CC Switch)

Salta questo passaggio se hai usato l’importazione con un clic. La configurazione manuale vale solo per Codex CLI, non per Codex Desktop.

1. Su Mac esegui le tre righe seguenti in un terminale; un file esistente con lo stesso nome viene prima salvato automaticamente come backup:

mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/hiapi.config.toml" ]; then cp "$HOME/.codex/hiapi.config.toml" "$HOME/.codex/hiapi.config.toml.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.codex/hiapi.config.toml"

2. Per un file nuovo incolla tutto il contenuto seguente; se il file esiste, aggiorna solo i campi e le tabelle con gli stessi nomi, lascia il resto e non aggiungere duplicati. I campi di primo livello devono venire prima di [model_providers.hiapi]. env_key = "HIAPI_API_KEY" è il modo in cui Codex legge una variabile d’ambiente; lascialo così.

model_provider = "hiapi"
model = "gpt-6-astra"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
requires_openai_auth = false
wire_api = "responses"

3. Premi Ctrl+O → Enter → Ctrl+X per salvare e uscire. Il nome del file deve essere hiapi.config.toml, non .toml.txt. Se hai impostato CODEX_HOME, salva il file in quella directory.

4. Torna a HiAPI Console → API Keys, fai clic sull’icona di copia accanto alla chiave e copia la chiave API HiAPI completa. Nello stesso terminale in cui avvierai Codex esegui il comando seguente (sostituisci YOUR_HIAPI_API_KEY con la tua chiave API HiAPI e mantieni le virgolette), poi vai nella directory del tuo progetto e avvia:

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex --profile hiapi

5. Su Windows usa PowerShell per creare la directory $env:USERPROFILE\.codex, apri hiapi.config.toml nel Blocco note e incolla lo stesso TOML; prima fai il backup di un file esistente. In Save as scegli “All files” e UTF-8 e verifica che non ci sia il suffisso .txt. Nella stessa finestra PowerShell e nella stessa directory di progetto esegui:

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex.cmd --profile hiapi

La variabile d’ambiente vale solo per il terminale corrente; impostala di nuovo dopo aver chiuso il terminale. Una volta avviato, scegli un modello come al passaggio 8.

Risoluzione dei problemi

Qui sono elencati solo i problemi specifici di Codex CLI. Per gli errori comuni come 401, 404 e 429, vedi Errori comuni.