Come usare Codex — dall'installazione all'esecuzione con una chiave API senza abbonamento

Codex è l'agente di programmazione di OpenAI. Per usarlo, installa Codex CLI, che funziona nel terminale (npm install -g @openai/codex), avvialo nel repository su cui vuoi lavorare con codex e formula la richiesta in giapponese. Esistono 2 modi per iniziare: accedere con un piano ChatGPT (Plus, Pro, Business e altri) e usare la quota inclusa, oppure eseguirlo con una chiave API e pagare soltanto i token utilizzati. Poiché le guide in giapponese trattano quasi esclusivamente il primo metodo, questa pagina spiega in ordine il secondo — configurare Codex CLI senza abbonamento, scegliere il modello per ogni attività e conoscere il costo effettivo di una singola attività.

Codex non è uno strumento in cui incollare codice in una schermata di chat: è un agente che legge e modifica file nel repository ed esegue test e comandi. Puoi decidere quanto affidargli senza conferma dopo l'avvio, tramite /permissions.

I 2 modi per usare Codex

Quando usi una chiave API, la fatturazione è calcolata separatamente dalla quota del piano OpenAI. Puoi usare direttamente una chiave API OpenAI, ma questa pagina tratta il metodo per indirizzare la richiesta a un endpoint compatibile con Responses API. Puoi passare da GPT-6 Astra a GPT-5.6 Terra con la stessa chiave; per esempio, GPT-5.6 Sol costa $2,00 / $12,00 per 1M token, rispetto al prezzo di listino OpenAI di $5,00 / $30,00(OpenAI offre attualmente il modello al prezzo promozionale di $4,00 / $20,00. Secondo la pagina dei prezzi, l'offerta prosegue almeno fino al 21 novembre 2026) (le tariffe vengono caricate direttamente dal catalogo).

Installazione — npm o Homebrew

# npm（Node.js が入っていれば macOS / Linux / Windows 共通）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

Entrambi sono metodi riportati nel README ufficiale di OpenAI. Anche su Windows puoi installarlo con il comando npm. Al termine dell'installazione, avvialo eseguendo codex nella directory del repository su cui vuoi lavorare. Se accedi con ChatGPT, qui hai finito e non sono necessarie altre impostazioni.

Eseguirlo con una chiave API — 1 blocco in config.toml

Per prima cosa crea un account, ricaricalo a partire da $10 e genera la chiave nella pagina delle chiavi API. La chiave viene mostrata una sola volta, quindi salvala subito. Poi scrivi un blocco relativo al provider nel 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ù comune qui riguarda env_key. Devi inserire il nome della variabile d'ambiente che contiene la chiave, non la chiave stessa. Poiché la chiave non viene inserita nel file di configurazione, config.toml può essere committato o incollato in una domanda senza rischi.

# env_key で指定した名前の変数にキーを入れる（キーは sk-kn- で始まる）
export KUNAVO_API_KEY="sk-kn-..."

# 毎回 export しないよう、使っているシェルの設定ファイルに追記しておく
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

In PowerShell su Windows, esegui setx KUNAVO_API_KEY sk-kn-... e poi riapri un nuovo terminale. Il file di configurazione si trova in %USERPROFILE%\.codex\config.toml. Prima di avviare Codex, verificare con una singola richiesta che la chiave e l'endpoint siano corretti facilita la diagnosi dei problemi successivi.

# Codex を疑う前に、キーとエンドポイントだけを 1 回で確かめる
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 とだけ返して"}'

Se ricevi JSON, la chiave e l'endpoint sono corretti; eventuali problemi residui riguardano config.toml. I dettagli delle impostazioni sono nella documentazione sull'integrazione di Codex CLI (in inglese); una guida che include anche come chiamare modelli Claude da Codex è disponibile nella guida alla configurazione della chiave API di Codex CLI (in inglese).

La prima attività

# 1. 作業したいリポジトリに入って起動する
cd ~/work/my-app
codex

# 2. AGENTS.md の雛形を作らせる（テストの実行方法や決めごとを書くファイル）
> /init

# 3. あとは日本語で頼む。ファイル名を添えるほど速く、安く終わる
> src/utils/date.test.ts が落ちている。原因を調べて直し、テストが通るのを確認して

Il file AGENTS.md creato da /init contiene le decisioni che non si possono capire leggendo il codice, come come eseguire i test, quali librerie usare e quali percorsi non modificare; viene caricato automaticamente nelle sessioni successive. Il contenuto generato è una bozza, quindi correggilo manualmente.

I consigli per formulare le richieste sono gli stessi di Claude Code: includi i nomi e i percorsi dei file e non inviare richieste grandi tutte insieme. Riducendo i token usati per l'esplorazione, il risultato sarà più rapido e preciso e la fattura diminuirà. La frequenza dei dialoghi di conferma può essere regolata con /permissions. Le modalità operative di Claude Code sono raccolte in Come usare Claude Code.

Scegliere il modello per attività — costo effettivo di una singola attività

Il vantaggio principale dell'uso di una chiave API è che puoi scegliere il modello in base alla complessità del lavoro. model è soltanto il nome del modello sull'endpoint, quindi per cambiare non servono chiavi o impostazioni aggiuntive.

# config.toml の既定（gpt-5-6-sol）はそのまま、この起動だけモデルを変える
codex -m gpt-6-astra     # 原因の見えないバグ、設計をまたぐ変更
codex -m gpt-5-6-terra   # 定型の修正、一括置換、ログの要約などの軽い作業

“Una singola attività” è calcolata considerando 20 passaggi per correggere un test non riuscito. Un passaggio comprende 25.000 token in input (prompt di sistema + cronologia della conversazione + file letti) e 1.200 token in output (una modifica o spiegazione), quindi una singola attività equivale a 500.000 token in input e 24.000 in output. Con GPT-5.6 Sol il costo è $1,29; pagando lo stesso numero di token direttamente a OpenAI, al prezzo promozionale attuale sarebbe $2,48 (al prezzo di listino $3,22). I modelli più economici possono richiedere più scambi a causa dei rifacimenti, quindi è pratico passare al livello superiore se non si conclude al primo tentativo.

Questo calcolo non considera la cache. Codex reinvia la cronologia della conversazione a ogni passaggio: gli input presenti nella cache vengono fatturati a 0,10 volte il prezzo unitario dell'input (con GPT-5.6 Sol, l'input nella cache costa $0,20 per 1M token), mentre i nuovi contenuti scritti nella cache costano 1,25 volte il prezzo unitario dell'input. Inoltre, per la serie GPT-5.6 e GPT-6 Astra, se il prompt di una richiesta supera 272K token, l'intera richiesta viene fatturata con input a 2 volte e output a 1,5 volte. È più sicuro non concentrare troppo lavoro in un'unica sessione e riavviare Codex per ogni attività. I token di ragionamento dei modelli di ragionamento vengono fatturati come output, quindi le attività difficili aumentano anche l'output. Verifica il costo effettivo in usage della risposta e nella cronologia di utilizzo. Le specifiche del modello sono nella pagina del modello GPT-5.6 Sol; i prezzi unitari di tutti i modelli sono nella tabella dei prezzi.

Errori comuni

Parliamoci chiaro — quando il piano ChatGPT è più conveniente

Se lavori ogni giorno per molte ore interagendo con Codex, il piano a prezzo fisso è in genere più economico. La tariffazione a consumo è direttamente proporzionale al numero di token, quindi il vantaggio del prezzo fisso cresce per chi usa il servizio molto e in modo costante. Il punto di pareggio è “canone mensile ÷ costo di una singola attività”; il punto di pareggio rispetto al piano è calcolato in Prezzi di Codex.

Ci sono altri 2 aspetti da conoscere. Secondo la documentazione OpenAI, le funzionalità che dipendono dal workspace o dal cloud ChatGPT sono limitate o non disponibili quando si usa una chiave API. Inoltre, il percorso Kunavo utilizza capacità condivisa e non offre quote dedicate né uno SLA contrattuale. Se ti servono una quota garantita o uno SLA, è più appropriato stipulare un contratto direttamente con OpenAI.

La chiave API è invece adatta a chi ha una grande differenza tra giorni di utilizzo e giorni senza utilizzo, vuole scegliere il modello per ogni attività, vuole separare limiti e cronologia per chiave all'interno di un team o vuole continuare a lavorare solo nei giorni in cui la quota del piano è esaurita. I due metodi possono coesistere. Eliminando la riga model_provider di config.toml torni all'accesso con ChatGPT; se vuoi cambiare a ogni avvio puoi usare --profile di Codex.

I pagamenti possono essere effettuati con carte, incluse JCB, Apple Pay, Google Pay e altri metodi; il saldo non scade. I pagamenti nei minimarket e PayPay non sono supportati. Le richieste non riuscite non vengono addebitate. Se non sai se utilizzare Codex o Claude Code, consulta Confronto tra Codex e Claude Code.

Domande frequenti