Riferimento dell'harness Codex

Questo riferimento descrive la configurazione dettagliata del plugin ufficiale codex. Per le decisioni relative alla configurazione e all'instradamento, iniziare da harness Codex.

Superficie di configurazione del plugin

Tutte le impostazioni dell'harness Codex si trovano in plugins.entries.codex.config.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

Campi di primo livello:

Supervisione

Per impostazione predefinita, l'individuazione delle sessioni native elenca le sessioni Codex non archiviate dal computer del Gateway e dai nodi associati che hanno fornito il consenso. Disabilitare solo tale catalogo con:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          sessionCatalog: {            enabled: false,          },        },      },    },  },}

supervision controlla separatamente gli strumenti rivolti all'agente:

Le voci degli endpoint accettano questi campi:

La pagina Sessioni Codex usa l'App Server di supervisione del plugin e mostra solo le sessioni non archiviate. Senza impostazioni di connessione appServer esplicite, tale connessione è uno stdio gestito nella home dell'utente. Le righe locali memorizzate o inattive possono creare una chat vincolata al modello con una cronologia limitata dell'utente e dell'assistente fino all'ultimo turno di origine terminale persistito. La relativa associazione privata mantiene su tale connessione il fork dell'istantanea, il ramo di origine appServer canonico, l'inserimento della cronologia e i turni successivi. Il primo avvio canonico usa la coppia restituita dal fork. Le riprese successive omettono le sostituzioni di modello e provider OpenClaw, affinché Codex ripristini la coppia persistita del thread canonico; una modifica nativa separata può aggiornare tale coppia, ma il modello esterno e la catena di fallback non la sostituiscono mai. Le righe memorizzate e inattive possono essere archiviate dopo la conferma che non siano presenti altri esecutori, a meno che un'altra associazione OpenClaw attiva possieda la destinazione esatta o uno dei suoi discendenti generati non archiviati. OpenClaw segue la paginazione dei discendenti di Codex e interrompe in modo sicuro in caso di errori di enumerazione, cicli o esaurimento del limite di sicurezza. La conferma continua a coprire i client nativi sconosciuti e la race condition tra stato e archiviazione. Una chat supervisionata vincolata al modello non può essere eliminata mentre protegge l'associazione nativa. Le origini attive non possono creare un ramo né essere archiviate, ma una chat supervisionata esistente può comunque essere aperta. Ogni riga di un nodo associato rimane di sola lettura; il trasporto del nodo non fornisce ancora il ciclo di vita dello streaming necessario all'harness.

Solo appServer.homeScope: "user" modifica quale home Codex viene usata da un processo harness gestito; non pubblica il catalogo del parco di sistemi. L'abilitazione della supervisione non modifica l'impostazione predefinita dell'harness. La connessione di supervisione separata usa invece per impostazione predefinita uno stdio gestito nella home dell'utente quando non esistono impostazioni di connessione appServer esplicite. Le impostazioni esplicite vengono rispettate per tale connessione. Le associazioni supervisionate in sospeso e confermate mantengono tale connessione per ogni turno; la supervisione disabilitata o una divergenza della connessione o del ciclo di vita causano un'interruzione sicura anziché un fallback sull'harness nella home dell'agente. La connessione predefinita condivide le sessioni memorizzate con i client Codex nativi, non il loro stato di attività locale al processo.

Le impostazioni plugins.entries.codex-supervisor precedenti sono state ritirate. Eseguire openclaw doctor --fix per migrare in questo blocco la vecchia voce, le definizioni degli endpoint, i flag dei criteri e i riferimenti di autorizzazione/esclusione dei plugin. In caso di conflitto prevalgono i valori canonici codex.config.supervision espliciti.

Trasporto dell'app-server

Per i turni ordinari dell'harness, OpenClaw avvia il binario Codex gestito distribuito con il plugin ufficiale (attualmente @openai/codex 0.144.3):

codex app-server --listen stdio://

In questo modo la versione dell'app-server rimane associata al plugin ufficiale codex, anziché a qualunque CLI Codex separata eventualmente installata in locale. Impostare appServer.command solo quando si desidera intenzionalmente un eseguibile diverso. I turni gestiti ordinari con la home isolata predefinita dell'agente preferiscono questo pacchetto con versione fissata anche quando è installato un bundle desktop per macOS. Quando Computer Use è abilitato oppure quando homeScope è "user" e può caricare lo stato nativo di Computer Use, l'avvio gestito preferisce invece il binario dell'app desktop che possiede le autorizzazioni macOS richieste. La stessa regola di precedenza per il desktop si applica quando la configurazione Codex effettiva della home isolata di un agente abilita Computer Use nativo. Se non è installato alcun bundle dell'app desktop, OpenClaw ricorre al binario del pacchetto con versione fissata.

Il passaggio dell'eseguibile e il confinamento della configurazione nativa coordinano i client all'interno di un unico processo Gateway in esecuzione. Riavviare il Gateway dopo che un altro processo ha modificato la configurazione nativa del plugin Codex.

La supervisione risolve una connessione separata. Senza impostazioni di connessione appServer esplicite, usa stdio gestito con homeScope: "user"; l'harness ordinario rimane su stdio gestito con homeScope: "agent". Le impostazioni di connessione esplicite vengono rispettate da entrambi i percorsi. Impostare homeScope: "user" esplicitamente quando l'harness ordinario deve condividere $CODEX_HOME (o ~/.codex) con i client nativi. Un'associazione supervisionata privata usa la connessione di supervisione indipendentemente dall'impostazione predefinita dell'harness ordinario. I processi App Server indipendenti mantengono stati attivi e di approvazione separati.

Per un app-server già in esecuzione, usare il trasporto WebSocket:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

Campi appServer:

appServer.networkProxy è esplicito perché modifica il contratto della sandbox di Codex. Quando è abilitato, OpenClaw imposta anche features.network_proxy.enabled e default_permissions nella configurazione del thread Codex, affinché il profilo di autorizzazione generato possa avviare la gestione della rete da parte di Codex. Per impostazione predefinita, OpenClaw genera un nome di profilo openclaw-network-<fingerprint> resistente alle collisioni dal corpo del profilo; usare profileName solo quando è richiesto un nome locale stabile.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

Se il normale runtime dell'app-server fosse danger-full-access, l'abilitazione di networkProxy usa invece un accesso al file system in stile workspace per il profilo di autorizzazione generato. L'applicazione delle restrizioni di rete gestita da Codex è una rete in sandbox, quindi un profilo con accesso completo non proteggerebbe il traffico in uscita.

Il Plugin blocca gli handshake dell'app-server meno recenti o privi di versione: l'app-server Codex deve segnalare la versione stabile 0.143.0 o successiva.

OpenClaw considera remoti gli URL WebSocket dell'app-server non loopback e richiede un'autenticazione WebSocket associata a un'identità tramite appServer.authToken o un'intestazione Authorization. appServer.authToken e ogni valore appServer.headers.* possono essere un SecretInput; il runtime dei segreti risolve i SecretRef e le forme abbreviate delle variabili di ambiente prima che OpenClaw crei le opzioni di avvio dell'app-server, mentre i SecretRef strutturati non risolti causano un errore prima che venga inviato qualsiasi token o intestazione. Quando sono configurati Plugin Codex nativi, OpenClaw usa il piano di controllo dei Plugin dell'app-server connesso per installare o aggiornare tali Plugin, quindi aggiorna l'inventario delle app affinché le app di proprietà dei Plugin siano visibili al thread Codex. app/list rimane la fonte autorevole dell'inventario e dei metadati, ma la policy di OpenClaw determina se thread/start invia config.apps[appId].enabled = true per un'app accessibile elencata, anche se Codex la contrassegna attualmente come disabilitata. Gli ID app sconosciuti o mancanti continuano a essere bloccati per impostazione predefinita; questo percorso attiva soltanto i Plugin del marketplace tramite plugin/install e aggiorna l'inventario. Collegare OpenClaw soltanto ad app-server remoti considerati attendibili per accettare installazioni di Plugin gestite da OpenClaw e aggiornamenti dell'inventario delle app.

Modalità di approvazione e sandbox

Le sessioni locali dell'app-server tramite stdio usano per impostazione predefinita la modalità YOLO: approvalPolicy: "never", approvalsReviewer: "user" e sandbox: "danger-full-access". Questa configurazione per operatori locali attendibili consente ai turni e agli Heartbeat automatici di OpenClaw di procedere senza richieste di approvazione native a cui nessuno è presente per rispondere.

Se il file locale dei requisiti di sistema di Codex non consente valori impliciti per l'approvazione YOLO, il revisore o la sandbox, OpenClaw considera invece l'impostazione predefinita implicita come guardian e seleziona le autorizzazioni guardian consentite. tools.exec.mode: "auto" impone inoltre approvazioni Codex sottoposte a revisione guardian e non conserva le sostituzioni legacy non sicure approvalPolicy: "never" o sandbox: "danger-full-access"; impostare tools.exec.mode: "full" per scegliere intenzionalmente di non richiedere approvazioni. Le voci [[remote_sandbox_config]] con corrispondenza del nome host nello stesso file dei requisiti vengono rispettate nella scelta dell'impostazione predefinita della sandbox.

Impostare appServer.mode: "guardian" per le approvazioni Codex sottoposte a revisione guardian:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

La preimpostazione guardian si espande in approvalPolicy: "on-request", approvalsReviewer: "auto_review" e sandbox: "workspace-write" quando tali valori sono consentiti. I singoli campi della policy sostituiscono mode. Il precedente valore del revisore guardian_subagent è ancora accettato come alias di compatibilità, ma le nuove configurazioni dovrebbero usare auto_review.

Quando è attiva una sandbox OpenClaw, il processo locale dell'app-server Codex viene comunque eseguito sull'host del Gateway. Per quel turno OpenClaw disabilita quindi la modalità Codice nativa di Codex, i server MCP dell'utente e l'esecuzione dei Plugin supportata dalle app, anziché considerare la sandbox lato host di Codex equivalente al backend sandbox di OpenClaw. L'accesso alla shell è esposto tramite strumenti dinamici supportati dalla sandbox di OpenClaw, come sandbox_exec e sandbox_process, quando sono disponibili i normali strumenti exec/process.

Esecuzione nativa in sandbox

L'impostazione predefinita stabile blocca l'esecuzione in caso di errore: una sandbox OpenClaw attiva disabilita le superfici di esecuzione native di Codex che altrimenti verrebbero eseguite dall'host dell'app-server Codex. Usare appServer.experimental.sandboxExecServer: true solo per provare il supporto degli ambienti remoti di Codex con il backend sandbox di OpenClaw. Questo percorso di anteprima funziona con ogni versione supportata dell'app-server Codex.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            experimental: {              sandboxExecServer: true,            },          },        },      },    },  },}

Quando il flag è attivo e la sessione OpenClaw corrente è in sandbox, OpenClaw avvia un exec-server loopback locale supportato dalla sandbox attiva, lo registra presso l'app-server Codex e avvia il thread e il turno Codex con tale ambiente di proprietà di OpenClaw. Se l'app-server non riesce a registrare l'ambiente, l'esecuzione viene bloccata anziché ripiegare silenziosamente sull'esecuzione nell'host.

Questo percorso di anteprima è esclusivamente locale. Un app-server WebSocket remoto non può raggiungere l'exec-server loopback, a meno che non venga eseguito sullo stesso host, quindi OpenClaw rifiuta tale combinazione.

Isolamento dell'autenticazione e dell'ambiente

Nella home predefinita per agente, l'autenticazione viene selezionata nel seguente ordine:

1. Un profilo di autenticazione Codex OpenClaw esplicito per l'agente.
2. L'account esistente dell'app-server nella home Codex di tale agente.
3. Solo per gli avvii locali dell'app-server tramite stdio, CODEX_API_KEY, quindi OPENAI_API_KEY, quando non è presente alcun account dell'app-server ed è ancora richiesta l'autenticazione OpenAI.

Quando OpenClaw rileva un profilo di autenticazione Codex in stile abbonamento ChatGPT (tipo di credenziale OAuth o token), rimuove CODEX_API_KEY e OPENAI_API_KEY dal processo figlio Codex generato. In questo modo le chiavi API a livello di Gateway rimangono disponibili per gli embedding o i modelli OpenAI diretti, senza che i turni nativi dell'app-server Codex vengano addebitati accidentalmente tramite l'API.

I profili Codex espliciti con chiave API e il ripiego locale alla chiave di ambiente tramite stdio usano l'accesso dell'app-server anziché l'ambiente ereditato dal processo figlio. Le connessioni WebSocket dell'app-server non ricevono il ripiego alla chiave API dell'ambiente del Gateway; usare un profilo di autenticazione esplicito o l'account dell'app-server remoto.

Gli avvii dell'app-server tramite stdio ereditano per impostazione predefinita l'ambiente del processo OpenClaw. OpenClaw gestisce il bridge dell'account dell'app-server Codex e imposta CODEX_HOME su una directory per agente nello stato OpenClaw di tale agente. In questo modo configurazione, account, cache/dati dei Plugin e stato dei thread di Codex restano circoscritti all'agente OpenClaw anziché provenire dalla home personale ~/.codex dell'operatore.

Impostare appServer.homeScope: "user" per condividere lo stato nativo di Codex con Codex Desktop e la CLI. Questa modalità home utente locale supporta stdio gestito e trasporto Unix esplicito. Usa $CODEX_HOME quando impostato e ~/.codex negli altri casi, includendo autenticazione nativa, configurazione, Plugin e thread. OpenClaw ignora il proprio bridge del profilo di autenticazione per l'app-server. I turni verificati del proprietario possono usare codex_threads per elencare, con un filtro search facoltativo, leggere, creare fork, rinominare, archiviare e rimuovere dall'archivio tali thread. Creare un fork di un thread prima di proseguirlo in OpenClaw; i processi Codex indipendenti non coordinano scritture simultanee sullo stesso thread.

Tale consenso esplicito homeScope si applica alle normali sessioni dell'harness. Una Chat creata tramite Codex Sessions usa invece la propria connessione di supervisione privata, che conserva la configurazione di autenticazione e del provider della connessione nativa per il ramo canonico e le riprese future.

In una Chat supervisionata con modello bloccato, codex_threads non può collegare un fork diverso né archiviare il thread nativo associato alla Chat. L'elenco e la lettura dei soli metadati rimangono disponibili. Le letture della trascrizione non elaborata richiedono allowRawTranscripts; quando è disabilitato, viene rifiutata anche la ricerca nell'elenco, perché la ricerca nativa può trovare corrispondenze nelle anteprime delle trascrizioni. La ridenominazione, la rimozione dall'archivio, il fork scollegato e l'archiviazione di un thread non correlato e non posseduto da un'altra Chat OpenClaw richiedono allowWriteControls. Nessuna delle due opzioni aggira un'associazione bloccata.

OpenClaw non riscrive HOME per i normali avvii locali dell'app-server. I sottoprocessi eseguiti da Codex, come openclaw, gh, git, le CLI cloud e i comandi shell vedono la normale home del processo e possono trovare la configurazione e i token della home utente. Codex può inoltre rilevare $HOME/.agents/skills e $HOME/.agents/plugins/marketplace.json; tale rilevamento .agents è intenzionalmente condiviso con la home dell'operatore ed è distinto dallo stato isolato ~/.codex.

Nell'ambito predefinito dell'agente, i Plugin OpenClaw e le istantanee delle Skills OpenClaw continuano a transitare rispettivamente attraverso il registro dei Plugin e il caricatore delle skill di OpenClaw; le risorse personali ~/.codex di Codex no. Se nella home Codex sono presenti skill o Plugin della CLI Codex utili che dovrebbero diventare parte di un agente OpenClaw isolato, inventariarli esplicitamente:

openclaw migrate codex --dry-runopenclaw migrate apply codex --yes

Se una distribuzione richiede un ulteriore isolamento dell'ambiente, aggiungere tali variabili a appServer.clearEnv:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv influisce soltanto sul processo figlio dell'app-server Codex generato. OpenClaw rimuove CODEX_HOME e HOME da questo elenco durante la normalizzazione dell'avvio locale: CODEX_HOME continua a puntare all'ambito agente o utente selezionato, mentre HOME rimane ereditato affinché i sottoprocessi possano usare il normale stato della home utente.

Strumenti dinamici

Per impostazione predefinita, gli strumenti dinamici di Codex usano il caricamento searchable, esposto nello spazio dei nomi openclaw con deferLoading: true. Normalmente OpenClaw non espone gli strumenti dinamici che duplicano le operazioni native di Codex sul workspace o la superficie di ricerca degli strumenti di Codex:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan
• tool_call
• tool_describe
• tool_search
• tool_search_code

Quando un elenco di elementi consentiti finito del runtime disabilita la modalità Codice nativa, OpenClaw invia una selezione vuota dell'ambiente di esecuzione. In tale caso diretto e senza sandbox, OpenClaw mantiene i propri strumenti exec e process, filtrati dalla policy, come ripiego per la shell. Gli elenchi di elementi consentiti del runtime e codexDynamicToolsExclude continuano ad applicarsi.

La maggior parte degli strumenti di integrazione OpenClaw rimanenti, come messaggistica, contenuti multimediali, cron, browser, nodi, gateway, heartbeat_respond e web_search, è disponibile tramite la ricerca degli strumenti di Codex in quello spazio dei nomi. In questo modo il contesto iniziale del modello rimane più ridotto. Un piccolo insieme di strumenti resta direttamente richiamabile indipendentemente da codexDynamicToolsLoading, perché la ricerca degli strumenti di Codex potrebbe non essere disponibile o restituire un universo composto esclusivamente da connettori: agents_list, sessions_spawn e sessions_yield. Le istruzioni per gli sviluppatori continuano a indirizzare i normali subagenti Codex verso spawn_agent nativo per il lavoro dei subagenti nativi di Codex, mentre sessions_spawn rimane disponibile per la delega esplicita OpenClaw o ACP. Anche le risposte di origine che usano esclusivamente lo strumento di messaggistica rimangono dirette, poiché si tratta di un contratto di controllo del turno.

Gli strumenti contrassegnati con catalogMode: "direct-only", incluso lo strumento OpenClaw computer, sono raggruppati sotto openclaw_direct. OpenClaw aggiunge tale spazio dei nomi all'elenco code_mode.direct_only_tool_namespaces di Codex senza sostituire le voci fornite dall'operatore. Codex espone quindi tali strumenti come DirectModelOnly nei thread normali e in quelli riservati alla modalità codice, anziché instradarli attraverso chiamate annidate tools.* della modalità codice. Questo confine è necessario per i risultati contenenti immagini: la serializzazione annidata della modalità codice riduce l'output delle immagini a testo, eliminando così lo screenshot necessario per la successiva azione sul computer.

Impostare codexDynamicToolsLoading: "direct" solo quando ci si connette a un app-server Codex personalizzato che non può cercare strumenti dinamici differiti oppure durante il debug del payload completo degli strumenti.

Timeout

Le chiamate agli strumenti dinamici di proprietà di OpenClaw sono limitate indipendentemente da appServer.requestTimeoutMs. Ogni richiesta Codex item/tool/call usa il primo timeout disponibile nel seguente ordine:

• Un argomento timeoutMs positivo per singola chiamata.
• Per image_generate, agents.defaults.imageGenerationModel.timeoutMs.
• Per image_generate senza un timeout configurato, il valore predefinito di 120 secondi per la generazione di immagini.
• Per lo strumento di comprensione multimediale image, tools.media.image.timeoutSeconds convertito in millisecondi oppure il valore predefinito multimediale di 60 secondi. Per la comprensione delle immagini, questo valore si applica alla richiesta stessa e non viene ridotto dal lavoro di preparazione precedente.
• Per lo strumento message, un valore predefinito fisso di 120 secondi.
• Il valore predefinito di 90 secondi per gli strumenti dinamici.

Questo watchdog rappresenta il budget esterno del item/tool/call dinamico. I timeout delle richieste specifici del provider operano all'interno di tale chiamata e mantengono la propria semantica di timeout. I budget degli strumenti dinamici sono limitati a 600000 ms. In caso di timeout, OpenClaw interrompe il segnale dello strumento dove supportato e restituisce a Codex una risposta di errore dello strumento dinamico, in modo che il turno possa continuare anziché lasciare la sessione in processing.

Dopo che Codex accetta un turno e dopo che OpenClaw risponde a una richiesta dell'app-server circoscritta al turno, l'harness si aspetta che Codex compia progressi nel turno corrente e alla fine concluda il turno nativo con turn/completed. Se l'app-server non produce attività per appServer.turnCompletionIdleTimeoutMs, OpenClaw tenta di interrompere il turno Codex, registra un timeout diagnostico e libera la corsia della sessione OpenClaw, affinché i messaggi di chat successivi non vengano accodati dietro un turno nativo obsoleto.

La maggior parte delle notifiche non terminali relative allo stesso turno disattiva questo breve watchdog, poiché Codex ha dimostrato che il turno è ancora attivo. I passaggi di consegne degli strumenti usano un budget di inattività post-strumento più lungo: dopo che OpenClaw restituisce una risposta item/tool/call, dopo il completamento di elementi degli strumenti nativi come commandExecution, dopo i completamenti custom_tool_call_output non elaborati e dopo il progresso non elaborato dell'assistente successivo allo strumento, i completamenti del ragionamento non elaborati o il progresso del ragionamento. La protezione usa appServer.postToolRawAssistantCompletionIdleTimeoutMs quando configurato e altrimenti imposta come valore predefinito cinque minuti. Lo stesso budget post-strumento estende inoltre il watchdog di avanzamento per la finestra di sintesi silenziosa prima che Codex emetta il successivo evento del turno corrente. I completamenti del ragionamento, i completamenti agentMessage di commento e il progresso del ragionamento o dell'assistente non elaborato precedente allo strumento possono essere seguiti da una risposta finale automatica, pertanto usano la protezione della risposta post-avanzamento anziché liberare immediatamente la corsia della sessione. Solo gli elementi agentMessage completati finali/non di commento e i completamenti dell'assistente non elaborati precedenti allo strumento attivano il rilascio dell'output dell'assistente: se Codex resta quindi inattivo senza turn/completed, OpenClaw tenta di interrompere il turno nativo e libera la corsia della sessione. Gli errori dell'app-server stdio che consentono la riproduzione sicura, inclusi i timeout di inattività al completamento del turno senza elementi di prova relativi ad assistente, strumenti, elementi attivi o effetti collaterali, vengono ritentati una volta mediante un nuovo tentativo dell'app-server. I timeout non sicuri dismettono comunque il client app-server bloccato e liberano la corsia della sessione OpenClaw. Inoltre rimuovono l'associazione obsoleta al thread nativo anziché essere riprodotti automaticamente. I timeout del controllo del completamento mostrano testo di timeout specifico di Codex: i casi che consentono la riproduzione sicura indicano che la risposta potrebbe essere incompleta, mentre i casi non sicuri invitano l'utente a verificare lo stato corrente prima di riprovare. La diagnostica pubblica dei timeout include campi strutturali come l'ultimo metodo di notifica dell'app-server, l'id/tipo/ruolo dell'elemento di risposta non elaborato dell'assistente, il conteggio delle richieste/degli elementi attivi e lo stato del controllo attivato. Quando l'ultima notifica è un elemento di risposta non elaborato dell'assistente, include anche un'anteprima limitata del testo dell'assistente. Non include il prompt non elaborato né il contenuto degli strumenti.

Rilevamento dei modelli

Per impostazione predefinita, il Plugin Codex richiede all'app-server i modelli disponibili. La disponibilità dei modelli è gestita dall'app-server Codex, pertanto l'elenco può cambiare quando OpenClaw aggiorna la versione @openai/codex inclusa oppure quando una distribuzione indirizza appServer.command a un binario Codex diverso. La disponibilità può inoltre dipendere dall'account. Usare /codex models su un gateway in esecuzione per visualizzare il catalogo attivo per tale harness e account.

Se il rilevamento non riesce o scade, OpenClaw usa un catalogo di fallback incluso:

Configurare il rilevamento sotto plugins.entries.codex.config.discovery:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

Disabilitare il rilevamento quando si desidera evitare che l'avvio interroghi Codex e usare esclusivamente il catalogo di fallback:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

File di bootstrap dell'area di lavoro

Codex gestisce autonomamente AGENTS.md tramite il rilevamento nativo della documentazione del progetto. OpenClaw non scrive file sintetici di documentazione del progetto Codex né dipende dai nomi di file di fallback di Codex per i file della persona, poiché i fallback di Codex si applicano solo quando AGENTS.md è assente.

Per garantire la parità dell'area di lavoro OpenClaw, l'harness Codex inoltra gli altri file di bootstrap come istruzioni per gli sviluppatori, ma non in modo identico:

• TOOLS.md viene inoltrato come istruzioni per gli sviluppatori Codex ereditate, pertanto anche i subagenti Codex nativi generati durante il turno lo ricevono.
• SOUL.md, IDENTITY.md e USER.md vengono inoltrati come istruzioni di collaborazione circoscritte al turno. I subagenti Codex nativi non le ereditano, evitando così che i turni dei subagenti acquisiscano la persona e il profilo utente dell'agente padre.
• Anche l'elenco compatto delle Skills OpenClaw caricate viene inoltrato come istruzioni per gli sviluppatori relative alla collaborazione e circoscritte al turno, pertanto nemmeno i subagenti Codex nativi lo ereditano.
• Il contenuto di HEARTBEAT.md non viene inserito; i turni Heartbeat ricevono un riferimento in modalità collaborazione per leggere il file quando esiste e non è vuoto.
• Il contenuto di MEMORY.md proveniente dall'area di lavoro configurata dell'agente non viene incollato nell'input del turno Codex nativo quando gli strumenti di memoria sono disponibili per tale area di lavoro; quando esiste, l'harness aggiunge un breve riferimento alla memoria dell'area di lavoro nelle istruzioni per gli sviluppatori relative alla collaborazione e circoscritte al turno, e Codex dovrebbe usare memory_search o memory_get quando la memoria persistente è pertinente. Se gli strumenti sono disabilitati, la ricerca nella memoria non è disponibile oppure l'area di lavoro attiva è diversa da quella della memoria dell'agente, MEMORY.md usa invece il normale percorso limitato del contesto del turno.
• BOOTSTRAP.md, quando presente, viene inoltrato come contesto di riferimento dell'input del turno OpenClaw.

Sostituzioni tramite variabili d'ambiente

Le sostituzioni tramite variabili d'ambiente rimangono disponibili per i test locali:

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

OPENCLAW_CODEX_APP_SERVER_BIN ignora il binario gestito quando appServer.command non è impostato.

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 è stato rimosso. Usare invece plugins.entries.codex.config.appServer.mode: "guardian" oppure OPENCLAW_CODEX_APP_SERVER_MODE=guardian per test locali occasionali. La configurazione è preferibile per distribuzioni ripetibili, poiché mantiene il comportamento del Plugin nello stesso file revisionato del resto della configurazione dell'harness Codex.

Argomenti correlati

• Harness Codex
• Runtime dell'harness Codex
• Supervisione Codex
• Plugin Codex nativi
• Uso del computer con Codex
• Provider OpenAI
• Riferimento della configurazione