Salta al contenuto principale

07 - Codex: cloud, subagenti, skill e MCP per delegare

Delegare a Codex cloud, ai subagenti, alle skill o a un server MCP: che cosa rende ciascun meccanismo, quanto costa e dove i permessi non bastano.

Cosa ne pensi di questo articolo?

07 - Codex: cloud, subagenti, skill e MCP per delegare
OpenAI Codexfedericocalo.dev

In Breve

Delegare a Codex cloud, ai subagenti, alle skill o a un server MCP: che cosa rende ciascun meccanismo, quanto costa e dove i permessi non bastano.

Hai un compito che richiede mezz'ora di attesa, un'indagine con tre domande indipendenti, un flusso che ripeti ogni venerdì, uno strumento aziendale da cui l'agente dovrebbe leggere: Codex offre quattro meccanismi, uno per problema. Codex Cloud esegue un compito in un ambiente remoto con un proprio workspace e prosegue anche a computer spento; costa configurazione, ti obbliga a mandare il codice altrove e non è disponibile con la sola chiave API. I subagenti lanciano più agenti in parallelo dalla stessa sessione: velocizzano le indagini di lettura, consumano più token e non risolvono da soli i conflitti di scrittura. Le skill impacchettano istruzioni ripetibili. Il MCP collega l'agente a strumenti esterni, e ogni server MCP è codice di terzi che entra nel tuo flusso di lavoro. Il discrimine comune: delega ciò che puoi verificare dopo, tieni a mano ciò che non puoi annullare.

Settima parte della serie su OpenAI Codex, con la documentazione aperta il 13 novembre 2026. Servono i permessi della parte 3 e le regole di AGENTS.md della parte 4. Non ho provato i quattro meccanismi su Codex: gli script girano senza agente e controllano la forma dei file di configurazione. Non sono affiliato a OpenAI.

Codex Cloud: il lavoro che non occupa il tuo portatile

Ogni compito ha un proprio workspace e può continuare mentre il tuo computer dorme; rivedi i risultati dal web, dal telefono o dall'app desktop. Si avvia scegliendo «Work in» e poi «Cloud» sul web o nell'app desktop; da terminale esiste codex cloud, che apre un selettore, mentre codex cloud exec invia direttamente un compito e codex cloud list elenca le chat recenti (con --json per gli script).

Gli ambienti

Se compare l'ambiente predefinito puoi partire senza scegliere un repository, per esempio per far scrivere e provare uno script su dati di esempio; se il compito richiede codice esistente, indichi quale repository clonare. Per riusare una configurazione crei un ambiente: scegli i repository (GitHub, e GitLab.com tramite il selettore di un ambiente riutilizzabile), Codex ispeziona il progetto, installa dipendenze e strumenti e prova il flusso, tu rivedi il rapporto e pubblichi; i compiti partono dall'ambiente pubblicato. La configurazione registra uno script di installazione e una «start skill» che avvia i servizi. Lo stato salvato di un compito resta recuperabile fino a sette giorni dall'ultimo turno e, avverte la pagina, non sostituisce il controllo di versione: ciò che ti serve va committato.

La rete, i segreti, i limiti noti

L'accesso a internet si sceglie fra aperto del tutto o ristretto ai domini che consenti (c'è un preset per i gestori di pacchetti come npm, PyPI, crates.io o Maven). Per i servizi che richiedono credenziali ci sono due strumenti diversi. Una variabile d'ambiente arriva direttamente ai programmi dell'ambiente. Un segreto di rete è una credenziale per un servizio HTTPS preciso: imposti chiave, valore e domini consentiti, i programmi ricevono un segnaposto e il proxy sostituisce il valore vero solo verso quei domini, sulla porta 443, senza mettere la credenziale in un processo o in un file locale. Attenzione al dettaglio: salvare un segreto di rete aggiunge i suoi domini all'accesso a internet ristretto. Ogni dominio consentito è un possibile canale di uscita e ogni segreto salvato è una credenziale che vive fuori dalla tua macchina: dai all'ambiente credenziali di minimo privilegio, di sola lettura se il compito è un'indagine.

Sui limiti, la pagina elenca le risorse predefinite di ogni macchina virtuale: 2 vCPU, 8 GiB di memoria e 8 GiB di disco per Plus, 4 vCPU, 16 GiB e 32 GiB per Pro, Business ed Enterprise. Dichiara non ancora supportati l'uso del computer e GitHub Enterprise Server autogestito. Una rete privata si raggiunge con una VPN, e oggi Tailscale è l'unico fornitore supportato. Le skill salvate nel repository sono disponibili nei compiti cloud, quelle personali del tuo computer non vengono sincronizzate. Quanta quota consumi la pagina Pricing lo dice solo in parte: i compiti cloud possono usarne più dei messaggi locali.

Quando conviene il cloud, e quando no

  • Conviene: compiti lunghi e indipendenti (una migrazione meccanica, un insieme di test da scrivere, un'indagine su un bug), più compiti in parallelo, lavoro da avviare dal telefono, risultati che arrivano come modifiche da rivedere o come pull request.
  • Non conviene: compiti che dipendono dal tuo ambiente locale (un database sul portatile, hardware, dati che non possono uscire), lavoro esplorativo in cui vuoi correggere la rotta ogni minuto.
  • Non disponibile: con la sola chiave API. La tabella Pricing indica che le funzioni cloud non rientrano nell'accesso a chiave.

Il trade-off è quello di ogni delega: guadagni tempo di attesa e perdi la possibilità di fermare l'agente a metà con una parola. Lo compensi con compiti ben delimitati e un criterio di «finito» scritto nel prompt (parte 2). Il criterio che tiene insieme le tre voci è la reversibilità: il cloud va bene per ciò che torna a te come modifica da rivedere.

Subagenti: parallelismo di lettura, non di scrittura

Un subagente è un agente delegato che Codex avvia per un compito specifico; Codex li esegue in parallelo e ne riunisce i risultati in una risposta. Non li «lanci» da un file: li chiedi nel prompt, o li fanno chiedere AGENTS.md e le skill, e Codex gestisce avvio, attesa e chiusura dei thread. Un buon prompt dice come dividere il lavoro, se attendere tutti e che cosa restituire.

Un esempio con questa struttura: «Avvia tre agenti: il primo elenca dove si usa la funzione calcolaSconto, il secondo cerca i test che la coprano, il terzo la documentazione che la cita. Attendi tutti e riassumi in una tabella». Tre indagini indipendenti, nessuna scrittura, un riassunto. Il contrario, tre agenti che modifichino lo stesso modulo, è la ricetta per un conflitto: la documentazione consiglia di partire dal lavoro di lettura (esplorazione, test, smistamento, riassunto) e di essere più cauti con la scrittura in parallelo. Il motivo è il contesto: note di esplorazione, log di test e stack trace nella chat principale la rendono meno affidabile, e i subagenti restituiscono riassunti al posto dell'output grezzo.

Agenti personalizzati

Quelli incorporati sono default, worker ed explorer. Ogni agente personalizzato è un file TOML: personali in ~/.codex/agents/, di progetto in .codex/agents/. Il file deve definire name, description e developer_instructions; può impostare model e model_reasoning_effort e disattivare capacità (per esempio features.shell_tool). Un agente con lo stesso nome di uno incorporato, come explorer, ha la precedenza. I valori globali stanno sotto [agents]: enabled (vale true se non lo scrivi), max_concurrent_threads_per_session (un tetto ai thread aperti, escluso il principale; se manca decide Codex), default_subagent_model e default_subagent_reasoning_effort.

La riga che conta per la sicurezza è un'altra, e conviene leggerla con attenzione: i subagenti ereditano sandbox e approvazioni del turno principale, anche quelle cambiate con /permissions o --yolo, e un file di agente non può sovrascrivere sandbox_mode, approval_policy, model_provider né mcp_servers. Le istruzioni di un agente possono chiedergli di non modificare file, ma la pagina precisa che non creano una sandbox di sola lettura separata. Quindi un «esploratore di sola lettura» è tale per istruzione, non per permesso: se vuoi la garanzia, la dai alla sessione che lo lancia (parte 3). Nei flussi non interattivi, un'azione che richiede una nuova approvazione fallisce e l'errore risale al flusso padre.

Lo script seguente controlla con tomllib la forma di un agente e di una tabella [mcp_servers]. Campi obbligatori, chiavi non sovrascrivibili ed elenco delle chiavi MCP sono una copia delle pagine Subagents e Configuration Reference del 13 novembre, da aggiornare se cambiano. Il primo agente è ispirato all'esempio «PR review» della documentazione; il secondo è volutamente sbagliato (manca la descrizione, prova a imporre sandbox_mode); la configurazione contiene un errore di battitura (enabled_tool) e una voce presente in due elenchi.

# Controllo di forma di un agente personalizzato e di una tabella [mcp_servers]
# contro ciò che le pagine Subagents e Configuration Reference dichiarano (13 novembre 2026).
import tomllib

OBBLIGATORI = {"name", "description", "developer_instructions"}
NON_SOVRASCRIVIBILI = {"sandbox_mode", "approval_policy", "model_provider", "mcp_servers"}
CHIAVI_MCP = {
    "command", "args", "env", "env_vars", "cwd", "url", "auth", "bearer_token_env_var",
    "http_headers", "env_http_headers", "http_headers_helper", "environment_id",
    "startup_timeout_sec", "tool_timeout_sec", "enabled", "required", "startup_readiness",
    "enabled_tools", "disabled_tools", "default_tools_approval_mode", "tools",
}

def agente(nome, testo):
    cfg = tomllib.loads(testo)
    for chiave in sorted(OBBLIGATORI - cfg.keys()):
        print(f"{nome}: manca {chiave}")
    for chiave in sorted(NON_SOVRASCRIVIBILI & cfg.keys()):
        print(f"{nome}: {chiave} nel file dell'agente non ha effetto (vale quello del genitore)")
    if OBBLIGATORI <= cfg.keys() and not (NON_SOVRASCRIVIBILI & cfg.keys()):
        print(f"{nome}: ok")

def server_mcp(nome, testo):
    for sid, tabella in tomllib.loads(testo)["mcp_servers"].items():
        sconosciute = sorted(tabella.keys() - CHIAVI_MCP)
        if "command" not in tabella and "url" not in tabella:
            print(f"{nome}/{sid}: serve command (stdio) oppure url (HTTP)")
        if sconosciute:
            print(f"{nome}/{sid}: chiavi non documentate: {', '.join(sconosciute)}")
        doppie = set(tabella.get("enabled_tools", [])) & set(tabella.get("disabled_tools", []))
        if doppie:
            print(f"{nome}/{sid}: {', '.join(sorted(doppie))} in enabled_tools e disabled_tools: vince disabled_tools")
        if not sconosciute and ("command" in tabella or "url" in tabella):
            print(f"{nome}/{sid}: ok")

agente("esploratore", '''
name = "pr_explorer"
description = "Esplora il codice in sola lettura e raccoglie prove."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Non modificare file. Cita file e simboli.
"""
''')
agente("furbo", '''
name = "veloce"
sandbox_mode = "danger-full-access"
developer_instructions = "Fai tutto."
''')
server_mcp("config", '''
[mcp_servers.docs]
url = "https://mcp.example.invalid/mcp"
required = true
enabled_tool = ["search"]

[mcp_servers.browser]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
default_tools_approval_mode = "prompt"
''')

# Output:
# esploratore: ok
# furbo: manca description
# furbo: sandbox_mode nel file dell'agente non ha effetto (vale quello del genitore)
# config/docs: chiavi non documentate: enabled_tool
# config/browser: screenshot in enabled_tools e disabled_tools: vince disabled_tools
# config/browser: ok

Le prime righe dell'uscita mostrano il caso sano e quello furbo: un file di agente che scrive sandbox_mode = "danger-full-access" non ottiene nulla, e lo script lo dice invece di lasciarti credere il contrario. Le ultime mostrano l'errore più insidioso di un file TOML, la chiave scritta male: Codex non la riconosce come quella voluta, e tu credi di aver limitato gli strumenti. Lo script segnala anche screenshot, presente in entrambi gli elenchi, perché disabled_tools vince ed è raramente voluto. È un controllo di forma: non prova che Codex accetti il file.

Il costo: ogni subagente fa il proprio lavoro di modello e di strumenti, quindi una esecuzione con subagenti usa più token di una a singolo agente. Per i modelli la guida suggerisce gpt-6-luna per scansioni rapide e circoscritte e gpt-6.1-sol per il lavoro impegnativo; se scegli un modello esplicito, parte da high per Luna e da low per Astra (confronto di costo nella parte 5).

Skill e plugin: istruzioni che si richiamano

Una skill, secondo la documentazione, impacchetta istruzioni e risorse per un compito o un flusso specifico. Concretamente è una cartella con un file SKILL.md, che deve contenere name e description, più cartelle facoltative per script, riferimenti e risorse. Codex può sceglierne una da solo quando la richiesta corrisponde alla descrizione, oppure la richiami tu con $ (o con /skills); in ChatGPT si usa @. Per crearne una: $skill-creator, oppure a mano. Le skill seguono lo standard aperto agent skills. Un plugin è un pacchetto installabile che può includere skill, server MCP e hook del ciclo di vita del runtime di Codex, e ChatGPT e Codex condividono la stessa directory di plugin.

Per i repository, Codex cerca la cartella .agents/skills in ogni directory dalla cartella in cui lanci Codex fino alla radice; ci sono poi le skill dell'utente in $HOME/.agents/skills, quelle amministrative in /etc/codex/skills e quelle di sistema incluse nel prodotto. Se due skill hanno lo stesso nome Codex non le fonde: compaiono entrambe. La documentazione descrive anche la «divulgazione progressiva»: Codex parte dal nome e dalla descrizione di ogni skill, e carica il SKILL.md completo solo quando decide di usarla. L'elenco iniziale ha un budget, al massimo il 2% della finestra di contesto del modello (8.000 caratteri se la finestra è sconosciuta), e se le skill sono molte Codex accorcia prima le descrizioni.

Lo script seguente costruisce un piccolo repository di prova in una cartella temporanea, con due skill alla radice e nel sottoprogetto, e applica quelle regole: cerca dalla cartella di lavoro verso l'alto, legge il frontmatter e confronta la lunghezza della voce iniziale con quella del file completo. Rispecchia le regole della pagina, non è il codice di Codex, e mostra ciò che il testo da solo non rende: il peso sta nel corpo, la scelta nella descrizione.

# Mostra come si trovano le skill di un repository e perché la descrizione conta.
# Rispecchia le regole della pagina "Build skills" (13 novembre 2026): non è il codice di Codex.
import os
import tempfile

BUDGET_CARATTERI = 8000   # elenco iniziale quando la finestra di contesto è sconosciuta

def frontmatter(testo):
    righe = testo.split("\n")
    assert righe[0] == "---", "manca il frontmatter"
    fine = righe.index("---", 1)
    campi = dict(r.split(": ", 1) for r in righe[1:fine] if ": " in r)
    return campi, "\n".join(righe[fine + 1:])

def scrivi_skill(radice, cartella, nome, descrizione, corpo):
    d = os.path.join(radice, cartella, ".agents", "skills", nome)
    os.makedirs(d)
    with open(os.path.join(d, "SKILL.md"), "w", encoding="utf-8") as f:
        f.write(f"---\nname: {nome}\ndescription: {descrizione}\n---\n{corpo}\n")

def trova(radice, cwd):
    """Cerca .agents/skills da cwd fino alla radice del repository."""
    trovate, corrente = [], cwd
    while True:
        base = os.path.join(corrente, ".agents", "skills")
        if os.path.isdir(base):
            for nome in sorted(os.listdir(base)):
                trovate.append(os.path.join(base, nome, "SKILL.md"))
        if corrente == radice:
            return trovate
        corrente = os.path.dirname(corrente)

with tempfile.TemporaryDirectory() as radice:
    scrivi_skill(radice, ".", "prepara-release", "Prepara una release: changelog, versione, tag. Non usarla per hotfix.",
                 "Passi:\n" + "\n".join(f"{i}. passo {i} della release" for i in range(1, 41)))
    scrivi_skill(radice, "servizi/pagamenti", "audit-pagamenti", "Controlla un modulo di pagamento contro la checklist interna.",
                 "Apri la checklist e confronta ogni voce con il modulo.")
    scrivi_skill(radice, "servizi/pagamenti", "prepara-release", "Release del solo servizio pagamenti.",
                 "Stessa procedura, ma con il tag del servizio.")
    cwd = os.path.join(radice, "servizi", "pagamenti")
    totale_iniziale = 0
    for percorso in trova(radice, cwd):
        with open(percorso, encoding="utf-8") as f:
            testo = f.read()
        campi, corpo = frontmatter(testo)
        voce = f"{campi['name']}: {campi['description']} ({os.path.relpath(percorso, radice)})"
        totale_iniziale += len(voce)
        print(f"{os.path.relpath(percorso, radice):52s} elenco {len(voce):3d} caratteri, completo {len(testo):4d}")
    print(f"elenco iniziale totale: {totale_iniziale} caratteri su un budget di {BUDGET_CARATTERI}")
    nomi = [frontmatter(open(p, encoding='utf-8').read())[0]['name'] for p in trova(radice, cwd)]
    print("nomi ripetuti (non vengono fusi):", sorted({n for n in nomi if nomi.count(n) > 1}))

# Output:
# servizi/pagamenti/.agents/skills/audit-pagamenti/SKILL.md elenco 138 caratteri, completo  160
# servizi/pagamenti/.agents/skills/prepara-release/SKILL.md elenco 113 caratteri, completo  126
# .agents/skills/prepara-release/SKILL.md              elenco 128 caratteri, completo 1182
# elenco iniziale totale: 379 caratteri su un budget di 8000
# nomi ripetuti (non vengono fusi): ['prepara-release']

Nell'uscita la skill della radice pesa 128 caratteri nell'elenco iniziale e 1.182 nel file completo: il costo fisso di ogni skill installata è la sua descrizione, quello variabile il corpo, pagato solo quando serve. Per questo la guida consiglia descrizioni brevi, con scopo e confini in testa: la scelta implicita dipende da quelle parole. Le due prepara-release non si fondono e compaiono entrambe, quindi non riusare lo stesso nome fra radice e sottocartella.

Per la regola che vale sempre ti serve AGENTS.md (parte 4); la skill è per il flusso a richiesta. Quando vale la fatica? Quando un compito si ripete almeno tre volte con lo stesso schema e le stesse trappole, come «prepara la release»: è un criterio mio, non della fonte. Una skill vecchia che descrive una procedura cambiata è peggio di nessuna skill.

MCP: gli strumenti degli altri, nel tuo flusso

Un server MCP descrive gli strumenti disponibili e gestisce le richieste: cercare un ticket, leggere una documentazione. La CLI ha codex mcp per aggiungere, elencare e autenticare i server; i comandi sono qui sotto, non eseguiti. La configurazione sta in config.toml (~/.codex/config.toml, oppure .codex/config.toml di progetto, ma solo per progetti di cui ti fidi) in tabelle [mcp_servers.<nome>].

# schema da adattare, non eseguito: richiede Codex installato
codex mcp add context7 -- npx -y @upstash/context7-mcp   # server locale (stdio)
codex mcp list                                          # server configurati
codex cloud list --json                                 # chat cloud recenti, per script

Le chiavi che contano per il rischio sono poche. Per un server locale (stdio) serve command, per uno remoto url. required = true fa fallire l'avvio se il server non è pronto (e, come visto nella parte 6, fa uscire con errore codex exec). enabled_tools e disabled_tools sono un elenco di consentiti e uno di vietati, con il secondo applicato dopo il primo. default_tools_approval_mode accetta auto, prompt, writes e approve, e writes chiede conferma per gli strumenti non marcati come di sola lettura. I tempi predefiniti sono 10 secondi per l'avvio (startup_timeout_sec) e 60 per ogni chiamata (tool_timeout_sec). Una chiave scritta male non produce errore nel tuo editor: il lint della sezione precedente serve anche a questo.

I rischi sono tre, e sono miei ragionamenti, non pagine di documentazione: un server MCP locale gira sulla tua macchina con i tuoi permessi, quindi installane solo da fonti che controlleresti come una dipendenza; il suo output è contesto non fidato, perché un ticket o una pagina letti tramite uno strumento possono contenere istruzioni ostili, e la guida di sicurezza della GitHub Action elenca fra le fonti di prompt injection i corpi delle pull request e i messaggi dei commit; un token con troppi privilegi dato a un server MCP diventa il privilegio dell'agente. Ogni server aggiunge inoltre contesto a ogni messaggio, e la pagina Pricing consiglia di spegnere quelli che non servono. Per il contenuto che arriva da un altro sistema l'SDK Python offre ExternalMessage, che Codex tratta come output di strumento a priorità più bassa delle istruzioni di utente e sviluppatore: una mitigazione, non una garanzia.

Una sequenza di adozione ragionevole

  1. Per le prime due settimane, solo CLI locale e AGENTS.md (parti 2 e 4).
  2. Poi i subagenti per le indagini di lettura: guadagno alto, rischio basso.
  3. Poi una skill per il tuo compito più ripetuto.
  4. Solo allora un server MCP, uno alla volta, con token a minimo privilegio.
  5. Il cloud per ultimo, quando hai un compito delimitato e un ambiente con il minimo di credenziali.

L'ordine qui conta, ed è per esposizione crescente: ogni passo aggiunge qualcosa che esce dal perimetro del passo precedente, prima più lavoro (subagenti), poi più istruzioni (skill), poi codice e dati di terzi (MCP), infine la tua base di codice su una macchina remota (cloud). È una sequenza che propongo io, non la fonte.

Domande frequenti

Codex Cloud funziona con la sola chiave API?

No. La tabella dei prezzi indica che con la chiave API si usano CLI, SDK ed estensione IDE ma non le funzioni cloud, come la revisione su GitHub o Slack. Il cloud richiede un accesso con account ChatGPT su un piano che lo includa.

I subagenti possono avere permessi più ampi dell'agente principale?

No. Ereditano sandbox e approvazioni del turno principale e un file di agente non può sovrascrivere sandbox_mode, approval_policy, model_provider o mcp_servers. Le istruzioni «non modificare file» non creano una sandbox di sola lettura separata.

Che cosa non è dimostrato qui

Non ho provato nessuno dei quattro meccanismi su Codex. I due script controllano la forma di file di prova e rispecchiano le regole della documentazione, non il comportamento reale del prodotto. Non so quanto cloud e subagenti consumino della quota rispetto a una sessione locale equivalente: per i subagenti la fonte dice solo che usano più token, per il cloud che possono usarne più dei messaggi locali. Non ho verificato come si comporti un server MCP concreto, né la sintassi dei plugin e del loro manifesto.

Fonti

  • Codex Cloud - avvio dei compiti, ambiente predefinito, consultata il 2026-11-13
  • Cloud environments - ambienti, rete, segreti di rete, VPN, risorse della macchina, limiti noti, skill nei compiti cloud, consultata il 2026-11-13
  • Subagents - agenti incorporati, file TOML, chiavi di [agents], eredità di sandbox e approvazioni, costo, consultata il 2026-11-13
  • Build skills - struttura di una skill, percorsi di ricerca, divulgazione progressiva, budget dell'elenco iniziale, consultata il 2026-11-13
  • Skills and plugins - differenza fra skill e plugin, menzione $, directory condivisa, consultata il 2026-11-13
  • Model Context Protocol - tabelle [mcp_servers], chiavi, valori predefiniti, codex mcp, consultata il 2026-11-13
  • Configuration Reference - elenco delle chiavi di mcp_servers e di agents, consultata il 2026-11-13
  • Developer commands - codex cloud e codex mcp, consultata il 2026-11-13
  • Pricing - funzioni cloud escluse con la sola chiave API, consumo del cloud, effetto dei server MCP sulla quota, consultata il 2026-11-13
  • Codex SDK - il tipo ExternalMessage dell'SDK Python, consultata il 2026-11-13
  • openai/codex-action, docs/security.md - le fonti di prompt injection in un flusso di pull request, consultata il 2026-11-13

Le pagine sono state scaricate per intero e lette nei passi citati. I due script sono stati eseguiti con Python 3.14 (python3 -I), due volte ciascuno, con uscite identiche, senza Codex e senza rete.

← Parte 6: codex exec e SDK Parte 8: il confronto onesto →

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti