Repo del giorno: opencodex, qualsiasi LLM dentro Codex e Claude Code

💡 Cos'è opencodex: un traduttore di API che vive sulla tua macchina

opencodex è un demone locale scritto in TypeScript (runtime Bun, incluso nel pacchetto npm: serve solo Node 18+) che ascolta su localhost:10100 e fa da interprete: Codex CLI, App e SDK parlano la loro Responses API, il proxy la converte nel protocollo del provider che scegli. Cinque adapter coprono Anthropic Messages, Google Gemini, Azure OpenAI, il passthrough Responses e ogni endpoint compatibile Chat Completions: in pratica oltre 40 provider out of the box, inclusi DeepSeek, Groq, OpenRouter, Mistral e i server locali come Ollama, vLLM e LM Studio.

La parte che trovo più curata è l'iniezione «history-safe»: su installazione locale il proxy punta il provider openai nativo di Codex verso sé stesso con una sola riga di openai_base_url, così i thread esistenti non vengono rietichettati e un arresto sporco non lascia residui. ocx stop ripristina la configurazione originale di Codex, senza processi orfani. Streaming, tool call, reasoning token e immagini passano in entrambe le direzioni.

repo       lidge-jun/opencodex · licenza MIT
stelle     ~370 in meno di un mese (creato il 18 giugno 2026)
pacchetto  npm install -g @bitkyc08/opencodex · comando ocx
porta      localhost:10100 · dashboard web con ocx gui
adapter    Anthropic · Google · Azure · Responses · OpenAI-compatible
piattaforme macOS · Linux · Windows (launchd / systemd / Task Scheduler)

⚙️ Come si installa: tre comandi e Codex non se ne accorge

L'installazione è la parte meno drammatica: un pacchetto npm globale, un ocx init interattivo che scrive la configurazione e la inietta in Codex, e ocx start per avviare il proxy. Da quel momento codex si usa esattamente come prima — cambia solo chi risponde dall'altra parte. Per i provider l'aggiunta più comoda passa dalla dashboard web (ocx gui): si sceglie tra i 40+ preset o si inserisce un endpoint custom, si incolla la API key (o si fa OAuth per Anthropic, xAI e Kimi) e i modelli vengono scoperti in automatico dall'endpoint /v1/models, senza riavvii.

Per l'avvio automatico ci sono due strade: il servizio di sistema (launchd, systemd o Task Scheduler, per il proxy sempre acceso) oppure lo shim che avvolge il launcher di codex e fa partire il proxy on demand alla prima invocazione. La disinstallazione è simmetrica: ocx uninstall ferma tutto, rimuove servizio e shim e riporta Codex allo stato nativo.

# 1) installa (il runtime Bun arriva in bundle: basta Node 18+)
npm install -g @bitkyc08/opencodex

# 2) setup interattivo: config, iniezione in Codex, autostart
ocx init

# 3) avvia il proxy (fallback automatico se la porta è occupata)
ocx start

# da qui Codex si usa normalmente
codex "Scrivi un hello world in Rust"

🔀 Routing dei modelli: provider/model e il resto lo fa il proxy

Il cuore operativo è la sintassi provider/model: qualunque provider configurato diventa raggiungibile con codex -m "anthropic/claude-opus-4-8" o codex -m "google/gemini-3-pro", e senza prefisso il proxy instrada verso il provider di default o auto-abbina in base al pattern del nome (claude-* → Anthropic, gpt-* → OpenAI). I modelli instradati compaiono anche nel model picker dell'App Codex, con i controlli di reasoning effort per modello: dall'esterno sembrano modelli nativi.

C'è anche un livello più ambizioso: dalla dashboard si possono «mettere in vetrina» fino a cinque modelli nel picker dei subagent di Codex, per delegare il task giusto al modello giusto — un reasoning model per i problemi complessi, un modello economico per i task veloci. È lo stesso principio di cui ho scritto parlando di orchestrazione multi-agente: la novità è vederlo applicato al routing tra provider diversi dentro un harness solo.

# Claude Opus via Anthropic
codex -m "anthropic/claude-opus-4-8" "Spiega questo stack trace"

# Gemini via Google
codex -m "google/gemini-3-pro" "Scrivi gli unit test per auth.ts"

# GLM via Ollama Cloud
codex -m "ollama-cloud/glm-5.2" "Scrivi una migration SQL"

# modello locale via Ollama: i sorgenti non escono dalla macchina
codex -m "ollama/llama3" "Rifattorizza questa funzione"

🧩 Anche Claude Code: lo stesso proxy, nella direzione opposta

La funzione che mi ha fatto scegliere questo repo è l'estensione a Claude Code: lo stesso demone serve anche l'API Anthropic Messages (/v1/messages più count_tokens), quindi ocx claude lancia Claude Code già cablato al proxy, e i modelli instradati compaiono nel suo picker /model nativo come alias claude-ocx-<provider>--<model>. In altre parole: Codex può parlare con Claude, e Claude Code può parlare con Gemini, DeepSeek o un modello locale, con slot e mappe dei modelli configurabili dalla pagina Claude della dashboard.

È un'idea che sul blog ho già incontrato in forma più artigianale con claude-code-router; qui il perimetro è più ampio — due harness, cinque protocolli, una dashboard — e la direzione è dichiarata nel nome del progetto: «make codex open». Per chi vuole capire quanto un harness sia davvero separabile dal suo modello, questo repo è il banco di prova più completo che abbia visto finora.

🏠 Modelli locali e PMI: il caso d'uso che mi convince di più

Il caso d'uso su cui mi soffermerei, soprattutto in ottica PMI, è il routing verso modelli locali: puntare opencodex a un server Ollama, vLLM o LM Studio sulla propria macchina (o su un server interno) significa tenere il workflow di Codex — pianificazione, tool call, diff — facendo girare l'inferenza dentro il perimetro aziendale. Per una software house che lavora su codice sotto NDA, o per progetti in settori regolamentati, è la differenza tra «non possiamo usare gli agenti» e «possiamo usarli con un modello che non esce dalla rete».

La configurazione è un blocco JSON in ~/.opencodex/config.json con baseUrl locale e API key vuota. Vale la pena essere onesti sui limiti: un modello locale medio non è Claude Opus, e sui task complessi la differenza si sente. Ma per refactoring circoscritti, test e boilerplate il compromesso è spesso accettabile — e il costo marginale è zero, un tema che avevo già toccato parlando di limiti e razionamento dei token.

{
  "port": 10100,
  "defaultProvider": "ollama",
  "providers": {
    "ollama": {
      "adapter": "openai-chat",
      "baseUrl": "http://localhost:11434/v1",
      "authMode": "key",
      "apiKey": "",
      "defaultModel": "llama3"
    }
  }
}

⚠️ Cosa sapere prima di adottarlo: ToS, account pool e superficie di rete

Qui serve la parte seria. Il README dichiara senza giri di parole che alcuni provider — Anthropic in testa — possono sospendere o limitare gli account che instradano il traffico attraverso proxy di terze parti: prima di collegare un provider va letta la sua Terms of Service, e la responsabilità resta tua («use at your own risk»). Non è una clausola di stile: è il rischio concreto di perdere un account che usi per lavorare. La funzione di pool di account ChatGPT — più account Codex con auto-rotazione verso quello meno carico — è tecnicamente ben fatta (affinità di thread, cooldown sui 429, failover), ma è anche l'area dove starei più attento ai termini d'uso.

Sul piano della sicurezza il progetto si comporta bene: bind di default su loopback, e se lo esponi in LAN rifiuta di partire senza bearer token (confrontato in tempo costante). Restano le cautele da progetto giovane: un maintainer principale, meno di un mese di vita, e un adapter Cursor sperimentale che tiene l'esecuzione nativa disattivata di default proprio perché scavalcherebbe sandbox e approvazioni di Codex.

• Termini di servizio: Anthropic e altri provider possono sospendere account che passano da proxy terzi; leggere le ToS prima di collegare un provider.
• Account pool: utile per la telemetria delle quote, ma è l'area più delicata rispetto ai termini d'uso di ChatGPT/Codex.
• Esposizione in rete: di default solo loopback; in LAN serve OPENCODEX_API_AUTH_TOKEN, e va trattato come un segreto.
• Progetto giovane: nato il 18 giugno 2026, ritmo di rilascio alto ma bus factor da considerare per un uso in team.

🗺️ Perché è interessante e da dove partire

Al di là del tool, opencodex mi sembra il segnale più chiaro di una tendenza: l'harness sta diventando un livello indipendente dal modello. Codex e Claude Code valgono per il loro loop agentico — pianificazione, tool, sandbox, diff — e progetti come questo dimostrano che il «cervello» sotto quel loop è intercambiabile. Per chi sviluppa è un vantaggio negoziale e tecnico: si sceglie il modello per il task, non per l'abbonamento. Per una PMI è un modo per sperimentare gli agenti tenendo aperte le opzioni, incluso il modello locale quando i dati non possono uscire.

Il percorso che suggerisco: primo, provarlo su una macchina secondaria con un solo provider via API key (il percorso OAuth lascialo a dopo, quando hai letto le ToS). Secondo, testare il routing verso un modello locale con Ollama, che è il caso d'uso a rischio zero. Terzo, se ti serve la strada inversa — Claude Code con modelli alternativi — confrontalo con claude-code-router, di cui ho scritto un tutorial completo: più piccolo il perimetro, più facile capire dove passa il traffico.