Harness Codex di OpenClaw: sessioni, credenziali e fatturazione

L'harness Codex di OpenClaw è il plugin ufficiale @openclaw/codex: affida un turno dell'agente OpenClaw all'app-server Codex di OpenAI, così che Codex gestisca il ciclo del modello, la ripresa dei thread, la continuazione degli strumenti e la compattazione. Non è un prodotto per delegare attività di coding, non è un livello di fatturazione e — l'aspetto che confonde la maggior parte delle configurazioni — non è un modo per eseguire Codex tramite un endpoint API di terze parti. Quale di queste funzioni ti serva davvero è la decisione che questa pagina vuole aiutarti a prendere.

Prima le date, così nulla di tutto ciò è privo di data. Il pacchetto npm openclaw è alla versione 2026.9.5 e richiede Node >=24.16.0 <25 || >=26.1.0; @openclaw/codex è alla versione 2026.9.5, pubblicata il 18 settembre 2026. Entrambi sono stati letti dal registry il 21 settembre 2026. Tre progetti non correlati condividono questi nomi e nessuno dei loro numeri è pertinente qui: pjasicek/OpenClaw si descrive come una reimplementazione del platformer del 1997 Captain Claw, il pacchetto npm senza scope codex è un "generatore di siti statici e documentazione del codice" pubblicato l'ultima volta nel 2012, mentre la CLI di OpenAI è @openai/codex (0.155.1 nella stessa data).

Cinque superfici di OpenClaw condividono il nome "Codex"

La documentazione sui runtime degli agenti di OpenClaw li definisce "intenzionalmente indipendenti". Scegliere quello sbagliato è il motivo più comune per cui una configurazione sembra corretta ma non produce alcun effetto.

Un sesto nome non appartiene affatto a OpenClaw. openclaw-code-agent è un plugin di terze parti che esegue in background sessioni di coding con approvazione del piano e isolamento del worktree; il suo README afferma che è separato dal plugin runtime acpx incluso in OpenClaw e dal plugin core codex incluso. Se sei arrivato qui cercando la delegazione invece di una sostituzione del runtime, si tratta di un prodotto diverso con chiavi di configurazione diverse.

Attivare l'harness e dimostrare che è attivo

Il percorso documentato consiste in due comandi: il plugin, poi l'accesso.

openclaw plugins install @openclaw/codex
openclaw models auth login --provider openai

Poi la configurazione minima. Se usi un elenco plugins.allow, aggiungi anche "codex".

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      // The docs' own example ref. Legacy codex-cli/* refs are
      // repaired to the same openai/<model> route by doctor --fix.
      model: "openai/gpt-6-astra",
    },
  },
}

Due dettagli esplicitati nella documentazione dell'harness. Le modifiche alla configurazione del plugin vengono applicate automaticamente nella modalità di ricaricamento ibrido, ma una chat esistente richiede prima /new o /reset, affinché il turno successivo risolva l'harness usando la configurazione corrente. Inoltre, il profilo effettivo degli strumenti deve consentire funzionalità native di shell e filesystem: coding e full lo fanno, mentre messaging e minimal disabilitano la superficie nativa. Un sandbox ordinario di OpenClaw o una policy degli strumenti con restrizioni è una limitazione più severa nella stessa documentazione: disabilita la modalità nativa del codice, a meno che tu non scelga il percorso sperimentale sandbox exec-server; quando il sandboxing disabilita la superficie nativa, i comandi shell consentiti restano raggiungibili tramite sandbox_exec.

Requisiti di versione, verificati il 21 settembre 2026 rispetto al riferimento del trasporto app-server: il plugin gestisce Codex app-server stabile 0.154.0, mentre gli eseguibili personalizzati espliciti, gli app-server remoti e i binari desktop macOS devono riportare una versione semantica analizzabile pari o superiore a 0.149.0. L'ultima versione npm di @openai/codex è 0.155.1 nella stessa data, quindi il pin gestito è indietro di una patch — motivo per cui qualsiasi guida che dica "Codex latest" senza una data diventa obsoleta nel giro di pochi giorni. Anche la migrazione di una configurazione precedente è importante: la pagina sui runtime degli agenti afferma che il backend Codex CLI incluso in OpenClaw è stato rimosso nella v2026.5.14 e che i riferimenti legacy codex-cli/* vengono riparati verso lo stesso percorso app-server Codex openai/<model> sotto openclaw doctor --fix, che gestisce in generale la riparazione dei percorsi Codex legacy.

Per verificare: un turno gestito da Codex riporta Runtime: OpenAI Codex sotto /status, mentre /codex status, /codex models e /codex binding ispezionano lo stato dell'app-server. Un lint — openclaw doctor --lint --only codex/managed-app-server --json — controlla il binario gestito, ma la documentazione lo descrive come di sola lettura ed esclude da quel controllo un binario Codex Desktop selezionato, un comando personalizzato esplicito e un app-server remoto.

C'è una tensione che vale la pena conoscere prima di basarsi su tutto questo. La documentazione dell'app-server di OpenAI afferma che "il comando app-server e il trasporto WebSocket sono sperimentali e non sono supportati per carichi di lavoro di produzione" — nota che l'avvertenza nomina sia il comando sia il trasporto. OpenClaw costruisce una funzionalità distribuita sopra quel comando e il suo campo transport ha come valore predefinito stdio, mentre websocket viene usato solo quando configuri un url. Entrambe le affermazioni sono vere contemporaneamente; decidi tenendole entrambe presenti.

Artefatti di delega, autorizzazioni, annullamento e ripresa

La documentazione dell’harness è onesta sui limiti di ciò che dimostra lo stato di un subagent nativo: esecuzione, risultato dell’attività e consegna del risultato sono fatti distinti; un thread nativo inattivo, interrotto o scaricato non dimostra che l’attività sia riuscita e, quando la conferma della chiusura non è disponibile, l’attività chiede di ritentare la chiusura. I subagent nativi di Codex sono il meccanismo proprietario di Codex: la delega esplicita tramite OpenClaw o ACP passa comunque da sessions_spawn.

Secondo la tabella dei campi di configurazione del plugin, le autorizzazioni di esecuzione per l’app-server avviato da OpenClaw sono impostate per impostazione predefinita sulla modalità yolo, sulla policy di approvazione never e sulla sandbox danger-full-access, a meno che i requisiti locali di Codex non impediscano tale configurazione; in tal caso, le impostazioni predefinite del guardian privilegiano le approvazioni su richiesta e workspace-write, altrimenti read-only; requestTimeoutMs, il timeout per le chiamate al control plane dell’app-server, è impostato per impostazione predefinita su 60000. Questi sono i valori predefiniti di OpenClaw per il processo che avvia, non quelli propri della CLI di Codex; in un repository sconosciuto, la prima impostazione da esaminare prima della prima esecuzione è proprio quella predefinita.

Il controllo durante un turno è nativo: /codex stop, /codex steer, /codex resume, /codex detach, /codex bind, /codex compact, /codex threads, /codex goal, /codex model, /codex fast e /codex permissions. Un turno con restrizioni è valido per singolo turno, non è una modalità di sessione, e per quel solo turno disabilita Code Mode nativo, le selezioni dell’ambiente, i server MCP configurati e i relay degli hook nativi. Il contratto di supporto runtime v1 di OpenClaw elenca inoltre come non supportati: la mutazione nativa degli argomenti degli strumenti (gli hook pre-tool possono bloccare, ma OpenClaw non riscrive gli argomenti), una cronologia modificabile della trascrizione nativa di Codex, l’intervento sulla compattazione e la cattura byte per byte delle richieste API al modello; quindi, se il requisito di audit è la richiesta esatta in uscita, questo runtime non può fornirla.

Autorizzazione, diritto incluso nel piano e consumo di token sono tre cose diverse

Letto dalla pagina della policy dell’app-server Codex di OpenClaw il 21 settembre 2026. Su tutto questo incombe una trappola di denominazione: la pagina dei prezzi API di OpenAI afferma che l’elaborazione Priority è stata rinominata modalità Fast il 30 luglio 2026 e che è possibile inviare service_tier di "priority" oppure "fast", mentre appServer.serviceTier di OpenClaw documenta "priority" e "flex" e normalizza un valore legacy "fast" in "priority": nella direzione opposta. «Attiva la modalità fast» significa cose diverse nei due sistemi.

Perché un endpoint di terze parti esce dall’harness

Questo è il singolo fatto che la maggior parte degli articoli di terze parti inverte. La tabella dei runtime impliciti degli agenti di OpenClaw, per un provider o runtime del modello non impostato oppure auto, indica quanto segue:

Quindi, indirizzare OpenClaw verso un qualsiasi URL base di terze parti — incluso Kunavo — porta il turno sul runtime integrato di OpenClaw, per progettazione. Il solo prefisso openai/* non seleziona mai l’harness e forzare agentRuntime.id: "codex" non lo recupera. La pagina dei runtime afferma che questa impostazione «richiede un harness Codex registrato; i percorsi o le autenticazioni non supportati falliscono in modo chiuso, tranne per il fatto che gli override della richiesta definiti dall’utente possono utilizzare il fallback OpenClaw dichiarato da Codex per le richieste esatte prima dell’esecuzione»: quindi gli esiti possibili sono un turno fallito oppure un turno OpenClaw, e nessuno dei due è Codex su un endpoint personalizzato. Anche i campi di configurazione documentati del plugin non includono un’impostazione dell’URL base del modello; l’unico campo url indicato è l’indirizzo WebSocket o unix:// dell’app-server stesso. Non è documentato né testato se appServer.args possa introdurre di nascosto un override del provider nell’app-server gestito; questa pagina non lo presenta come soluzione alternativa.

Anche un percorso del runtime integrato modifica la richiesta e la pagina dei provider personalizzati di OpenClaw specifica l’ambito di ciascuna regola. Per api: "openai-completions" su un endpoint non nativo — definito come qualsiasi baseUrl non vuoto il cui host non sia api.openai.com — OpenClaw imposta forzatamente compat.supportsDeveloperRole su false e sovrascrive un true esplicito. Separatamente, i percorsi proxy compatibili con OpenAI «ignorano la trasformazione nativa delle richieste riservata a OpenAI»: niente service_tier, niente store di Responses, niente store di Completions, niente indicazioni di cache del prompt, nessuna trasformazione del payload compatibile con il ragionamento OpenAI e nessun header di attribuzione nascosto. Senza service_tier sul filo, Fast mode e Flex non sono selezionabili su tale percorso. La stessa pagina offre invece il pass-through di params.extra_body per i proxy Completions compatibili con OpenAI, headers per provider e models.providers.<id>.timeoutSeconds per host lenti o remoti.

Codex è l’altra metà della storia ed è più permissivo: la pagina della configurazione avanzata di Codex mostra ~/.codex/config.toml con supporto per [model_providers.<id>] tramite base_url e env_key. Esiste però un vincolo rigido: il riferimento di configurazione afferma che, per model_providers.<id>.wire_api, «responses è l’unico valore supportato ed è quello predefinito quando viene omesso». Un endpoint che offre solo Chat Completions non può quindi pilotare Codex. La stessa pagina della configurazione avanzata riserva gli ID integrati openai, ollama e lmstudio ed elenca model_provider e model_providers tra le chiavi ignorate da Codex in un .codex/config.toml a livello di progetto; le chiavi del provider devono quindi trovarsi nella configurazione a livello utente. Kunavo implementa una superficie Responses nativa su /v1/responses, che rende possibile la configurazione della CLI di Codex; tuttavia si tratta della CLI standalone di Codex, non dell’harness OpenClaw, e Kunavo non ha testato in runtime nessuno dei due client.

Quanto costa il software e quanto costano i token

OpenClaw in sé costa $0. Il suo indice della documentazione descrive il progetto come con licenza MIT, guidato dalla comunità e sviluppato da una fondazione indipendente 501(c)(3), con «Nessun piano a pagamento»; @openclaw/codex è pubblicato gratuitamente nel registro npm pubblico. Ogni costo reale è costituito dalla macchina su cui esegui il Gateway e dall’utilizzo del modello, che viene fatturato secondo uno dei tre contratti seguenti.

Dalla pagina dei prezzi di Codex di OpenAI, verificata il 21 settembre 2026. A questa tabella vanno aggiunte tre precisazioni. La scheda dei prezzi pubblica solo «Da $100» per Pro; un articolo separato di OpenAI, Informazioni sui piani ChatGPT Pro, indica un piano superiore da $200 le cui nuove iscrizioni e gli upgrade sono sospesi dal 10 settembre 2026; verifica quindi al checkout invece di preventivare una cifra che questa pagina non mostrava in una scheda dei prezzi. L’utilizzo incluso è pubblicato solo come intervalli stimati di messaggi locali per periodo di cinque ore, non come numero fisso di messaggi. Inoltre, le tariffe dei crediti oltre i limiti inclusi sono pubblicate in crediti per milione di token, senza un valore in dollari per credito su quella pagina dei prezzi; pertanto non fornisce alcuna conversione in dollari per quella riga. Separatamente, GPT-5.5 verrà ritirato da ChatGPT, ChatGPT Work e Codex su tutti i piani il 14 ottobre 2026, mentre l’API OpenAI non sarà interessata.

Il terzo contratto è un gateway sul runtime integrato di OpenClaw. Supponiamo un turno delegato che invia 180.000 token di input non memorizzati nella cache e riceve 9.000 token di output; le tariffe sono i prezzi attuali del catalogo Kunavo per milione di token.

Si tratta di un calcolo illustrativo dei token, non dei costi misurati di un’attività né di un tetto di fatturazione: la forma del turno è un’ipotesi e un turno reale dell’agente reinvia il contesto a ogni andata e ritorno degli strumenti. L’importo del catalogo Kunavo è un minimo di fatturazione, non un limite: quando il provider upstream comunica il proprio addebito, la fattura è il maggiore tra il costo di catalogo e il costo upstream moltiplicato per il markup applicabile. Gli addebiti della cache e gli strumenti esterni non rientrano nell’esempio. La ricarica minima è $10 di credito prepagato, che finanzia un saldo invece di acquistare un piano: consulta i dettagli della fatturazione.

Kunavo non offre alcun modello di embedding, alcun modello di sintesi vocale e alcun modello di riconoscimento vocale. Kunavo non offre questi passaggi su nessun percorso; indirizzali quindi a un provider che li supporti.

Questo limite è importante perché la tabella delle superfici qui sopra mantiene separato dal harness un percorso non-agent della OpenAI Platform e una chiave Gateway copre solo i modelli di chat nel catalogo Kunavo.

Quale route prevale quando

Se la risposta è la riga del gateway, inizia dall’integrazione della CLI di Codex per la struttura dell’API Responses, confronta le opzioni in la migliore API per OpenClaw e la migliore API per Codex e crea un account Kunavo quando sei pronto a finanziare una chiave. Per il lato del budget di un assistente self-hosted, i prezzi di OpenClaw separano software, hosting e consumo del modello.

Domande frequenti

La tabella dei runtime, l’ordine di autenticazione, l’avviso sull’app-server, il vincolo wire_api, i riferimenti alle versioni e i prezzi dei piani sopra riportati sono stati recuperati il 21 settembre 2026 dalla documentazione proprietaria di OpenClaw e OpenAI, dal centro assistenza di OpenAI e dalle voci del registro npm per openclaw, @openclaw/codex, @openai/codex, codex e openclaw-code-agent. Ogni affermazione rimanda alla pagina da cui proviene; quando un documento non risolveva una questione, il testo lo dichiara invece di colmare la lacuna. Kunavo non ha eseguito alcun test runtime di OpenClaw o dell’harness Codex; ogni configurazione qui riportata è quindi verificata rispetto alla documentazione di riferimento, non dimostrata sull’endpoint Kunavo. Le tariffe dei token Kunavo provengono dal catalogo attuale e ogni cifra in dollari è un calcolo illustrativo.