Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Questo riferimento copre la configurazione dettagliata per il Plugin codex incluso. Per le decisioni di configurazione e routing, inizia da Harness Codex.

​
Superficie di configurazione del Plugin

Tutte le impostazioni dell’harness Codex si trovano sotto plugins.entries.codex.config. 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
          appServer: {
            mode: "guardian",
          },
        },
      },
    },
  },
}
Campi di primo livello supportati:
CampoPredefinitoSignificato
discoveryabilitatoImpostazioni di discovery dei modelli per model/list dell’app-server Codex.
appServerapp-server stdio gestitoImpostazioni di trasporto, comando, auth, approvazione, sandbox e timeout.
codexDynamicToolsLoading"searchable"Usa "direct" per inserire gli strumenti dinamici di OpenClaw direttamente nel contesto iniziale degli strumenti Codex.
codexDynamicToolsExclude[]Nomi aggiuntivi degli strumenti dinamici di OpenClaw da omettere dai turni dell’app-server Codex.
codexPluginsdisabilitatoSupporto nativo di plugin/app Codex per plugin curati installati da sorgente migrati. Vedi Plugin Codex nativi.
computerUsedisabilitatoConfigurazione di Codex Computer Use. Vedi Codex Computer Use.

​
Trasporto app-server

Per impostazione predefinita, OpenClaw avvia il binario Codex gestito distribuito con il Plugin incluso: 
codex app-server --listen stdio://
Questo mantiene la versione dell’app-server legata al Plugin codex incluso invece che a qualsiasi CLI Codex separata installata localmente. Imposta appServer.command solo quando vuoi intenzionalmente eseguire un eseguibile diverso. Per un app-server già in esecuzione, usa 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 supportati:
CampoPredefinitoSignificato
transport"stdio""stdio" genera Codex; "websocket" si connette a url.
commandbinario Codex gestitoEseguibile per il trasporto stdio. Lascia non impostato per usare il binario gestito.
args["app-server", "--listen", "stdio://"]Argomenti per il trasporto stdio.
urlnon impostatoURL WebSocket dell’app-server.
authTokennon impostatoToken bearer per il trasporto WebSocket.
headers{}Header WebSocket extra.
clearEnv[]Nomi di variabili d’ambiente extra rimossi dal processo app-server stdio generato dopo che OpenClaw ha costruito il proprio ambiente ereditato.
requestTimeoutMs60000Timeout per le chiamate del piano di controllo dell’app-server.
turnCompletionIdleTimeoutMs60000Finestra di quiete dopo una richiesta app-server con ambito di turno mentre OpenClaw attende turn/completed.
mode"yolo" salvo che i requisiti locali di Codex non consentano YOLOPreset per l’esecuzione YOLO o revisionata da guardian.
approvalPolicy"never" o una policy di approvazione guardian consentitaPolicy di approvazione nativa Codex inviata all’avvio del thread, alla ripresa e al turno.
sandbox"danger-full-access" o una sandbox guardian consentitaModalità sandbox nativa Codex inviata all’avvio e alla ripresa del thread.
approvalsReviewer"user" o un reviewer guardian consentitoUsa "auto_review" per lasciare che Codex revisioni i prompt di approvazione nativi quando consentito.
defaultWorkspaceDirdirectory del processo correnteWorkspace usato da /codex bind quando --cwd è omesso.
serviceTiernon impostatoLivello di servizio app-server Codex facoltativo. "priority" abilita il routing in modalità veloce, "flex" richiede elaborazione flex e null cancella l’override. Il valore legacy "fast" è accettato come "priority".
Il Plugin blocca handshake app-server più vecchi o senza versione. Codex app-server deve riportare la versione stabile 0.125.0 o successiva.

​
Modalità di approvazione e sandbox

Le sessioni app-server stdio locali usano per impostazione predefinita la modalità YOLO: approvalPolicy: "never", approvalsReviewer: "user" e sandbox: "danger-full-access". Questa postura da operatore locale fidato consente ai turni e agli Heartbeat non presidiati di OpenClaw di avanzare senza prompt di approvazione nativi a cui nessuno è presente per rispondere. Se il file dei requisiti di sistema locali di Codex non consente valori impliciti YOLO per approvazione, reviewer o sandbox, OpenClaw considera invece il valore predefinito implicito come guardian e seleziona permessi guardian consentiti. Le voci [[remote_sandbox_config]] corrispondenti all’hostname nello stesso file dei requisiti sono rispettate per la decisione predefinita della sandbox. Imposta appServer.mode: "guardian" per approvazioni Codex revisionate da guardian: 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}
Il preset guardian si espande in approvalPolicy: "on-request", approvalsReviewer: "auto_review" e sandbox: "workspace-write" quando tali valori sono consentiti. I singoli campi di policy sovrascrivono mode. Il valore reviewer più vecchio guardian_subagent è ancora accettato come alias di compatibilità, ma le nuove configurazioni dovrebbero usare auto_review.

​
Auth e isolamento dell’ambiente

Auth viene selezionato in questo ordine:
  1. Un profilo auth OpenClaw Codex esplicito per l’agente.
  2. L’account esistente dell’app-server nella home Codex di quell’agente.
  3. Solo per gli avvii locali dell’app-server stdio, CODEX_API_KEY, poi OPENAI_API_KEY, quando non è presente alcun account app-server e l’auth OpenAI è ancora richiesta.
Quando OpenClaw rileva un profilo auth Codex in stile abbonamento ChatGPT, rimuove CODEX_API_KEY e OPENAI_API_KEY dal processo figlio Codex generato. Questo mantiene disponibili le chiavi API a livello di Gateway per embedding o modelli OpenAI diretti senza far sì che i turni nativi dell’app-server Codex vengano fatturati accidentalmente tramite API. I profili API-key Codex espliciti e il fallback di chiave env stdio locale usano il login app-server invece dell’env ereditato dal processo figlio. Le connessioni WebSocket all’app-server non ricevono il fallback API-key env del Gateway; usa un profilo auth esplicito o l’account proprio dell’app-server remoto. Gli avvii dell’app-server stdio ereditano per impostazione predefinita l’ambiente di processo di OpenClaw, ma OpenClaw possiede il bridge degli account dell’app-server Codex e imposta sia CODEX_HOME sia HOME su directory per-agente nello stato OpenClaw di quell’agente. Il loader di Skills proprio di Codex legge $CODEX_HOME/skills e $HOME/.agents/skills, quindi entrambi i valori sono isolati per gli avvii locali dell’app-server. Questo mantiene Skills, plugin, configurazione, account e stato dei thread nativi Codex limitati all’agente OpenClaw invece di farli trapelare dalla home personale della CLI Codex dell’operatore. I plugin OpenClaw e gli snapshot delle Skills OpenClaw continuano a passare attraverso il registro dei plugin e il loader delle Skills propri di OpenClaw. Gli asset personali della CLI Codex no. Se hai Skills o plugin utili della CLI Codex che dovrebbero diventare parte di un agente OpenClaw, inventariali esplicitamente: 
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes
Se una distribuzione richiede isolamento ambientale aggiuntivo, aggiungi tali variabili a appServer.clearEnv: 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}
appServer.clearEnv influisce solo sul processo figlio app-server Codex generato. CODEX_HOME e HOME rimangono riservati all’isolamento Codex per-agente di OpenClaw negli avvii locali.

​
Strumenti dinamici

Gli strumenti dinamici Codex usano per impostazione predefinita il caricamento searchable. OpenClaw non espone strumenti dinamici che duplicano le operazioni workspace native di Codex:
  • read
  • write
  • edit
  • apply_patch
  • exec
  • process
  • update_plan
Gli altri strumenti di integrazione di OpenClaw, come messaggistica, sessioni, media, cron, browser, nodi, Gateway, heartbeat_respond e web_search, sono disponibili tramite la ricerca strumenti di Codex sotto il namespace openclaw. Questo mantiene più piccolo il contesto iniziale del modello. sessions_yield e le risposte sorgente solo tramite strumento di messaggistica restano dirette perché sono contratti di controllo del turno. Imposta codexDynamicToolsLoading: "direct" solo quando ti connetti a un app-server Codex personalizzato che non può cercare strumenti dinamici differiti o quando esegui 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 in questo ordine:
  • Un argomento timeoutMs positivo per singola chiamata.
  • Per image_generate, agents.defaults.imageGenerationModel.timeoutMs.
  • Per lo strumento di comprensione dei media image, tools.media.image.timeoutSeconds convertito in millisecondi, oppure il valore predefinito media di 60 secondi.
  • Il valore predefinito di 30 secondi per gli strumenti dinamici.
I budget degli strumenti dinamici sono limitati a 600000 ms. Al timeout, OpenClaw interrompe il segnale dello strumento dove supportato e restituisce a Codex una risposta di strumento dinamico non riuscita, così il turno può continuare invece di lasciare la sessione in processing. Dopo che OpenClaw risponde a una richiesta app-server con ambito di turno di Codex, l’harness si aspetta anche che Codex completi il turno nativo con turn/completed. Se l’app-server resta silenzioso per appServer.turnCompletionIdleTimeoutMs dopo quella risposta, OpenClaw tenta al meglio di interrompere il turno Codex, registra un timeout diagnostico e rilascia la corsia della sessione OpenClaw, così i messaggi di chat successivi non vengono messi in coda dietro un turno nativo obsoleto. Qualsiasi notifica non terminale per lo stesso turno, inclusa rawResponseItem/completed, disattiva quel breve watchdog perché Codex ha dimostrato che il turno è ancora vivo. Il watchdog terminale più lungo continua a proteggere i turni realmente bloccati. Le diagnostiche di timeout includono l’ultimo metodo di notifica dell’app-server e, per gli elementi di risposta raw dell’assistente, il tipo dell’elemento, il ruolo, l’id e un’anteprima limitata del testo dell’assistente.

​
Rilevamento dei modelli

Per impostazione predefinita, il plugin Codex chiede all’app-server i modelli disponibili. La disponibilità dei modelli appartiene all’app-server Codex, quindi l’elenco può cambiare quando OpenClaw aggiorna la versione @openai/codex inclusa o quando un deployment punta appServer.command a un binario Codex diverso. La disponibilità può anche essere specifica dell’account. Usa /codex models su un Gateway in esecuzione per vedere il catalogo live per quell’harness e quell’account. Se il rilevamento non riesce o va in timeout, OpenClaw usa un catalogo di fallback incluso per:
  • GPT-5.5
  • GPT-5.4 mini
  • GPT-5.2
L’harness incluso attuale è @openai/codex 0.130.0. Una sonda model/list contro quell’app-server incluso ha restituito:
ID modelloPredefinitoNascostoModalità di inputImpegni di reasoning
gpt-5.5SìNotesto, immaginelow, medium, high, xhigh
gpt-5.4NoNotesto, immaginelow, medium, high, xhigh
gpt-5.4-miniNoNotesto, immaginelow, medium, high, xhigh
gpt-5.3-codexNoNotesto, immaginelow, medium, high, xhigh
gpt-5.3-codex-sparkNoNotestolow, medium, high, xhigh
gpt-5.2NoNotesto, immaginelow, medium, high, xhigh
I modelli nascosti possono essere restituiti dal catalogo dell’app-server per flussi interni o specializzati, ma non sono normali scelte del selettore modelli. Configura il rilevamento sotto plugins.entries.codex.config.discovery: 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}
Disabilita il rilevamento quando vuoi che l’avvio eviti di sondare Codex e usi solo il catalogo di fallback: 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}

​
File di bootstrap del workspace

Codex gestisce AGENTS.md autonomamente tramite il rilevamento nativo dei documenti di progetto. OpenClaw non scrive file sintetici di documenti di progetto Codex né dipende dai nomi file di fallback di Codex per i file persona, perché i fallback di Codex si applicano solo quando AGENTS.md manca. Per la parità del workspace OpenClaw, l’harness Codex risolve gli altri file di bootstrap, inclusi SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md e MEMORY.md quando presenti, e li inoltra tramite le istruzioni per sviluppatori di Codex su thread/start e thread/resume. Questo mantiene visibili il contesto persona e profilo del workspace sulla corsia nativa di Codex che modella il comportamento, senza duplicare AGENTS.md.

​
Override di ambiente

Gli override di ambiente restano 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 bypassa il binario gestito quando appServer.command non è impostato. OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 è stato rimosso. Usa invece plugins.entries.codex.config.appServer.mode: "guardian", oppure OPENCLAW_CODEX_APP_SERVER_MODE=guardian per test locali una tantum. La configurazione è preferita per deployment ripetibili perché mantiene il comportamento del plugin nello stesso file revisionato del resto della configurazione dell’harness Codex.

​
Correlati