Guida pratica a Codex Cloud: delegare un task GitHub a un Agent cloud e revisionare il risultato

Un GitHub issue dice: “Il test webhook fallisce in CI, ma ora non posso eseguire l’ambiente completo in locale.” Vuoi che Codex Cloud corregga il problema nel repository remoto e che alla fine ti consegni solo diff, log dei test e PR da revisionare.

Il punto non è che “cloud” significhi più automatico. Il punto è che un Cloud task gira in un ambiente di repository pulito e riproducibile, separato dal tuo portatile. Non legge file locali non commitati, sessione browser o .env locale; questo limite è sia un vincolo sia una protezione utile.

Il flusso è questo: decidere se il task deve andare in Cloud, configurare l’environment, scrivere il prompt, controllare il risultato e poi scegliere se aprire un PR, riportare il diff in locale o usare @codex review come seconda verifica.

Prima decidi: questa richiesta va in Cloud o resta locale?

I confini tra Local, Worktree, Cloud e SSH host

I vari punti di ingresso di Codex risolvono problemi diversi. Non sono semplicemente versioni più o meno potenti della stessa cosa.

Cloud non è un “Worktree più potente”. Worktree gira ancora sulla tua macchina; separa solo la directory Git. Cloud è un configured cloud environment che fa checkout del repository GitHub ed esegue il task in un container remoto.

Un buon task Cloud di solito ha quattro caratteristiche: obiettivo chiaro, stato del repository riproducibile, ambiente scriptabile e un Done when verificabile con un comando o un diff. Correggere un CI failure, completare documentazione, gestire un follow-up di PR review o aggiungere test a un modulo specifico rientra bene in questo schema.

Task da non consegnare a Cloud

Alcuni task possono beneficiare di un assistente IA, ma non dovrebbero uscire dal tuo ambiente locale.

• Dipendono da file locali non commitati: Cloud vede solo lo stato checkout dal repository remoto.
• Dipendono da una sessione browser o da un dev server locale: il container Cloud non accede automaticamente a Chrome, localhost o app desktop.
• Richiedono secrets di produzione nell’agent phase: i secrets non dovrebbero essere esposti all’agent loop.
• Sono grandi refactoring vaghi: senza comando di validazione, Cloud sposta solo l’incertezza più lontano.
• Richiedono giudizio di prodotto o compromessi del team: Codex può aiutare ad analizzare, ma non dovrebbe riscrivere direttamente tutta la direzione.

La mia abitudine è partire con un Cloud task piccolo. Se non puoi scrivere “esegui questo comando per sapere che è finito”, il task non è ancora pronto per Cloud.

Prima del Cloud task, fai riprodurre il repository all’environment

Il ciclo di vita di un Cloud task

Un Cloud task gira più o meno in questo ordine:

1. Crea un container remoto.
2. Fa checkout del branch o commit SHA scelto.
3. Esegue il setup script; se viene ripristinato un cached container, può eseguire il maintenance script.
4. Applica la policy di rete.
5. Lascia che l’Agent legga file, modifichi codice, esegua controlli e tenti la validazione in una terminal command loop.
6. Restituisce answer, summary e diff; poi puoi fare follow-up o creare un PR.

Molti errori in Cloud non dipendono dal fatto che l’Agent non sappia scrivere codice. È l’environment a non riprodurre il repository: dipendenze che non si installano, database di test assente, lockfile e runtime non allineati, oppure setup script che presume un file presente solo sul tuo portatile.

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

setup script, maintenance script e cache

Il setup script deve portare il container da “checkout appena fatto” a “pronto per eseguire il comando di validazione”. Un esempio minimo può essere breve:

pnpm install
pnpm run typecheck
pnpm test -- --runInBand

Non è un template universale. È un promemoria: il Cloud environment deve sapere come installare dipendenze, preparare l’ambiente di test ed eseguire almeno un controllo capace di far emergere il problema.

Nel setup spesso rientrano:

• Installare dipendenze, linter, formatter, typechecker e test tools.
• Inizializzare un database di test o generare sostituti sicuri della configurazione locale.
• Preparare autenticazione una tantum per installare package privati.
• Mettere valori non sensibili persistenti in environment settings, invece di contare su un export temporaneo nello script.

La cache riduce il tempo necessario a reinstallare dipendenze, ma aggiunge anche un livello da controllare nel debugging. Cambiare setup script, maintenance script, env vars o secrets invalida la cache e avvia una nuova esecuzione. Se le dipendenze si comportano improvvisamente in modo diverso, anche un cache reset è un passo sensato.

Secrets, variabili d’ambiente e rete: tre punti facili da fraintendere

Il ciclo di vita di secrets e environment variables

La differenza principale tra secrets e environment variables non è il nome. È quando sono visibili.

I secrets sono adatti alla fase di setup, per esempio per installare dipendenze private o recuperare package interni. Dovrebbero essere rimossi prima dell’agent phase. In altre parole: non progettare un Cloud task che richiede all’Agent di leggere un token di produzione mentre modifica codice.

Le environment variables restano disponibili per tutto il task. Sono più adatte a valori non sensibili come NODE_ENV=test, una API base URL pubblica o un feature flag.

Attiva agent internet access solo quando serve

Il setup script può usare Internet per installare dipendenze, ma l’agent phase non ha rete per impostazione predefinita. Questo default conta, perché il rischio cambia quando l’Agent legge pagine o API esterne.

Se devi attivare agent internet access, fallo in modo conservativo:

1. Consenti domain specifici, non tutta Internet.
2. Limita gli HTTP methods quando possibile, per esempio a GET, HEAD e OPTIONS.
3. Non lasciare che l’Agent legga, concateni o carichi file sensibili.
4. Scrivi esattamente quali fatti richiedono verifica via rete, così l’Agent non esplora liberamente.

I rischi comuni includono prompt injection, esfiltrazione di codice o secrets, download di dipendenze malevole e problemi di licenza. Aprire unrestricted networking per risparmiare un passaggio quasi mai conviene.

Scrivi il prompt Cloud come un issue

Un template di prompt davvero eseguibile

Un prompt Cloud non dovrebbe essere un desiderio. Dovrebbe sembrare un piccolo GitHub issue: obiettivo, contesto, scope, ambiente, validazione e condizioni di stop.

Goal: Fix the failing webhook.test.ts test in GitHub Actions.
Context: The failure log is below; the relevant code is probably in src/webhooks/ and tests/webhooks/.
Scope: Only fix Stripe webhook signature verification. Do not change the payment public API or refactor the test framework.
Environment: The Cloud environment has pnpm dependencies installed. Please run pnpm test tests/webhooks/webhook.test.ts first.
Done when: The target test passes; list changed files, commands you ran, checks you did not run, and risks I need to confirm manually.
Stop if: You need to add a new secret, change the database schema, modify shared/http-client.ts, or cannot reproduce the failure.

Il formato non è la parte più importante. La parte importante è dare a Codex confini che può rispettare. Più il Cloud task assomiglia a un issue, più è probabile ricevere un diff revisionabile.

Stop if è più utile di “fai attenzione”

“Fai attenzione” è troppo astratto. L’Agent non sa sempre dove inizi il superamento del limite. Stop if trasforma il rischio in condizioni concrete.

Alibaba Cloud - Scelta top per sviluppatori, 15% di sconto esclusivo su Lighthouse

Ottieni -15% →Pubbl.

Puoi scrivere:

• Stop if you need to add a new secret.
• Stop if you need to change the database schema.
• Stop if you must touch the shared auth middleware.
• Stop if the target test cannot be reproduced.
• Stop if the task requires broad renaming or file migration.

In questo modo, quando il Cloud task arriva a un punto rischioso, è più probabile che si fermi e spieghi la situazione invece di allargare il diff.

Quando il Cloud task finisce, guarda summary, diff e command log

Quando fare follow-up e quando aprire un PR

Quando Cloud termina, non fermarti a “done”. Prima leggi quattro cose:

1. Il summary riformula correttamente obiettivo e modifiche?
2. Il diff resta dentro lo scope?
3. Il command log include test, lint o typecheck richiesto?
4. I controlli saltati e i rischi da confermare manualmente sono elencati?

Se il diff tocca file fuori scope, chiedi prima:

The diff touches shared/http-client.ts, which was outside scope. Explain why it was necessary. If not necessary, revert that part and keep the webhook fix minimal.

Se il test target non è stato eseguito, chiedi prima quello:

You did not run the target test. Run pnpm test tests/webhooks/webhook.test.ts and summarize the result before opening a PR.

Vai verso il PR solo quando lo scope delle modifiche è chiaro, il comando di validazione è credibile e i rischi residui sono nominati.

Cosa controllare quando riporti il risultato in locale

Entrambe le strade possono funzionare:

• Modifica piccola: Create PR e lascia che GitHub review, CI e processo del team la gestiscano.
• Modifica più rischiosa: check out locally e verifica con strumenti locali, Codex app review pane o IDE.

Quando riporti il risultato in locale, controlla almeno questo:

• git status è clean, oppure sei su un branch / worktree isolato?
• Il diff contiene solo l’obiettivo del Cloud task?
• Test target, lint e typecheck passano anche in locale?
• Sono cambiati .env*, secrets, CI config, lockfile o generated files?
• Questa lezione dovrebbe diventare una regola in AGENTS.md?

Un Cloud diff non è un pulsante di merge. È un tentativo remoto restituito a te per la review.

@codex review su GitHub: seconda porta, non permesso di merge

Trigger manuale e automatic reviews

In un PR GitHub con Codex Cloud e Code review configurati, un commento può avviare la review:

@codex review

Puoi anche restringere il focus:

@codex review for security regressions

Codex review legge il PR diff, segue le indicazioni del AGENTS.md più vicino ai file modificati e si concentra per impostazione predefinita sui problemi ad alta priorità. I team possono anche attivare automatic reviews, così la review parte quando un PR viene opened for review.

Ma automatic review non significa automatic merge. Può far emergere prima problemi di tipo P0/P1, ma non sostituisce business owner, CI o giudizio umano finale.

Railway - Piattaforma di deploy moderna, senza operazioni complesse, online in pochi minuti

Inizia ora →Pubbl.

Se la review trova un problema, puoi chiedere a Codex di correggerlo dal PR context, per esempio con @codex fix the P1 issue. Questo avvia un flusso Cloud task, e il diff risultante va comunque revisionato.

Se @codex non risponde, fai debug in ordine

Non pubblicare più volte lo stesso commento nel PR. Prima controlla:

1. Il repository ha Codex Cloud configurato?
2. Code review è abilitato per quel repository in Codex settings?
3. Il commento contiene esattamente @codex review?
4. automatic review è attivo e l’evento corrisponde?
5. GitHub app / repository permission consente di leggere PR diff, commenti e push branch?
6. workspace/admin policy, GitHub Enterprise o private repo access aggiungono restrizioni?
7. Sono stati raggiunti usage limits, soprattutto perché code review limits possono differire dall’uso chat ordinario?

Se Cloud tasks, commenti di review e commenti @codex non-review si comportano in modo diverso, registra task, commento, repository e ora prima di consultare supporto ufficiale o workspace admin.

Remote devbox / SSH host non è Cloud

Quando usare una remote connection

Ci sono task che non si adattano bene né a Local né a Cloud: il progetto vive già su una devbox, una macchina GPU, una rete interna o un enterprise remote development host.

La distinzione è questa:

• Codex Cloud: OpenAI managed / configured cloud environment, fa checkout di un repository GitHub ed è adatto a task di repository e workflow PR lontani dal tuo computer.
• Remote connection / SSH host: la Codex app si collega al tuo remote host e usa files, credentials, permissions, plugins, browser setup e local tools di quella macchina.

Se il task richiede un servizio interno, GPU, database remoto o tool già configurati su una devbox, una remote connection è più vicina all’ambiente reale. Cambia anche il confine di sicurezza: permissions, credentials e tools disponibili su quell’host sono il confine che dai a Codex.

L’impostazione conservativa usa trusted SSH keys e least-privilege accounts, evita di esporre app-server transport alla public internet e preferisce VPN o mesh networking per attraversare reti.

Una SOP conservativa per Codex Cloud

Per una prima configurazione di Codex Cloud, segui questa sequenza:

1. Scegli un task piccolo con stato del repository riproducibile, non un grande refactoring.
2. Configura il Cloud environment del repository.
3. Scrivi un setup script per rendere ripetibili installazione delle dipendenze e controllo target.
4. Metti solo valori sensibili di setup phase in secrets; metti configurazione non sensibile in env vars.
5. Lascia agent internet access disattivato per impostazione predefinita; se devi abilitarlo, allowlist solo domain e methods necessari.
6. Scrivi il task prompt come un issue: Goal, Context, Scope, Environment, Done when, Stop if.
7. Durante l’esecuzione guarda plan, commands e failures.
8. Alla fine leggi summary, diff, test results e skipped checks.
9. Crea un PR per una modifica piccola; per modifiche più rischiose, prima check out locally.
10. Usa @codex review nel PR come seconda verifica.
11. Lascia che persone, CI e processo del team decidano se fare merge.
12. Trasforma lezioni ricorrenti di review in regole dentro AGENTS.md.

Ciò che rende Cloud affidabile non è più automazione. È avere un confine chiaro a ogni passaggio: l’environment riproduce il repo, il prompt è eseguibile, il diff è revisionabile e la traccia di review è verificabile. Così affidi un requisito concreto a un Agent cloud, invece di mandare l’incertezza più lontano.