---
read_when:
    - Vuoi usare l'harness app-server Codex incluso
    - Ti servono esempi di configurazione dell'harness Codex
    - Vuoi che le distribuzioni solo Codex falliscano anziché ripiegare su PI
summary: Esegui i turni dell'agente integrato di OpenClaw tramite l'ambiente app-server di Codex incluso
title: Harness di Codex
x-i18n:
    generated_at: "2026-05-02T23:39:25Z"
    model: gpt-5.5
    provider: openai
    source_hash: 8ffa0cbb28422b2ed8d7c0eef6ee0222072c523d170b4b33597bb37bd3fa9700
    source_path: plugins/codex-harness.md
    workflow: 16
---

Il Plugin `codex` incluso consente a OpenClaw di eseguire turni agent incorporati attraverso l'app-server Codex invece che tramite l'harness PI integrato.

Usalo quando vuoi che Codex possieda la sessione agent di basso livello: rilevamento dei modelli, ripresa nativa del thread, Compaction nativa ed esecuzione app-server. OpenClaw continua a possedere i canali chat, i file di sessione, la selezione del modello, gli strumenti, le approvazioni, la consegna dei media e il mirror visibile della trascrizione.

Quando un turno chat sorgente viene eseguito attraverso l'harness Codex, le risposte visibili usano per impostazione predefinita lo strumento `message` di OpenClaw se la distribuzione non ha configurato esplicitamente `messages.visibleReplies`. L'agent può comunque completare privatamente il proprio turno Codex; pubblica sul canale solo quando chiama `message(action="send")`. Imposta `messages.visibleReplies: "automatic"` per mantenere le risposte finali delle chat dirette sul percorso legacy di consegna automatica.

Anche i turni Heartbeat Codex ricevono per impostazione predefinita lo strumento `heartbeat_respond`, così l'agent può registrare se il risveglio deve restare silenzioso o notificare senza codificare quel flusso di controllo nel testo finale.

Se stai cercando di orientarti, inizia da
[Runtime agent](/it/concepts/agent-runtimes). In breve:
`openai/gpt-5.5` è il riferimento del modello, `codex` è il runtime, e Telegram,
Discord, Slack o un altro canale resta la superficie di comunicazione.

## Configurazione rapida

La maggior parte degli utenti che vuole "Codex in OpenClaw" desidera questo percorso: accedere con un abbonamento ChatGPT/Codex, poi eseguire turni agent incorporati attraverso il runtime nativo dell'app-server Codex. Il riferimento del modello resta comunque canonico come
`openai/gpt-*`; l'autenticazione dell'abbonamento proviene dall'account/profilo Codex, non da un prefisso modello `openai-codex/*`.

Per prima cosa accedi con Codex OAuth se non lo hai già fatto:

```bash
openclaw models auth login --provider openai-codex
```

Poi abilita il Plugin `codex` incluso e forza il runtime Codex:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}
```

Se la tua configurazione usa `plugins.allow`, includi anche `codex` lì:

```json5
{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
```

Non usare `openai-codex/gpt-*` quando intendi il runtime nativo Codex. Quel prefisso
è il percorso esplicito "Codex OAuth tramite PI". Le modifiche di configurazione si applicano alle sessioni nuove o reimpostate; le sessioni esistenti mantengono il runtime registrato.

## Cosa cambia questo Plugin

Il Plugin `codex` incluso contribuisce diverse capacità distinte:

| Capacità                          | Come si usa                                         | Cosa fa                                                                       |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| Runtime incorporato nativo        | `agentRuntime.id: "codex"`                          | Esegue i turni agent incorporati di OpenClaw attraverso l'app-server Codex.   |
| Comandi nativi di controllo chat  | `/codex bind`, `/codex resume`, `/codex steer`, ... | Associa e controlla thread dell'app-server Codex da una conversazione di messaggistica. |
| Provider/catalogo app-server Codex | internali `codex`, esposti attraverso l'harness     | Consente al runtime di rilevare e validare i modelli app-server.              |
| Percorso di comprensione media Codex | percorsi di compatibilità modello-immagine `codex/*` | Esegue turni app-server Codex limitati per modelli di comprensione immagini supportati. |
| Relay hook nativo                 | Hook del Plugin attorno a eventi nativi Codex       | Consente a OpenClaw di osservare/bloccare eventi nativi Codex supportati di strumenti/finalizzazione. |

Abilitare il Plugin rende disponibili queste capacità. **Non**:

- inizia a usare Codex per ogni modello OpenAI
- converte i riferimenti modello `openai-codex/*` nel runtime nativo
- rende ACP/acpx il percorso Codex predefinito
- cambia al volo sessioni esistenti che hanno già registrato un runtime PI
- sostituisce la consegna sui canali OpenClaw, i file di sessione, l'archiviazione dei profili di autenticazione o il routing dei messaggi

Lo stesso Plugin possiede anche la superficie nativa dei comandi di controllo chat `/codex`. Se il Plugin è abilitato e l'utente chiede di associare, riprendere, guidare, arrestare o ispezionare thread Codex dalla chat, gli agent dovrebbero preferire `/codex ...` rispetto ad ACP. ACP resta il fallback esplicito quando l'utente chiede ACP/acpx o sta testando l'adapter ACP Codex.

I turni nativi Codex mantengono gli hook Plugin di OpenClaw come livello pubblico di compatibilità.
Questi sono hook OpenClaw in-process, non hook di comando Codex `hooks.json`:

- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `before_tool_call`, `after_tool_call`
- `before_message_write` per record di trascrizione duplicati
- `before_agent_finalize` tramite relay Codex `Stop`
- `agent_end`

I Plugin possono anche registrare middleware dei risultati degli strumenti indipendente dal runtime per riscrivere i risultati degli strumenti dinamici di OpenClaw dopo che OpenClaw esegue lo strumento e prima che il risultato venga restituito a Codex. Questo è separato dall'hook Plugin pubblico
`tool_result_persist`, che trasforma le scritture dei risultati degli strumenti nella trascrizione possedute da OpenClaw.

Per la semantica degli hook Plugin, vedi [Hook dei Plugin](/it/plugins/hooks)
e [Comportamento delle guardie dei Plugin](/it/tools/plugin).

L'harness è disattivato per impostazione predefinita. Le nuove configurazioni dovrebbero mantenere i riferimenti modello OpenAI canonici come `openai/gpt-*` e forzare esplicitamente
`agentRuntime.id: "codex"` o `OPENCLAW_AGENT_RUNTIME=codex` quando vogliono l'esecuzione nativa app-server. I riferimenti modello legacy `codex/*` continuano a selezionare automaticamente l'harness per compatibilità, ma i prefissi provider legacy supportati da runtime non vengono mostrati come normali scelte modello/provider.

Se il Plugin `codex` è abilitato ma il modello primario è ancora
`openai-codex/*`, `openclaw doctor` avvisa invece di cambiare il percorso. È intenzionale: `openai-codex/*` resta il percorso PI Codex OAuth/abbonamento, e l'esecuzione nativa app-server resta una scelta esplicita di runtime.

## Mappa dei percorsi

Usa questa tabella prima di modificare la configurazione:

| Comportamento desiderato                          | Riferimento modello       | Configurazione runtime                 | Percorso auth/profilo        | Etichetta di stato prevista    |
| ------------------------------------------------- | ------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ |
| Abbonamento ChatGPT/Codex con runtime nativo Codex | `openai/gpt-*`            | `agentRuntime.id: "codex"`             | Codex OAuth o account Codex  | `Runtime: OpenAI Codex`        |
| API OpenAI tramite runner OpenClaw normale        | `openai/gpt-*`            | omesso o `runtime: "pi"`               | Chiave API OpenAI            | `Runtime: OpenClaw Pi Default` |
| Abbonamento ChatGPT/Codex tramite PI              | `openai-codex/gpt-*`      | omesso o `runtime: "pi"`               | Provider OpenAI Codex OAuth  | `Runtime: OpenClaw Pi Default` |
| Provider misti con modalità auto conservativa     | riferimenti specifici del provider | `agentRuntime.id: "auto"`       | Per provider selezionato     | Dipende dal runtime selezionato |
| Sessione adapter ACP Codex esplicita              | dipendente da prompt/modello ACP | `sessions_spawn` con `runtime: "acp"` | Auth backend ACP             | Stato task/sessione ACP        |

La distinzione importante è provider rispetto a runtime:

- `openai-codex/*` risponde a "quale percorso provider/auth deve usare PI?"
- `agentRuntime.id: "codex"` risponde a "quale loop deve eseguire questo
  turno incorporato?"
- `/codex ...` risponde a "quale conversazione nativa Codex deve associare
  o controllare questa chat?"
- ACP risponde a "quale processo harness esterno deve avviare acpx?"

## Scegli il prefisso modello corretto

I percorsi della famiglia OpenAI sono specifici per prefisso. Per la configurazione comune abbonamento più runtime nativo Codex, usa `openai/*` con `agentRuntime.id: "codex"`.
Usa `openai-codex/*` solo quando vuoi intenzionalmente Codex OAuth tramite PI:

| Riferimento modello                          | Percorso runtime                            | Quando usarlo                                                            |
| -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------ |
| `openai/gpt-5.4`                             | Provider OpenAI tramite impianto OpenClaw/PI | Vuoi accesso corrente diretto all'API OpenAI Platform con `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.5`                       | OpenAI Codex OAuth tramite OpenClaw/PI      | Vuoi autenticazione con abbonamento ChatGPT/Codex con il runner PI predefinito. |
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness app-server Codex                    | Vuoi autenticazione con abbonamento ChatGPT/Codex con esecuzione nativa Codex. |

GPT-5.5 può comparire sia sui percorsi con chiave API OpenAI diretta sia sui percorsi di abbonamento Codex quando il tuo account li espone. Usa `openai/gpt-5.5` con l'harness app-server Codex per il runtime nativo Codex, `openai-codex/gpt-5.5` per PI OAuth, oppure
`openai/gpt-5.5` senza override runtime Codex per traffico diretto con chiave API.

I riferimenti legacy `codex/gpt-*` restano accettati come alias di compatibilità. La migrazione di compatibilità di Doctor riscrive i riferimenti runtime primari legacy in riferimenti modello canonici e registra separatamente la policy runtime, mentre i riferimenti legacy solo fallback restano invariati perché il runtime è configurato per l'intero contenitore agent.
Le nuove configurazioni PI Codex OAuth dovrebbero usare `openai-codex/gpt-*`; le nuove configurazioni con harness nativo app-server dovrebbero usare `openai/gpt-*` più
`agentRuntime.id: "codex"`.

`agents.defaults.imageModel` segue la stessa distinzione di prefisso. Usa
`openai-codex/gpt-*` quando la comprensione delle immagini deve passare attraverso il percorso provider OpenAI Codex OAuth. Usa `codex/gpt-*` quando la comprensione delle immagini deve passare attraverso un turno app-server Codex limitato. Il modello app-server Codex deve dichiarare il supporto per input immagine; i modelli Codex solo testo falliscono prima dell'avvio del turno media.

Usa `/status` per confermare l'harness effettivo per la sessione corrente. Se la selezione è sorprendente, abilita il logging di debug per il sottosistema `agents/harness`
e ispeziona il record strutturato `agent harness selected` del Gateway. Include l'id harness selezionato, il motivo della selezione, la policy runtime/fallback e, in modalità `auto`, il risultato del supporto di ogni candidato Plugin.

### Cosa significano gli avvisi di doctor

`openclaw doctor` avvisa quando tutte queste condizioni sono vere:

- il Plugin `codex` incluso è abilitato o consentito
- il modello primario di un agent è `openai-codex/*`
- il runtime effettivo di quell'agent non è `codex`

Questo avviso esiste perché gli utenti spesso si aspettano che "Plugin Codex abilitato" implichi
"runtime nativo app-server Codex." OpenClaw non fa questo salto. L'avviso significa:

- **Non è necessaria alcuna modifica** se intendevi ChatGPT/Codex OAuth tramite PI.
- Cambia il modello in `openai/<model>` e imposta
  `agentRuntime.id: "codex"` se intendevi l'esecuzione nativa app-server.
- Le sessioni esistenti richiedono comunque `/new` o `/reset` dopo una modifica runtime,
  perché i pin del runtime di sessione sono persistenti.

La selezione dell'harness non è un controllo di sessione live. Quando viene eseguito un turno incorporato,
OpenClaw registra l'id dell'harness selezionato su quella sessione e continua a usarlo per i turni successivi nello stesso id sessione. Cambia la configurazione `agentRuntime` o
`OPENCLAW_AGENT_RUNTIME` quando vuoi che le sessioni future usino un altro harness;
usa `/new` o `/reset` per avviare una nuova sessione prima di passare una conversazione esistente tra PI e Codex. Questo evita di riprodurre una trascrizione attraverso due sistemi di sessione nativi incompatibili.

Le sessioni legacy create prima dei pin harness vengono trattate come vincolate a PI una volta che hanno cronologia di trascrizione. Usa `/new` o `/reset` per far entrare quella conversazione in Codex dopo aver cambiato configurazione.

`/status` mostra il runtime del modello effettivo. L'harness PI predefinito appare come
`Runtime: OpenClaw Pi Default`, mentre l'harness app-server Codex appare come
`Runtime: OpenAI Codex`.

## Requisiti

- OpenClaw con il plugin `codex` in bundle disponibile.
- Codex app-server `0.125.0` o versione successiva. Il plugin in bundle gestisce per impostazione predefinita un binario Codex app-server compatibile, quindi i comandi locali `codex` su `PATH` non influiscono sul normale avvio dell'harness.
- Autenticazione Codex disponibile per il processo app-server o per il bridge di autenticazione Codex di OpenClaw. Gli avvii locali dell'app-server usano una home Codex gestita da OpenClaw per ciascun agente e un `HOME` figlio isolato, quindi per impostazione predefinita non leggono il tuo account personale `~/.codex`, le Skills, i plugin, la configurazione, lo stato dei thread o le Skills native in `$HOME/.agents/skills`.

Il plugin blocca handshake dell'app-server meno recenti o senza versione. Questo mantiene OpenClaw sulla superficie del protocollo rispetto alla quale è stato testato.

Per i test smoke live e Docker, l'autenticazione di solito proviene dall'account Codex CLI o da un profilo di autenticazione OpenClaw `openai-codex`. Gli avvii locali dell'app-server stdio possono anche ripiegare su `CODEX_API_KEY` / `OPENAI_API_KEY` quando non è presente alcun account.

## File di bootstrap del workspace

Codex gestisce `AGENTS.md` direttamente tramite il rilevamento nativo della documentazione di progetto. OpenClaw non scrive file di documentazione di progetto Codex sintetici né dipende dai nomi file di fallback di Codex per i file persona, perché i fallback di Codex si applicano solo quando manca `AGENTS.md`.

Per la parità del workspace OpenClaw, l'harness Codex risolve gli altri file di bootstrap (`SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` e `MEMORY.md`, quando presenti) e li inoltra tramite le istruzioni di configurazione Codex su `thread/start` e `thread/resume`. Questo mantiene visibile `SOUL.md` e il relativo contesto persona/profilo del workspace senza duplicare `AGENTS.md`.

## Aggiungere Codex insieme ad altri modelli

Non impostare `agentRuntime.id: "codex"` globalmente se lo stesso agente deve poter passare liberamente tra Codex e modelli di provider non Codex. Un runtime forzato si applica a ogni turno incorporato per quell'agente o sessione. Se selezioni un modello Anthropic mentre quel runtime è forzato, OpenClaw prova comunque l'harness Codex e fallisce in modo chiuso invece di instradare silenziosamente quel turno tramite PI.

Usa invece una di queste forme:

- Metti Codex su un agente dedicato con `agentRuntime.id: "codex"`.
- Mantieni l'agente predefinito su `agentRuntime.id: "auto"` e il fallback PI per il normale utilizzo misto dei provider.
- Usa i riferimenti legacy `codex/*` solo per compatibilità. Le nuove configurazioni dovrebbero preferire `openai/*` più una policy di runtime Codex esplicita.

Per esempio, questo mantiene l'agente predefinito sulla normale selezione automatica e aggiunge un agente Codex separato:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
        },
      },
    ],
  },
}
```

Con questa forma:

- L'agente predefinito `main` usa il normale percorso del provider e il fallback di compatibilità PI.
- L'agente `codex` usa l'harness Codex app-server.
- Se Codex manca o non è supportato per l'agente `codex`, il turno fallisce invece di usare silenziosamente PI.

## Instradamento dei comandi dell'agente

Gli agenti dovrebbero instradare le richieste utente in base all'intento, non solo alla parola "Codex":

| L'utente chiede di...                                  | L'agente dovrebbe usare...                       |
| ------------------------------------------------------ | ------------------------------------------------ |
| "Associa questa chat a Codex"                          | `/codex bind`                                    |
| "Riprendi qui il thread Codex `<id>`"                  | `/codex resume <id>`                             |
| "Mostra i thread Codex"                                | `/codex threads`                                 |
| "Apri una segnalazione di supporto per una cattiva esecuzione Codex" | `/diagnostics [note]`                            |
| "Invia solo feedback Codex per questo thread allegato" | `/codex diagnostics [note]`                      |
| "Usa il mio abbonamento ChatGPT/Codex con il runtime Codex" | `openai/*` più `agentRuntime.id: "codex"`       |
| "Usa il mio abbonamento ChatGPT/Codex tramite PI"      | riferimenti modello `openai-codex/*`             |
| "Esegui Codex tramite ACP/acpx"                        | ACP `sessions_spawn({ runtime: "acp", ... })`    |
| "Avvia Claude Code/Gemini/OpenCode/Cursor in un thread" | ACP/acpx, non `/codex` e non sotto-agenti nativi |

OpenClaw pubblicizza agli agenti la guida di spawn ACP solo quando ACP è abilitato, instradabile e supportato da un backend runtime caricato. Se ACP non è disponibile, il prompt di sistema e le skill del plugin non dovrebbero insegnare all'agente l'instradamento ACP.

## Distribuzioni solo Codex

Forza l'harness Codex quando devi dimostrare che ogni turno agente incorporato usa Codex. I runtime dei plugin espliciti hanno come impostazione predefinita nessun fallback PI, quindi `fallback: "none"` è opzionale ma spesso utile come documentazione:

```json5
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}
```

Override tramite ambiente:

```bash
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```

Con Codex forzato, OpenClaw fallisce in anticipo se il plugin Codex è disabilitato, se l'app-server è troppo vecchio o se l'app-server non può avviarsi. Imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=pi` solo se vuoi intenzionalmente che PI gestisca la selezione mancante dell'harness.

## Codex per agente

Puoi rendere un agente solo Codex mentre l'agente predefinito mantiene la normale selezione automatica:

```json5
{
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
          fallback: "none",
        },
      },
    ],
  },
}
```

Usa i normali comandi di sessione per cambiare agenti e modelli. `/new` crea una nuova sessione OpenClaw e l'harness Codex crea o riprende il proprio thread app-server sidecar secondo necessità. `/reset` cancella il binding della sessione OpenClaw per quel thread e consente al turno successivo di risolvere di nuovo l'harness dalla configurazione corrente.

## Rilevamento dei modelli

Per impostazione predefinita, il plugin Codex chiede all'app-server i modelli disponibili. Se il rilevamento fallisce o scade, usa un catalogo di fallback in bundle per:

- GPT-5.5
- GPT-5.4 mini
- GPT-5.2

Puoi regolare il rilevamento in `plugins.entries.codex.config.discovery`:

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

Disabilita il rilevamento quando vuoi che l'avvio eviti di interrogare Codex e resti sul catalogo di fallback:

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

## Connessione e policy dell'app-server

Per impostazione predefinita, il plugin avvia localmente il binario Codex gestito da OpenClaw con:

```bash
codex app-server --listen stdio://
```

Il binario gestito è distribuito con il pacchetto del plugin `codex`. Questo mantiene la versione dell'app-server legata al plugin in bundle invece che a qualunque Codex CLI separato sia installato localmente. Imposta `appServer.command` solo quando vuoi intenzionalmente eseguire un eseguibile diverso.

Per impostazione predefinita, OpenClaw avvia le sessioni locali dell'harness Codex in modalità YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` e `sandbox: "danger-full-access"`. Questa è la postura dell'operatore locale attendibile usata per gli Heartbeat autonomi: Codex può usare strumenti shell e di rete senza fermarsi su prompt di approvazione nativi a cui nessuno è presente per rispondere.

Per attivare le approvazioni revisionate dal guardian Codex, imposta `appServer.mode:
"guardian"`:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "fast",
          },
        },
      },
    },
  },
}
```

La modalità Guardian usa il percorso di approvazione con revisione automatica nativo di Codex. Quando Codex chiede di uscire dalla sandbox, scrivere fuori dal workspace o aggiungere permessi come l'accesso di rete, Codex instrada quella richiesta di approvazione al revisore nativo invece che a un prompt umano. Il revisore applica il framework di rischio di Codex e approva o nega la richiesta specifica. Usa Guardian quando vuoi più protezioni rispetto alla modalità YOLO ma hai comunque bisogno che agenti non presidiati facciano progressi.

Il preset `guardian` si espande in `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` e `sandbox: "workspace-write"`. I singoli campi di policy continuano a sovrascrivere `mode`, quindi le distribuzioni avanzate possono combinare il preset con scelte esplicite. Il valore di revisore precedente `guardian_subagent` è ancora accettato come alias di compatibilità, ma le nuove configurazioni dovrebbero usare `auto_review`.

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

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://127.0.0.1:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}
```

Gli avvii stdio dell'app-server ereditano per impostazione predefinita l'ambiente di processo di OpenClaw, ma OpenClaw possiede il bridge dell'account Codex app-server e imposta sia `CODEX_HOME` sia `HOME` su directory per agente nello stato OpenClaw di quell'agente. Il loader delle skill 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 le Skills native Codex, i plugin, la configurazione, gli account e lo stato dei thread limitati all'agente OpenClaw invece di farli trapelare dalla home personale dell'operatore per Codex CLI.

I plugin OpenClaw e gli snapshot delle skill OpenClaw continuano a passare tramite il registro dei plugin e il loader delle skill propri di OpenClaw. Gli asset personali Codex CLI no. Se hai skill o plugin utili di Codex CLI che dovrebbero diventare parte di un agente OpenClaw, inventariali esplicitamente:

```bash
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes
```

Il provider di migrazione Codex copia le skill nel workspace dell'agente OpenClaw corrente. I plugin nativi Codex, gli hook e i file di configurazione vengono segnalati o archiviati per revisione manuale invece di essere attivati automaticamente, perché possono eseguire comandi, esporre server MCP o contenere credenziali.

L'autenticazione viene selezionata in questo ordine:

1. Un profilo di autenticazione 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'autenticazione OpenAI è ancora richiesta.

Quando OpenClaw rileva un profilo di autenticazione Codex in stile abbonamento ChatGPT, rimuove `CODEX_API_KEY` e `OPENAI_API_KEY` dal processo figlio Codex generato. Questo mantiene le chiavi API a livello Gateway disponibili per embedding o modelli OpenAI diretti senza far addebitare per errore i turni nativi Codex app-server tramite l'API. I profili espliciti con chiave API Codex e il fallback con chiave env stdio locale usano il login dell'app-server invece dell'env ereditato dal processo figlio. Le connessioni WebSocket app-server non ricevono il fallback della chiave API env del Gateway; usa un profilo di autenticazione esplicito o l'account proprio dell'app-server remoto.

Se una distribuzione richiede un ulteriore isolamento dell'ambiente, aggiungi quelle variabili a `appServer.clearEnv`:

```json5
{
  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.

Gli strumenti dinamici di Codex usano per impostazione predefinita il profilo `native-first`. In questa modalità,
OpenClaw non espone strumenti dinamici che duplicano le operazioni di workspace
native di Codex: `read`, `write`, `edit`, `apply_patch`, `exec`, `process` e
`update_plan`. Gli strumenti di integrazione OpenClaw come messaggistica, sessioni, media,
Cron, browser, nodi, Gateway, `heartbeat_respond` e `web_search` restano
disponibili.

Campi Plugin Codex di primo livello supportati:

| Campo                      | Predefinito      | Significato                                                                               |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `codexDynamicToolsProfile` | `"native-first"` | Usa `"openclaw-compat"` per esporre l'intero set di strumenti dinamici OpenClaw all'app-server Codex. |
| `codexDynamicToolsExclude` | `[]`             | Nomi aggiuntivi di strumenti dinamici OpenClaw da omettere dai turni dell'app-server Codex.               |

Campi `appServer` supportati:

| Campo               | Predefinito                            | Significato                                                                                                                                                                                                                              |
| ------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transport`         | `"stdio"`                              | `"stdio"` genera Codex; `"websocket"` si connette a `url`.                                                                                                                                                                             |
| `command`           | binario Codex gestito                  | Eseguibile per il trasporto stdio. Lascialo non impostato per usare il binario gestito; impostalo solo per una sostituzione esplicita.                                                                                                                         |
| `args`              | `["app-server", "--listen", "stdio://"]` | Argomenti per il trasporto stdio.                                                                                                                                                                                                       |
| `url`               | non impostato                          | URL WebSocket dell'app-server.                                                                                                                                                                                                            |
| `authToken`         | non impostato                          | Token bearer per il trasporto WebSocket.                                                                                                                                                                                                |
| `headers`           | `{}`                                   | Header WebSocket aggiuntivi.                                                                                                                                                                                                             |
| `clearEnv`          | `[]`                                   | Nomi di variabili d'ambiente aggiuntive rimosse dal processo app-server stdio generato dopo che OpenClaw ha costruito il suo ambiente ereditato. `CODEX_HOME` e `HOME` sono riservati all'isolamento Codex per agente di OpenClaw negli avvii locali. |
| `requestTimeoutMs`  | `60000`                                | Timeout per le chiamate del piano di controllo dell'app-server.                                                                                                                                                                                          |
| `mode`              | `"yolo"`                               | Preset per l'esecuzione YOLO o con revisione guardian.                                                                                                                                                                                      |
| `approvalPolicy`    | `"never"`                              | Criterio di approvazione nativo Codex inviato all'avvio/ripresa/turno del thread.                                                                                                                                                                       |
| `sandbox`           | `"danger-full-access"`                 | Modalità sandbox nativa Codex inviata all'avvio/ripresa del thread.                                                                                                                                                                               |
| `approvalsReviewer` | `"user"`                               | Usa `"auto_review"` per lasciare che Codex esamini le richieste di approvazione native. `guardian_subagent` resta un alias legacy.                                                                                                                         |
| `serviceTier`       | non impostato                          | Livello di servizio app-server Codex opzionale: `"fast"`, `"flex"` o `null`. I valori legacy non validi vengono ignorati.                                                                                                                            |

Le chiamate agli strumenti dinamici di proprietà di OpenClaw sono limitate indipendentemente da
`appServer.requestTimeoutMs`: ogni richiesta Codex `item/tool/call` deve ricevere
una risposta OpenClaw entro 30 secondi. In caso di 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 Codex con ambito di turno, l'harness
si aspetta anche che Codex concluda il turno nativo con `turn/completed`. Se
l'app-server resta silenzioso per 60 secondi dopo quella risposta, OpenClaw tenta al meglio
di interrompere il turno Codex, registra un timeout diagnostico e libera la corsia
della sessione OpenClaw, così i messaggi di chat successivi non restano in coda dietro a un turno
nativo obsoleto.

Gli override d'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` ignora 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 è
preferibile per distribuzioni ripetibili perché mantiene il comportamento del Plugin nello
stesso file revisionato del resto della configurazione dell'harness Codex.

## Computer use

Computer Use è trattato nella propria guida di configurazione:
[Codex Computer Use](/it/plugins/codex-computer-use).

In breve: OpenClaw non include l'app di controllo del desktop né esegue
azioni desktop direttamente. Prepara l'app-server Codex, verifica che il server MCP
`computer-use` sia disponibile e poi lascia che Codex gestisca le chiamate agli strumenti MCP
native durante i turni in modalità Codex.

Per l'accesso diretto al driver TryCua al di fuori del flusso marketplace Codex, registra
`cua-driver mcp` con `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`.
Vedi [Codex Computer Use](/it/plugins/codex-computer-use) per la distinzione
tra Computer Use di proprietà di Codex e registrazione MCP diretta.

Configurazione minima:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          computerUse: {
            autoInstall: true,
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}
```

La configurazione può essere verificata o installata dalla superficie dei comandi:

- `/codex computer-use status`
- `/codex computer-use install`
- `/codex computer-use install --source <marketplace-source>`
- `/codex computer-use install --marketplace-path <path>`

Computer Use è specifico per macOS e può richiedere autorizzazioni locali del sistema operativo prima che il
server MCP Codex possa controllare le app. Se `computerUse.enabled` è true e il server MCP
non è disponibile, i turni in modalità Codex falliscono prima dell'avvio del thread invece di
eseguire silenziosamente senza gli strumenti nativi di Computer Use. Vedi
[Codex Computer Use](/it/plugins/codex-computer-use) per scelte del marketplace,
limiti del catalogo remoto, motivi di stato e risoluzione dei problemi.

Quando `computerUse.autoInstall` è true, OpenClaw può registrare il marketplace standard
Codex Desktop incluso da
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` se Codex
non ha ancora rilevato un marketplace locale. Usa `/new` o `/reset` dopo
aver modificato la configurazione del runtime o di Computer Use, così le sessioni esistenti non mantengono un vecchio
binding di PI o thread Codex.

## Ricette comuni

Codex locale con trasporto stdio predefinito:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
```

Validazione dell'harness solo Codex:

```json5
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
```

Approvazioni Codex con revisione guardian:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            approvalPolicy: "on-request",
            approvalsReviewer: "auto_review",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}
```

App-server remoto con header espliciti:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: {
              "X-OpenClaw-Agent": "main",
            },
          },
        },
      },
    },
  },
}
```

Il cambio di modello resta controllato da OpenClaw. Quando una sessione OpenClaw è collegata
a un thread Codex esistente, il turno successivo invia nuovamente all'app-server il modello
OpenAI, il provider, il criterio di approvazione, la sandbox e il livello di servizio
attualmente selezionati. Passare da `openai/gpt-5.5` a `openai/gpt-5.2` mantiene il
binding del thread ma chiede a Codex di continuare con il nuovo modello selezionato.

## Comando Codex

Il Plugin incluso registra `/codex` come comando slash autorizzato. È
generico e funziona su qualsiasi canale che supporti i comandi testuali OpenClaw.

Forme comuni:

- `/codex status` mostra connettività app-server live, modelli, account, limiti di frequenza, server MCP e skills.
- `/codex models` elenca i modelli live dell'app-server Codex.
- `/codex threads [filter]` elenca i thread Codex recenti.
- `/codex resume <thread-id>` collega la sessione OpenClaw corrente a un thread Codex esistente.
- `/codex compact` chiede all'app-server Codex di compattare il thread collegato.
- `/codex review` avvia la revisione nativa Codex per il thread collegato.
- `/codex diagnostics [note]` chiede conferma prima di inviare il feedback diagnostico Codex per il thread collegato.
- `/codex computer-use status` controlla il plugin Computer Use configurato e il server MCP.
- `/codex computer-use install` installa il plugin Computer Use configurato e ricarica i server MCP.
- `/codex account` mostra lo stato dell'account e dei limiti di frequenza.
- `/codex mcp` elenca lo stato dei server MCP dell'app-server Codex.
- `/codex skills` elenca le skills dell'app-server Codex.

### Flusso di debug comune

Quando un agente basato su Codex fa qualcosa di inatteso in Telegram, Discord, Slack,
o in un altro canale, inizia dalla conversazione in cui si è verificato il problema:

1. Esegui `/diagnostics bad tool choice after image upload` o un'altra breve nota
   che descriva ciò che hai visto.
2. Approva la richiesta di diagnostica una volta. L'approvazione crea lo zip
   diagnostico del Gateway locale e, poiché la sessione usa l'harness Codex, invia anche
   il bundle di feedback Codex pertinente ai server OpenAI.
3. Copia la risposta diagnostica completata nel bug report o nel thread di supporto.
   Include il percorso del bundle locale, il riepilogo della privacy, gli ID sessione OpenClaw,
   gli ID thread Codex e una riga `Inspect locally` per ogni thread Codex.
4. Se vuoi eseguire il debug della run in autonomia, esegui il comando `Inspect locally`
   stampato in un terminale. Ha l'aspetto di `codex resume <thread-id>` e apre il
   thread Codex nativo così puoi ispezionare la conversazione, continuarla localmente,
   o chiedere a Codex perché ha scelto uno strumento o un piano specifico.

Usa `/codex diagnostics [note]` solo quando vuoi specificamente l'upload del
feedback Codex per il thread attualmente collegato senza il bundle diagnostico completo
del Gateway OpenClaw. Per la maggior parte delle segnalazioni di supporto, `/diagnostics [note]` è
il punto di partenza migliore perché collega lo stato del Gateway locale e gli ID
thread Codex in un'unica risposta. Vedi [Esportazione diagnostica](/it/gateway/diagnostics)
per il modello di privacy completo e il comportamento nelle chat di gruppo.

Il nucleo OpenClaw espone anche `/diagnostics [note]`, solo per gli owner, come comando
generale di diagnostica del Gateway. Il prompt di approvazione mostra il preambolo
sui dati sensibili, linka [Esportazione diagnostica](/it/gateway/diagnostics), e richiede
`openclaw gateway diagnostics export --json` tramite approvazione exec esplicita
ogni volta. Non approvare la diagnostica con una regola allow-all. Dopo l'approvazione,
OpenClaw invia un report incollabile con il percorso del bundle locale e il riepilogo
del manifest. Quando la sessione OpenClaw attiva usa l'harness Codex, quella stessa
approvazione autorizza anche l'invio dei bundle di feedback Codex pertinenti ai
server OpenAI. Il prompt di approvazione dice che verrà inviato feedback Codex, ma
non elenca gli ID sessione o thread Codex prima dell'approvazione.

Se `/diagnostics` viene invocato da un owner in una chat di gruppo, OpenClaw mantiene
pulito il canale condiviso: il gruppo riceve solo un breve avviso, mentre il
preambolo diagnostico, i prompt di approvazione e gli ID sessione/thread Codex vengono inviati
all'owner tramite il percorso di approvazione privato. Se non esiste un percorso owner privato,
OpenClaw rifiuta la richiesta di gruppo e chiede all'owner di eseguirla da un DM.

L'upload Codex approvato chiama `feedback/upload` dell'app-server Codex e chiede
all'app-server di includere i log per ogni thread elencato e i sottothread Codex generati
quando disponibili. L'upload passa attraverso il normale percorso di feedback di Codex verso i
server OpenAI; se il feedback Codex è disabilitato in quell'app-server, il comando restituisce
l'errore dell'app-server. La risposta diagnostica completata elenca i canali,
gli ID sessione OpenClaw, gli ID thread Codex e i comandi locali `codex resume <thread-id>`
per i thread che sono stati inviati. Se neghi o ignori l'approvazione,
OpenClaw non stampa quegli ID Codex. Questo upload non sostituisce l'esportazione
diagnostica del Gateway locale.

`/codex resume` scrive lo stesso file di binding sidecar che l'harness usa per
i turni normali. Al messaggio successivo, OpenClaw riprende quel thread Codex, passa il
modello OpenClaw attualmente selezionato all'app-server e mantiene abilitata la cronologia
estesa.

### Ispezionare un thread Codex dalla CLI

Il modo più rapido per capire una run Codex problematica è spesso aprire direttamente
il thread Codex nativo:

```sh
codex resume <thread-id>
```

Usalo quando noti un bug in una conversazione di canale e vuoi ispezionare la
sessione Codex problematica, continuarla localmente, o chiedere a Codex perché ha fatto una
particolare scelta di strumento o ragionamento. Il percorso più semplice di solito è eseguire
prima `/diagnostics [note]`: dopo averlo approvato, il report completato elenca
ogni thread Codex e stampa un comando `Inspect locally`, per esempio
`codex resume <thread-id>`. Puoi copiare quel comando direttamente in un terminale.

Puoi anche ottenere un ID thread da `/codex binding` per la chat corrente o
`/codex threads [filter]` per i thread recenti dell'app-server Codex, quindi eseguire lo stesso
comando `codex resume` nella tua shell.

La superficie di comando richiede l'app-server Codex `0.125.0` o più recente. I singoli
metodi di controllo vengono segnalati come `unsupported by this Codex app-server` se un
app-server futuro o personalizzato non espone quel metodo JSON-RPC.

## Confini degli hook

L'harness Codex ha tre livelli di hook:

| Livello                               | Owner                    | Scopo                                                               |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| Hook dei plugin OpenClaw              | OpenClaw                 | Compatibilità prodotto/plugin tra harness PI e Codex.               |
| Middleware di estensione app-server Codex | Plugin in bundle OpenClaw | Comportamento dell'adattatore per turno attorno agli strumenti dinamici OpenClaw. |
| Hook nativi Codex                     | Codex                    | Ciclo di vita Codex di basso livello e policy nativa degli strumenti dalla configurazione Codex. |

OpenClaw non usa file Codex `hooks.json` di progetto o globali per instradare
il comportamento dei plugin OpenClaw. Per il bridge supportato di strumenti nativi e autorizzazioni,
OpenClaw inietta una configurazione Codex per thread per `PreToolUse`, `PostToolUse`,
`PermissionRequest` e `Stop`. Altri hook Codex come `SessionStart` e
`UserPromptSubmit` restano controlli a livello Codex; non sono esposti come
hook dei plugin OpenClaw nel contratto v1.

Per gli strumenti dinamici OpenClaw, OpenClaw esegue lo strumento dopo che Codex richiede la
chiamata, quindi OpenClaw attiva il comportamento di plugin e middleware che possiede
nell'adattatore dell'harness. Per gli strumenti nativi Codex, Codex possiede il record canonico dello strumento.
OpenClaw può rispecchiare eventi selezionati, ma non può riscrivere il thread Codex nativo
a meno che Codex esponga quell'operazione tramite app-server o callback degli hook nativi.

Le proiezioni di Compaction e ciclo di vita LLM provengono dalle notifiche dell'app-server Codex
e dallo stato dell'adattatore OpenClaw, non da comandi hook nativi Codex.
Gli eventi `before_compaction`, `after_compaction`, `llm_input` e
`llm_output` di OpenClaw sono osservazioni a livello di adattatore, non acquisizioni byte per byte
della richiesta interna o dei payload di compattazione di Codex.

Le notifiche app-server native Codex `hook/started` e `hook/completed` sono
proiettate come eventi agente `codex_app_server.hook` per traiettoria e debug.
Non invocano hook dei plugin OpenClaw.

## Contratto di supporto V1

La modalità Codex non è PI con una diversa chiamata al modello sotto il cofano. Codex possiede una parte maggiore
del ciclo del modello nativo, e OpenClaw adatta le sue superfici di plugin e sessione
attorno a quel confine.

Supportato nel runtime Codex v1:

| Superficie                                    | Supporto                                | Perché                                                                                                                                                                                               |
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ciclo del modello OpenAI tramite Codex        | Supportato                              | L'app-server Codex possiede il turno OpenAI, la ripresa del thread nativo e la continuazione degli strumenti nativi.                                                                                  |
| Routing e recapito dei canali OpenClaw        | Supportato                              | Telegram, Discord, Slack, WhatsApp, iMessage e altri canali restano fuori dal runtime del modello.                                                                                                    |
| Strumenti dinamici OpenClaw                   | Supportato                              | Codex chiede a OpenClaw di eseguire questi strumenti, quindi OpenClaw resta nel percorso di esecuzione.                                                                                                |
| Plugin di prompt e contesto                   | Supportato                              | OpenClaw costruisce overlay del prompt e proietta il contesto nel turno Codex prima di avviare o riprendere il thread.                                                                                 |
| Ciclo di vita del motore di contesto          | Supportato                              | Assemblaggio, ingestione o manutenzione post-turno, e coordinamento della compattazione del motore di contesto vengono eseguiti per i turni Codex.                                                     |
| Hook degli strumenti dinamici                 | Supportato                              | `before_tool_call`, `after_tool_call` e il middleware dei risultati degli strumenti vengono eseguiti attorno agli strumenti dinamici posseduti da OpenClaw.                                            |
| Hook del ciclo di vita                        | Supportato come osservazioni dell'adattatore | `llm_input`, `llm_output`, `agent_end`, `before_compaction` e `after_compaction` vengono emessi con payload onesti in modalità Codex.                                                                  |
| Gate di revisione della risposta finale       | Supportato tramite il relay degli hook nativi | Codex `Stop` viene inoltrato a `before_agent_finalize`; `revise` chiede a Codex un altro passaggio del modello prima della finalizzazione.                                                             |
| Blocco o osservazione di shell, patch e MCP nativi | Supportato tramite il relay degli hook nativi | Codex `PreToolUse` e `PostToolUse` vengono inoltrati per superfici di strumenti nativi confermate, inclusi i payload MCP su app-server Codex `0.125.0` o più recente. Il blocco è supportato; la riscrittura degli argomenti no. |
| Policy di autorizzazione nativa               | Supportato tramite il relay degli hook nativi | Codex `PermissionRequest` può essere instradato tramite la policy OpenClaw dove il runtime lo espone. Se OpenClaw non restituisce alcuna decisione, Codex continua tramite il suo normale percorso guardian o di approvazione utente. |
| Acquisizione della traiettoria app-server     | Supportato                              | OpenClaw registra la richiesta inviata all'app-server e le notifiche app-server che riceve.                                                                                                            |

Non supportato nel runtime Codex v1:

| Superficie                                         | Confine V1                                                                                                                                      | Percorso futuro                                                                           |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Mutazione degli argomenti degli strumenti nativi   | Gli hook pre-strumento nativi di Codex possono bloccare, ma OpenClaw non riscrive gli argomenti degli strumenti nativi di Codex.                | Richiede il supporto di hook/schema di Codex per sostituire l'input dello strumento.      |
| Cronologia della trascrizione nativa Codex modificabile | Codex possiede la cronologia canonica nativa del thread. OpenClaw possiede un mirror e può proiettare il contesto futuro, ma non dovrebbe modificare interni non supportati. | Aggiungere API app-server esplicite di Codex se serve intervenire sui thread nativi.       |
| `tool_result_persist` per i record degli strumenti nativi di Codex | Quell'hook trasforma le scritture della trascrizione possedute da OpenClaw, non i record degli strumenti nativi di Codex.                       | Potrebbe replicare i record trasformati, ma la riscrittura canonica richiede supporto Codex. |
| Metadati ricchi di compattazione nativa            | OpenClaw osserva l'avvio e il completamento della compattazione, ma non riceve un elenco stabile di elementi mantenuti/scartati, delta di token o payload di riepilogo. | Richiede eventi di compattazione Codex più ricchi.                                        |
| Intervento sulla compattazione                     | Gli hook di compattazione OpenClaw attuali sono a livello di notifica in modalità Codex.                                                        | Aggiungere hook di pre/post compattazione Codex se i Plugin devono porre veto o riscrivere la compattazione nativa. |
| Acquisizione byte per byte della richiesta API al modello | OpenClaw può acquisire richieste e notifiche dell'app-server, ma il core Codex costruisce internamente la richiesta API OpenAI finale.           | Richiede un evento di tracciamento della richiesta al modello Codex o una API di debug.    |

## Strumenti, media e compattazione

L'harness Codex modifica solo l'esecutore dell'agente incorporato a basso livello.

OpenClaw continua a costruire l'elenco degli strumenti e riceve i risultati dinamici degli strumenti dall'harness. Testo, immagini, video, musica, TTS, approvazioni e output degli strumenti di messaggistica continuano attraverso il normale percorso di consegna di OpenClaw.

Il relay degli hook nativi è intenzionalmente generico, ma il contratto di supporto v1 è limitato ai percorsi di strumenti nativi e permessi Codex che OpenClaw testa. Nel runtime Codex, questo include payload shell, patch e MCP `PreToolUse`, `PostToolUse` e `PermissionRequest`. Non dare per scontato che ogni futuro evento hook di Codex sia una superficie Plugin di OpenClaw finché il contratto runtime non lo nomina.

Per `PermissionRequest`, OpenClaw restituisce solo decisioni esplicite di autorizzazione o rifiuto quando la policy decide. Un risultato senza decisione non è un'autorizzazione. Codex lo tratta come assenza di decisione dell'hook e prosegue con il proprio percorso di guardian o approvazione utente.

Le richieste di approvazione degli strumenti MCP di Codex vengono instradate attraverso il flusso di approvazione dei Plugin di OpenClaw quando Codex imposta `_meta.codex_approval_kind` su `"mcp_tool_call"`. I prompt Codex `request_user_input` vengono rimandati alla chat di origine, e il successivo messaggio di follow-up in coda risponde a quella richiesta del server nativo invece di essere indirizzato come contesto aggiuntivo. Le altre richieste di sollecitazione MCP continuano a fallire in modo chiuso.

Lo steering della coda di esecuzione attiva si mappa su `turn/steer` dell'app-server Codex. Con il valore predefinito `messages.queue.mode: "steer"`, OpenClaw raggruppa i messaggi chat in coda per la finestra di quiete configurata e li invia come un'unica richiesta `turn/steer` nell'ordine di arrivo. La modalità legacy `queue` invia richieste `turn/steer` separate. I turni di revisione Codex e di compattazione manuale possono rifiutare lo steering nello stesso turno; in quel caso OpenClaw usa la coda di follow-up quando la modalità selezionata consente il fallback. Vedi [Coda di steering](/it/concepts/queue-steering).

Quando il modello selezionato usa l'harness Codex, la compattazione del thread nativo viene delegata all'app-server Codex. OpenClaw mantiene un mirror della trascrizione per cronologia del canale, ricerca, `/new`, `/reset` e futuri cambi di modello o harness. Il mirror include il prompt utente, il testo finale dell'assistente e record leggeri di ragionamento o piano Codex quando l'app-server li emette. Oggi OpenClaw registra solo i segnali di avvio e completamento della compattazione nativa. Non espone ancora un riepilogo della compattazione leggibile da una persona o un elenco verificabile di quali voci Codex ha mantenuto dopo la compattazione.

Poiché Codex possiede il thread nativo canonico, `tool_result_persist` attualmente non riscrive i record dei risultati degli strumenti nativi di Codex. Si applica solo quando OpenClaw scrive un risultato strumento della trascrizione di sessione posseduta da OpenClaw.

La generazione di media non richiede PI. Immagini, video, musica, PDF, TTS e comprensione dei media continuano a usare le impostazioni provider/modello corrispondenti, come `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` e `messages.tts`.

## Risoluzione dei problemi

**Codex non appare come normale provider `/model`:** questo è previsto per le nuove configurazioni. Seleziona un modello `openai/gpt-*` con `agentRuntime.id: "codex"` (o un ref legacy `codex/*`), abilita `plugins.entries.codex.enabled` e controlla se `plugins.allow` esclude `codex`.

**OpenClaw usa PI invece di Codex:** `agentRuntime.id: "auto"` può ancora usare PI come backend di compatibilità quando nessun harness Codex prende in carico l'esecuzione. Imposta `agentRuntime.id: "codex"` per forzare la selezione di Codex durante i test. Un runtime Codex forzato ora fallisce invece di ricadere su PI, a meno che tu non imposti esplicitamente `agentRuntime.fallback: "pi"`. Una volta selezionato l'app-server Codex, i suoi errori emergono direttamente senza configurazione di fallback aggiuntiva.

**L'app-server viene rifiutato:** aggiorna Codex in modo che l'handshake dell'app-server riporti la versione `0.125.0` o successiva. Le prerelease della stessa versione o le versioni con suffisso di build come `0.125.0-alpha.2` o `0.125.0+custom` vengono rifiutate perché il limite minimo del protocollo stabile `0.125.0` è ciò che OpenClaw testa.

**La scoperta dei modelli è lenta:** riduci `plugins.entries.codex.config.discovery.timeoutMs` o disabilita la scoperta.

**Il trasporto WebSocket fallisce immediatamente:** controlla `appServer.url`, `authToken` e che l'app-server remoto parli la stessa versione del protocollo app-server Codex.

**Un modello non Codex usa PI:** questo è previsto, a meno che tu non abbia forzato `agentRuntime.id: "codex"` per quell'agente o selezionato un ref legacy `codex/*`. I normali ref `openai/gpt-*` e altri ref provider restano sul loro percorso provider normale in modalità `auto`. Se forzi `agentRuntime.id: "codex"`, ogni turno incorporato per quell'agente deve essere un modello OpenAI supportato da Codex.

**Computer Use è installato ma gli strumenti non vengono eseguiti:** controlla `/codex computer-use status` da una sessione nuova. Se uno strumento riporta `Native hook relay unavailable`, usa `/new` o `/reset`; se persiste, riavvia il Gateway per cancellare le registrazioni obsolete degli hook nativi. Se `computer-use.list_apps` va in timeout, riavvia Codex Computer Use o Codex Desktop e riprova.

## Correlati

- [Plugin harness agente](/it/plugins/sdk-agent-harness)
- [Runtime agente](/it/concepts/agent-runtimes)
- [Provider di modelli](/it/concepts/model-providers)
- [Provider OpenAI](/it/providers/openai)
- [Stato](/it/cli/status)
- [Hook dei Plugin](/it/plugins/hooks)
- [Riferimento configurazione](/it/gateway/configuration-reference)
- [Test](/it/help/testing-live#live-codex-app-server-harness-smoke)
