Guida a Codex — installare Codex CLI, usare una chiave API senza abbonamento e quanto costa una singola attività

Codex è l'agente di programmazione IA (coding agent) di OpenAI. Il modo più semplice per usarlo è installare Codex CLI nel terminale (npm install -g @openai/codex), eseguire codex nella cartella del progetto e dirgli in cinese cosa deve fare. Puoi iniziare in due modi: accedere con un piano ChatGPT (Plus, Pro, Business e così via) e usare la quota del piano, oppure eseguirlo con una chiave API e pagare in base ai token. Quasi tutte le guide in cinese descrivono solo il primo metodo; questa tratta il secondo: come eseguire Codex CLI senza abbonamento, scegliere il modello in base all'attività e calcolare il costo effettivo di un'attività.

Codex non è uno strumento per incollare codice in una chat: è un agente che legge e modifica file nel progetto ed esegue test e comandi. Configura con /permissions quali azioni può svolgere direttamente senza conferma dopo l'avvio.

I due modi di usare Codex

Quando usi una chiave API, i costi vengono calcolati separatamente dalla quota del piano ChatGPT. Puoi usare direttamente una chiave API OpenAI, ma questa guida tratta il collegamento a un endpoint compatibile con Responses API: la stessa chiave può passare da GPT-6 Astra a GPT-5.6 Terra. Ad esempio, GPT-5.6 Sol ha prezzi ufficiali OpenAI di $5,00 / $30,00 (attualmente OpenAI offre il modello al prezzo promozionale di $4,00 / $20,00; la pagina ufficiale dei prezzi indica che questo prezzo si applica almeno fino al 21 novembre 2026); qui il costo per 1M di token è $2,00 / $12,00 (le tariffe vengono lette direttamente dal catalogo del sito, non inserite manualmente).

Installare Codex CLI: npm o Homebrew

# npm（有 Node.js 就能用，macOS / Linux / Windows 通用）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

Entrambi sono metodi d'installazione riportati nel README ufficiale OpenAI; su Windows puoi usare la stessa riga npm. Dopo l'installazione, esegui codex nella cartella del progetto per avviarlo. Se prevedi di accedere con ChatGPT, qui hai finito e puoi saltare la configurazione seguente.

Usare una chiave API: aggiungere una sezione a config.toml

Prima crea un account, ricarica almeno $10 e poi vai alla pagina delle chiavi API per crearne una. La chiave viene mostrata una sola volta: salvala subito. Quindi aggiungi una sezione provider al file di configurazione di Codex:

# ~/.codex/config.toml（沒有的話就新建一個）
model          = "gpt-5-6-sol"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "Kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"   # 填「環境變數的名稱」，不是金鑰本身
wire_api = "responses"        # 唯一有效的值，省略也一樣

L'errore più facile da commettere riguarda env_key: qui devi inserire il nome della variabile d'ambiente che contiene la chiave, non la chiave stessa. La chiave non compare nel file di configurazione, quindi puoi tranquillamente eseguire il commit di config.toml in git o incollarlo in un forum per chiedere aiuto.

# 把金鑰放進 env_key 指定名稱的變數（金鑰以 sk-kn- 開頭）
export KUNAVO_API_KEY="sk-kn-..."

# 寫進 shell 的設定檔，就不必每次都 export
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

In PowerShell su Windows puoi eseguire setx KUNAVO_API_KEY sk-kn-... e poi aprire un nuovo terminale; il file di configurazione si trova in %USERPROFILE%\.codex\config.toml. Prima di avviare Codex, invia una richiesta per verificare che chiave ed endpoint funzionino: in caso di errore sarà più facile capire quale parte è responsabile.

# 懷疑 Codex 之前，先用一個請求確認金鑰和端點
curl https://api.kunavo.com/v1/responses \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5-6-sol", "input": "只回 OK"}'

La restituzione di JSON indica che chiave ed endpoint funzionano; il problema rimanente è in config.toml. Le descrizioni dei campi di configurazione sono nella documentazione d'integrazione di Codex CLI (inglese); il metodo per chiamare modelli Claude da Codex è nella guida alle chiavi API di Codex CLI (inglese).

La prima attività

# 1. 進到要處理的專案資料夾，啟動 Codex
cd ~/work/my-app
codex

# 2. 讓它產生 AGENTS.md 草稿（寫測試怎麼跑、專案規則的檔案）
> /init

# 3. 之後直接用中文交代。附上檔名，做得更快也更省
> src/utils/date.test.ts 一直失敗，找出原因修好，並確認測試通過

Il AGENTS.md generato da /init è il file che contiene le «regole impossibili da dedurre leggendo il codice»: come eseguire i test, quali librerie usare e quali percorsi non modificare. Viene letto automaticamente a ogni sessione. Il contenuto generato è solo una bozza: modificalo personalmente.

Il consiglio per impartire istruzioni è lo stesso di Claude Code: indica nomi e percorsi dei file e non affidare attività grandi a un'unica richiesta. Consumando meno token per l'esplorazione, ottieni risultati più rapidi e precisi e riduci la fattura.

Scegliere il modello in base all'attività: il costo effettivo di una singola attività

Il vantaggio principale dell'uso di una chiave API è poter scegliere il modello in base alla complessità del lavoro. model è solo il nome del modello presso l'endpoint: cambiarlo non richiede una nuova chiave né configurazioni aggiuntive.

# config.toml 的預設（gpt-5-6-sol）不動，只有這次啟動換模型
codex -m gpt-6-astra     # 找不到原因的 bug、跨模組的修改
codex -m gpt-5-6-terra   # 例行修改、大量取代、整理日誌這類輕量工作

Il calcolo di «un'attività» considera la correzione di un test fallito come 20 step. Ogni step comprende 25.000 token di input (prompt di sistema + cronologia della conversazione + file letti) e 1.200 token di output (una modifica o spiegazione), quindi un'attività comprende 500.000 token di input e 24.000 di output. Con GPT-5.6 Sol costa circa $1,29; la stessa quantità di token pagata direttamente a OpenAI costa, al prezzo promozionale attuale, $2,48 (al prezzo di listino $3,22). I modelli più economici potrebbero richiedere più scambi per correggere il problema; nella pratica, se il primo tentativo fallisce, conviene passare al livello superiore.

Questo calcolo non include la cache. Codex reinvia la cronologia della conversazione a ogni step; gli input trovati nella cache costano 0,10 volte la tariffa input (GPT-5.6 Sol costa $0,20 per 1M di token), mentre i nuovi dati scritti nella cache costano 1,25 volte la tariffa input. Inoltre, per la serie GPT-5.6 e GPT-6 Astra, quando il prompt di una singola richiesta supera 272K token, l'intera richiesta viene addebitata a 2 volte la tariffa input e 1,5 volte quella output. Evita quindi di inserire troppo lavoro nella stessa sessione; per sicurezza, riavvia la sessione per ogni attività. I token di ragionamento vengono addebitati alla tariffa output: più difficile è il problema, maggiore sarà l'output. Per il costo effettivo, consulta usage e il registro dell'utilizzo nella risposta. Le specifiche del modello sono nella pagina del modello GPT-5.6 Sol; le tariffe di tutti i modelli sono nel listino.

Errori comuni

Detto con franchezza: quando conviene il piano ChatGPT

Se passi diverse ore ogni giorno a dialogare con Codex, un piano con canone mensile fisso è di solito più economico. Il pagamento a consumo è proporzionale ai token utilizzati: più l'uso è intenso e costante, maggiore è il vantaggio del canone mensile. Il punto di pareggio è «canone mensile ÷ prezzo di un'attività»; il punto di pareggio tra i piani è già calcolato nella pagina Costi di Codex.

Ci sono altri due aspetti da sapere. Secondo la documentazione OpenAI, le funzionalità che dipendono dal workspace ChatGPT o dai servizi cloud possono essere limitate o non disponibili con una chiave API. Inoltre, il percorso Kunavo usa capacità condivisa, senza quota dedicata né SLA contrattuale; se ti servono capacità o SLA garantiti, è più adatto stipulare un contratto direttamente con OpenAI.

La chiave API è invece adatta a chi ha un utilizzo variabile, vuole scegliere il modello in base all'attività, desidera separare limiti e registri di utilizzo per chiave all'interno del team, o vuole continuare a lavorare dopo aver esaurito la quota del piano. Puoi usare entrambe le modalità: elimina la riga model_provider da config.toml per tornare all'accesso ChatGPT; per cambiare a ogni avvio, usa --profile di Codex.

Paga con una carta di credito internazionale (inclusa JCB), Apple Pay o Google Pay; a Taiwan non sono disponibili canali di pagamento locali: JKO Pay e LINE Pay non figurano nell’elenco dei metodi disponibili. Il sistema prepagato addebita la carta una sola volta al momento della ricarica; il saldo non scade e le richieste non riuscite non vengono addebitate. Se sei ancora indeciso tra Codex e Claude Code, consulta Claude Code vs Codex CLI (in inglese); per sapere come vengono calcolati i costi di Claude Code, consulta Costi di Claude Code.

Domande frequenti