Adozione di Codex nei team: guida decisionale per permessi, convenzioni e percorso Bedrock

Quando un team inizia a usare Codex insieme, la prima domanda di sicurezza e operations quasi mai è “quale piano dobbiamo comprare?”. Di solito è “chi ha full access, cosa può leggere .env e dove vediamo uso e log di audit?”. Queste domande decidono il primo passo dell’adozione. La risposta non è scegliere prima una API key. La risposta è definire prima il confine dei permessi. Questo articolo propone un framework decisionale per l’adozione enterprise: configurare requirements.toml e permission profiles per limitare i permessi per membro, standardizzare le regole condivise di AGENTS.md, scegliere un percorso di deploy come ChatGPT workspace, API Key o Amazon Bedrock, e infine collegare analytics e compliance. C’è anche un fatto da chiarire subito: AWS ha annunciato la disponibilità di GPT-5.4 in GovCloud il 2026-06-03, ma il provider Codex per Bedrock non supporta al momento gli endpoint GovCloud. Sono due fatti diversi, non uno solo.

1. Framework enterprise dei permessi: non lasciare full access su ogni macchina locale

Quando un’azienda vuole standardizzare Codex, può usare cloud-managed requirements per limitare il comportamento locale. requirements.toml è il file di policy di Codex. Gli amministratori possono applicare policy diverse per gruppi di utenti invece di lasciare che ogni membro configuri da solo il proprio ambiente.

1.1 Campi chiave in requirements.toml

Questi sono i campi più usati quando si avvia questo rollout:

Campo	Scopo	Valore consigliato
approval_policy	Controlla se serve approvazione umana	"suggest" o "auto-edit"; non usare "never" come default del team
approvals_reviewer	Indica chi approva	Il owner del team o il referente sicurezza
automatic_review_policy	Regole di revisione automatica	Definiscile in base al rischio del progetto
permission profiles	Modello permessi più nuovo (0.138.0+)	Consigliato per i nuovi deploy
sandbox_mode	Modello permessi precedente	Solo per migrazioni legacy
web_search_mode	Se la ricerca web è consentita	Opzionale, ma va limitata nei progetti sensibili
managed_hooks	Configurazione unificata dei hook	lint-check, test-runner e simili
MCP servers allowlist	Quali server MCP si possono usare	Solo filesystem, github e altri approvati

Codex 0.138.0 e successivi raccomandano permission profiles con allowed_permission_profiles e default_permissions. I deploy legacy possono ancora usare allowed_sandbox_modes.

1.2 Combinazioni proibite

La combinazione seguente non deve essere usata come default del team:

danger-full-access + approval_policy = "never"

È il massimo privilegio senza approvazione. Va bloccata nei requisiti gestiti nel cloud così non compare nelle configurazioni locali individuali.

1.3 Esempio di configurazione

# requirements.toml
[managed]
approval_policy = "suggest"
allowed_permission_profiles = ["suggest", "auto-edit"]
default_permissions = "suggest"

[mcp]
allowed_servers = ["filesystem", "github"]

[hooks]
managed_hooks = ["lint-check", "test-runner"]

Questo esempio limita i membri a "suggest" o "auto-edit", lascia "suggest" come default, consente solo filesystem e github per MCP e mantiene coerente il set di hook. Se vuoi dare "auto-edit" a un gruppo core e lasciare "suggest" a ruoli più limitati, questo è il posto giusto.

2. Minimo privilegio e sandbox: regole concrete, deny glob e protezione dei file sensibili

Chi si occupa di sicurezza non ha bisogno di uno slogan sul “minimo privilegio”. Ha bisogno di regole concrete: quali file si possono leggere, quali scrivere e quali sono del tutto proibiti.

2.1 I tre valori di filesystem

I permessi filesystem di Codex supportano tre valori:

• read: sola lettura, niente modifiche
• write: lettura/scrittura, modifiche consentite
• deny: accesso completamente bloccato

La regola di precedenza è semplice: vince la regola più specifica e deny ha la priorità più alta. Per esempio, se configuri sia "**/*.env" = "deny" sia ":workspace_roots" = "write", i file .env restano bloccati anche se la root del workspace è scrivibile.

2.2 Limiti di scope del workspace

Usa :workspace_roots per limitare l’area di lavoro. Esempio:

[permissions.filesystem]
":workspace_roots" = "write"

Questo permette a Codex di operare solo dentro la root del workspace corrente e i suoi figli. Non può uscire da quel perimetro.

2.3 Protezione dei file sensibili

Puoi usare deny glob per tenere fuori file di ambiente e directory segrete:

[permissions.filesystem]
":workspace_roots" = "write"
"**/*.env" = "deny"
"**/secrets/**" = "deny"
"**/*.log" = "read"

Significa:

• la root del workspace e i figli sono scrivibili
• tutti i file .env sono bloccati ovunque nell’albero
• le directory secrets/ e i loro figli sono bloccati
• i file .log restano in sola lettura

2.4 Permessi di rete

I permessi di rete possono essere abilitati e controllati con liste allow/deny per dominio.

[permissions.network]
enabled = true
allow = ["github.com", "api.openai.com"]
deny = ["localhost", "127.0.0.1"]

Questo consente github.com e api.openai.com, e blocca localhost e loopback. Esiste anche una protezione aggiuntiva per reti locali/private, quindi il team può definire policy di dominio proprie.

2.5 permission profiles contro sandbox mode

Confronto	Permission profiles	Sandbox mode
Fase di rilascio	Modello più nuovo	Modello legacy
Granularità	Più fine	Più grossolana
Campi di configurazione	allowed_permission_profiles + default_permissions	allowed_sandbox_modes
Raccomandazione	Preferito per i nuovi deploy	Principalmente per migrazioni legacy

I nuovi deploy dovrebbero preferire permission profiles. Sandbox mode può essere ritirato gradualmente.

3. Convenzioni condivise del team: un solo AGENTS.md, non un file per persona

I team hanno bisogno di un prompt condiviso, regole di contesto condivise e istruzioni di review condivise. Non serve che ognuno tenga una propria versione separata e frammenti la manutenzione. AGENTS.md è il file di istruzioni di Codex e supporta regole a livelli con priorità.

3.1 Ordine della catena di istruzioni

Quando Codex parte, costruisce questa catena:

global rules (~/.config/codex/AGENTS.md)
  -> project rules (project AGENTS.md)
  -> nearest-to-current-directory rules

Il file più vicino vince quando c’è sovrapposizione.

3.2 Architettura a livelli

Non mettere tutte le regole in un file gigantesco. Meglio dividere così:

• ~/.config/codex/AGENTS.md: regole globali, stile, aspettative di test, divieti generali
• AGENTS.md del progetto: architettura, dipendenze, stile di deploy
• AGENTS.md del modulo: esigenze specifiche del modulo

Ogni livello dovrebbe restare intorno ai 10-15 KiB per essere gestibile e non subire truncamento.

3.3 Gestire il limite da 32 KiB

Codex imposta project_doc_max_bytes a 32 KiB. Se AGENTS.md cresce troppo, può essere troncato.

Ci sono due modi per risolvere:

1. aumentare project_doc_max_bytes
2. dividere il documento in directory annidate

Di solito la seconda opzione è migliore perché rende più chiaro chi mantiene cosa.

3.4 A cosa serve AGENTS.override.md

AGENTS.override.md serve a sovrascrivere l’AGENTS.md superiore e ha la priorità più alta. Usalo quando:

• una sottodirectory specifica ha bisogno di una regola temporanea diversa
• un modulo sperimentale ha bisogno di limiti più morbidi
• un modulo deve divergere dalla policy generale del progetto

Registra il motivo dell’override così il team non si confonde.

3.5 Consiglio di manutenzione

Quando mantieni AGENTS.md, chiarisci:

• Ownership: chi mantiene quale livello
• Maintenance budget: quanto tempo di review riceve ogni sprint
• Review cycle: se le regole globali si rivedono ogni trimestre e quelle di progetto ogni mese

Così AGENTS.md diventa una referenza condivisa viva, non un file privato riscritto da tutti.

4. Scelta del deploy: come decidere tra ChatGPT workspace, API Key e Bedrock

Le organizzazioni devono scegliere quale percorso di account adottare. Le tre opzioni hanno punti di forza, limiti e contesti diversi.

4.1 Tabella comparativa

Dimensione	ChatGPT Business/Enterprise	API Key	Amazon Bedrock
Autenticazione	Login ChatGPT	OPENAI_API_KEY	Bedrock API key o AWS IAM
Proprietario della fatturazione	Workspace OpenAI	Account API OpenAI	Account AWS
Governance team	Analytics Dashboard, managed requirements	Nessuna governance team nativa	AWS IAM e CloudTrail
Completezza funzioni	La più completa	La più flessibile	Set parziale di funzioni (vedi 4.2)
Compliance / regione	Regioni OpenAI	Regioni OpenAI	Regioni AWS e data residency
Supporto GovCloud	No	No	Il modello può essere disponibile, ma il supporto del provider Codex è separato (vedi 4.3)
Fit migliore	Team piccoli o medi che vogliono gestione workspace	Sviluppatori che vogliono integrazione flessibile	Team centrati su AWS che vogliono billing, IAM e controlli di compliance

4.2 Capacità mancanti in Bedrock

Al 2026-06-08, le seguenti capacità non sono disponibili in questo percorso:

• Fast Mode
• hosted web/file search
• computer use
• shell tool
• image generation tool
• remote MCP servers
• on-demand inference only non è supportato; bisogna usare Provisioned Throughput

Queste capacità dipendono da servizi cloud ospitati da OpenAI, strumenti hosted o discovery cloud-managed, quindi sono fuori da questo percorso. Se il tuo team ne dipende, usa ChatGPT workspace o API Key.

4.3 Chiarimento su GovCloud

Qui ci sono due fatti diversi:

1. GPT-5.4 in AWS GovCloud (US-West) è disponibile

   • il modello è disponibile in GovCloud
   • GPT-5.4 può essere chiamato tramite API Bedrock

2. Il provider Codex per Bedrock non supporta endpoint GovCloud

   • il provider amazon-bedrock di Codex non supporta oggi gli endpoint Bedrock Mantle nelle regioni AWS GovCloud
   • non puoi configurare Codex su Bedrock in GovCloud oggi

Non scrivere “Codex su Bedrock supporta GovCloud” come se fosse lo stesso fatto.

4.4 Scenari d’uso

Scegli il percorso in base all’organizzazione:

ChatGPT Business/Enterprise

• team piccoli e medi
• vogliono amministrazione centralizzata del workspace
• vogliono il set più completo di funzioni
• non hanno bisogno di billing AWS o IAM

API Key

• sviluppatori che vogliono integrazione flessibile
• nessuna necessità di governance team
• pagano direttamente su un account API OpenAI
• non serve amministrazione compliance

Amazon Bedrock

• team centrati su AWS con account, IAM e billing già esistenti
• vogliono aggregare i costi sotto gli impegni AWS
• hanno bisogno di data residency o regioni AWS specifiche
• accettano un set parziale di funzioni (vedi 4.2)

5. Configurazione e limiti Bedrock: AWS-native auth, funzioni mancanti e rischio GovCloud

I team che scelgono Bedrock devono capire configurazione, autenticazione, funzioni mancanti e confine GovCloud.

5.1 Configurare il provider amazon-bedrock

Imposta il provider nel file di configurazione Codex:

{
  "provider": "amazon-bedrock",
  "aws_region": "us-east-1",
  "model_id": "openai.gpt-5.5"
}

L’ID del modello e la regione devono seguire la documentazione ufficiale.

5.2 AWS-native auth

Il percorso Bedrock usa autenticazione nativa AWS, non OPENAI_API_KEY:

• Bedrock API key: chiave temporanea, massimo 12 ore o durata sessione, eredita i permessi del principal IAM
• Credenziali AWS IAM: configurate tramite IAM role o IAM user

Per produzione si consigliano chiavi temporanee o IAM role. Le chiavi di lunga durata servono solo per esplorazione.

5.3 Regioni commerciali AWS supportate

La documentazione ufficiale supporta attualmente queste regioni commerciali AWS:

• us-east-1
• us-west-2
• eu-west-1
• ap-northeast-1

Per la lista aggiornata, consulta i documenti AWS Bedrock OpenAI models.

5.4 Governance delle chiavi Bedrock

Regole di governance per le chiavi Bedrock:

• Short-term key: fino a 12 ore o alla durata della sessione, eredita i permessi del principal IAM, raccomandata per produzione
• Long-term key: solo per esplorazione, non raccomandata per produzione
• CloudTrail logging: le chiamate API sono registrate in AWS CloudTrail; la chiave non viene salvata in chiaro
• IAM actions control: le azioni IAM possono controllare chi crea e usa le chiavi API

5.5 Elenco ripetuto delle funzioni mancanti

Al 2026-06-08, in Bedrock non sono disponibili:

• Fast Mode
• hosted web/file search
• computer use
• shell tool
• image generation tool
• remote MCP servers
• on-demand inference only non è supportato; bisogna usare Provisioned Throughput

Se il team dipende da queste funzioni, passa a ChatGPT workspace o API Key.

5.6 Rischio GovCloud (ripetizione)

Di nuovo, separa questi due fatti:

• GPT-5.4 di AWS è disponibile in GovCloud (US-West): il modello è disponibile in GovCloud
• Il provider Codex per Bedrock non supporta endpoint GovCloud: oggi non puoi configurare Codex su Bedrock nelle regioni AWS GovCloud

Se il tuo team ha bisogno di GovCloud, non assumere che Codex possa già puntarci.

6. Governance e audit: dove vedere uso e log di compliance

I manager devono tracciare adozione, uso e impatto del code review, e per farlo servono analytics e output di audit.

6.1 Confronto delle tre strade di governance

Percorso	Capacità	Ritardo	Ideale per
Analytics Dashboard	adozione, uso, feedback dei code review	I dati possono ritardare fino a 12 ore	Tracking del rollout
Analytics API	bucket giornalieri/settimanali, uso per workspace/utente, dettaglio per client, metriche Code Review	Da quasi real time a poche ore	Governance dei costi e analisi approfondita
Compliance API	esporta attività Codex e metadati di audit	Dipende dall’integrazione SIEM/eDiscovery	Audit di compliance

6.2 Scenari d’uso

6.2.1 Tracking del rollout

Usa Analytics Dashboard per vedere adozione e uso del team:

• tasso di attivazione dei membri
• qualità del feedback di code review
• distribuzione d’uso per client

I dati del dashboard possono arrivare con fino a 12 ore di ritardo, quindi sono più adatti a report settimanali o mensili che al monitoraggio in tempo reale.

6.2.2 Governance dei costi

Usa Analytics API per analisi più profonde:

• separa l’uso per workspace/utente/modello
• confronta bucket giornalieri e settimanali
• dettaglia per client (Codex App/CLI/IDE/Cloud)
• riassumi le metriche di Code Review

È il percorso giusto per governance interna dei costi e lavoro di ottimizzazione.

6.2.3 Audit di compliance

Usa Compliance API per esportare i log:

• attività Codex
• metadati di audit
• integrazione con SIEM/eDiscovery
• supporto alla revisione di compliance

È la via giusta per organizzazioni regolamentate come finanza, settore pubblico e sanità.

6.3 Raccomandazione sul percorso di governance

• Analytics Dashboard: meglio per responsabili tecnici e project manager che seguono il rollout
• Analytics API: meglio per platform engineer che fanno governance dei costi e analisi profonda
• Compliance API: meglio per team sicurezza e compliance che integrano SIEM ed eDiscovery

Le tre strade possono essere combinate in base alle esigenze dell’organizzazione.

7. Percorso di rollout del team: dal pilot individuale alla governance organizzativa

Molti team non sanno da dove partire, come dividere l’adozione o come scegliere la prima ondata di task pilota.

7.1 Framework di rollout in tre fasi

Fase 1: controllo individuale (definire il confine dei permessi)

Obiettivo: rendere controllabile il confine dei permessi di ogni membro in modo che i file sensibili non si spargano sulle macchine locali.

Azioni chiave:

• vietare danger-full-access + approval_policy = "never" come default del team
• proteggere .env e secrets/ con deny glob
• usare :workspace_roots per limitare l’area di lavoro

Criterio di successo: nessun membro può accedere ai file sensibili senza approvazione.

Fase 2: pilot di piccolo team (convenzioni condivise + task a basso rischio)

Obiettivo: uniformare AGENTS.md e skills nel piccolo team, poi partire con task a basso rischio per verificare che il flusso funzioni.

Azioni chiave:

• scrivere un AGENTS.md globale (stile e aspettative di test)
• scrivere un AGENTS.md di progetto (architettura, dipendenze, deploy)
• scegliere task a basso rischio come generazione documentazione, correzioni lint e aggiunte di test
• evitare di automatizzare direttamente deploy di produzione o logica di pagamento

Criterio di successo: la maggior parte del team usa l’AGENTS.md condiviso e non ci sono incidenti di sicurezza gravi.

Fase 3: governance organizzativa (managed requirements + Analytics/Compliance API)

Obiettivo: elevare permessi e convenzioni a governance organizzativa e collegare osservabilità e audit.

Azioni chiave:

• configurare requisiti gestiti per gruppi di utenti
• collegare Analytics Dashboard/API per seguire adozione e uso
• collegare Compliance API a SIEM
• rivedere periodicamente permission profiles e allowlist MCP

Criterio di successo: il cruscotto di governance è online e i log di audit sono tracciabili.

7.2 Task pilota consigliati

Dai priorità ai task a basso rischio

Buoni task per la prima ondata di pilot:

• generazione documentazione: README, documenti API, pulizia note
• correzioni lint: eslint, prettier, automazione formattazione
• aggiunte test: test unitari e scheletri di integrazione
• suggerimenti di refactoring: miglioramenti strutturali con review umana

Evita l’automazione diretta

Task non adatti alla prima ondata di pilot:

• deploy di produzione
• logica di pagamento
• cambi di permessi
• cancellazione dati

Sono task ad alto rischio e dovrebbero aspettare che governance e audit maturino.

7.3 Relazione con il resto della serie

Questo articolo è la pagina decisionale per l’adozione team; i prossimi possono entrare più nel dettaglio:

• stile di scrittura AGENTS.md: come scrivere regole a livelli, evitare truncamento e mantenerle
• blocchi personali e sandbox: problemi di permessi, configurazione sandbox, errori comuni
• integrazione Cloud/GitHub: sviluppo remoto, GitHub review, cloud task
• ottimizzazione costi e quota: tecniche per ridurre token e controllare il budget
• automazione e task lunghi: trigger programmati, heartbeat e job multi-giorno

Riepilogo e prossimi passi

Se sei il responsabile tecnico che porta Codex nel team, l’ordine dovrebbe essere:

1. Leggi prima la configurazione dei permessi (sezioni 1 e 2) per bloccare le combinazioni pericolose
2. Standardizza poi le convenzioni (sezione 3) così AGENTS.md ha una forma condivisa
3. Scegli dopo il percorso di deploy (sezioni 4 e 5) per decidere tra workspace, API Key e Bedrock
4. Collega alla fine la governance (sezione 6) tramite Analytics e Compliance API

Poi puoi passare a moduli più specifici:

• stile di scrittura AGENTS.md: come scrivere regole a livelli, evitare truncamento e mantenerle
• blocchi personali e sandbox: problemi di permessi, configurazione sandbox, errori comuni
• integrazione Cloud/GitHub: sviluppo remoto, GitHub review, cloud task
• ottimizzazione costi e quota: tecniche per ridurre token e controllare il budget
• automazione e task lunghi: trigger programmati, heartbeat e job multi-giorno

Concetti base correlati:

• fondamenti della collaborazione Git nel team: Git flow, strategia dei branch e flusso di code review
• segreti CI e sicurezza dei permessi: GitHub Actions secrets, confini di permesso e pratiche di sicurezza