Guia prático de Codex Cloud: delegar uma tarefa do GitHub a um agente em nuvem e revisar o resultado

Um GitHub issue diz: “O teste de webhook está falhando no CI, mas agora não consigo rodar o ambiente completo localmente.” Você quer que o Codex Cloud corrija isso no repositório remoto e, no fim, entregue apenas o diff, o log de testes e o PR para revisão.

A questão não é que “nuvem” seja mais automática. A questão é que uma Cloud task roda em um ambiente de repositório limpo e reproduzível, separado do seu notebook. Ela não lê seus arquivos locais sem commit, sua sessão de navegador nem seu .env local; esse limite é restrição e proteção ao mesmo tempo.

O fluxo é este: decidir se a tarefa deve ir para Cloud, configurar o environment, escrever o prompt, revisar o resultado e então escolher entre abrir um PR, trazer o diff para local ou usar @codex review como segunda checagem.

Primeiro decida: essa demanda vai para Cloud ou fica local?

Os limites entre Local, Worktree, Cloud e SSH host

As entradas do Codex resolvem problemas diferentes. Elas não são só versões mais fortes ou mais fracas da mesma coisa.

Cloud não é um “Worktree mais forte”. Worktree ainda roda na sua máquina; ele só separa o diretório Git. Cloud é um configured cloud environment que faz checkout do repositório GitHub e executa a tarefa dentro de um contêiner remoto.

Uma boa tarefa para Cloud costuma ter quatro características: alvo claro, estado de repositório reproduzível, ambiente que pode ser preparado por script e um Done when validável por comando ou diff. Corrigir um CI failure, complementar documentação, tratar follow-up de PR review ou adicionar testes a um módulo específico se encaixa bem.

Tarefas que você não deveria entregar para Cloud

Algumas tarefas podem se beneficiar de um assistente de IA, mas não deveriam sair do ambiente local.

• Dependem de arquivos locais sem commit: Cloud só vê o estado checkout do repositório remoto.
• Dependem de sessão de navegador ou dev server local: o contêiner Cloud não acessa automaticamente Chrome, localhost ou apps de desktop.
• Exigem secrets de produção na agent phase: secrets não devem ficar expostos ao agent loop.
• São refactorings grandes e vagos: sem comando de validação, Cloud só empurra a incerteza para mais longe.
• Exigem julgamento de produto ou acordo do time: Codex pode ajudar a analisar, mas não deveria reescrever toda a direção.

Meu padrão é começar com uma Cloud task pequena. Se você não consegue escrever “rode este comando para saber que terminou”, a tarefa ainda não está pronta para Cloud.

Antes da Cloud task, faça o environment reproduzir o repositório

O ciclo de vida de uma Cloud task

Uma Cloud task geralmente roda nesta ordem:

1. Criar um container remoto.
2. Fazer checkout do branch ou commit SHA escolhido.
3. Executar o setup script; se um cached container for restaurado, executar opcionalmente o maintenance script.
4. Aplicar a política de rede.
5. Deixar o agente ler arquivos, alterar código, rodar verificações e tentar validar em uma terminal command loop.
6. Devolver answer, summary e diff; depois você pode fazer follow-up ou criar um PR.

Muitas falhas em Cloud não acontecem porque o agente não sabe escrever código. O environment simplesmente não reproduz o repositório: dependências não instalam, falta banco de testes, lockfile e runtime não batem, ou o setup script assume um arquivo que só existe no seu notebook.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

setup script, maintenance script e cache

O setup script deve levar o contêiner de “checkout recém-feito” para “pronto para rodar o comando de validação”. Um exemplo mínimo pode ser curto:

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

Isso não é um template universal. É um lembrete: o Cloud environment precisa saber como instalar dependências, preparar o ambiente de teste e rodar pelo menos uma verificação capaz de expor o problema.

O setup costuma incluir:

• Instalar dependências, linter, formatter, typechecker e test tools.
• Inicializar banco de testes ou gerar substitutos seguros para configuração local.
• Preparar autenticação pontual para instalar pacotes privados.
• Colocar valores não sensíveis persistentes em environment settings, em vez de depender de um export temporário dentro do script.

O cache reduz o tempo de reinstalar dependências, mas também adiciona uma camada ao diagnóstico. Mudanças em setup script, maintenance script, env vars ou secrets invalidam o cache e disparam uma execução nova. Se dependências passam a se comportar de outro jeito, resetar o cache também é um passo razoável.

Secrets, variáveis de ambiente e rede: três lugares fáceis de entender errado

O ciclo de vida de secrets e environment variables

A principal diferença entre secrets e environment variables não é o nome. É quando eles ficam visíveis.

Secrets combinam com a fase de setup, por exemplo para instalar dependências privadas ou buscar pacotes internos. Eles devem ser removidos antes da agent phase. Em outras palavras: não desenhe uma Cloud task que exige que o agente leia um token de produção enquanto altera código.

Environment variables duram a tarefa inteira. Elas combinam melhor com valores não sensíveis como NODE_ENV=test, uma API base URL pública ou um feature flag.

Ative agent internet access só quando a tarefa precisar

O setup script pode usar Internet para instalar dependências, mas a agent phase não tem rede por padrão. Esse padrão importa porque o risco muda quando o agente lê páginas ou APIs externas.

Se você precisar ativar agent internet access, faça isso de forma conservadora:

1. Permita domínios específicos, não a Internet inteira.
2. Limite HTTP methods quando possível, por exemplo a GET, HEAD e OPTIONS.
3. Não deixe o agente ler, concatenar ou fazer upload de arquivos sensíveis.
4. Escreva exatamente quais fatos precisam de verificação por rede, para o agente não sair explorando.

Riscos comuns incluem prompt injection, exfiltração de código ou secrets, download de dependências maliciosas e problemas de licença. Abrir unrestricted networking só para economizar um passo quase nunca compensa.

Escreva o prompt de Cloud como um issue

Um template de prompt que dá para executar

Um prompt de Cloud não deveria ser um desejo. Ele deve parecer um GitHub issue pequeno: objetivo, contexto, escopo, ambiente, validação e condições de parada.

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.

O formato não é o ponto principal. O ponto é dar ao Codex limites que ele consiga seguir. Quanto mais a Cloud task parece um issue, maior a chance de receber um diff revisável.

Stop if funciona melhor do que “tenha cuidado”

“Tenha cuidado” é abstrato demais. O agente nem sempre sabe onde fica o limite. Stop if transforma o risco em condições concretas.

🔥 Não perca meses em produtos sem demanda! Valide as propostas do seu SaaS com a Adsterra e pouco orçamento →

Testar agora →Anúncio

Você pode escrever:

• 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.

Assim, quando a Cloud task chega a um ponto de risco, é mais provável que ela pare e explique a situação, em vez de ampliar o diff.

Quando a Cloud task terminar, revise summary, diff e log de comandos

Quando fazer follow-up e quando abrir um PR

Quando Cloud termina, não pare em “done”. Primeiro leia quatro coisas:

1. Se o summary reformula corretamente o objetivo e as mudanças.
2. Se o diff fica dentro do scope.
3. Se o log de comandos inclui o test, lint ou typecheck que você pediu.
4. Se verificações não executadas e riscos humanos estão claramente listados.

Se o diff toca arquivos fora do scope, pergunte primeiro:

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 o teste alvo não rodou, pergunte isso primeiro:

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

Avance para PR só quando o escopo da mudança estiver claro, o comando de validação for confiável e os riscos restantes estiverem nomeados.

O que revisar ao trazer o resultado para local

Os dois caminhos servem:

• Mudança pequena: Create PR e deixar GitHub review, CI e processo do time cuidarem.
• Mudança de maior risco: check out locally e validar com ferramentas locais, Codex app review pane ou IDE.

Ao trazer o resultado para local, revise pelo menos isto:

• Se git status está clean, ou se você está em um branch / worktree isolado.
• Se o diff contém apenas o objetivo da Cloud task.
• Se o test alvo, lint e typecheck também passam localmente.
• Se .env*, secrets, CI config, lockfiles ou generated files mudaram.
• Se essa lição deveria virar regra em AGENTS.md.

Um Cloud diff não é um botão de merge. É uma tentativa remota devolvida para você revisar.

@codex review no GitHub: segunda porta, não permissão de merge

Disparo manual e automatic reviews

Em um PR do GitHub com Codex Cloud e Code review configurados, um comentário pode iniciar a review:

@codex review

Você também pode focar a revisão:

@codex review for security regressions

Codex review lê o PR diff, segue a orientação do AGENTS.md mais próximo dos arquivos alterados e foca por padrão em problemas de alta prioridade. Times também podem ativar automatic reviews para rodar quando um PR é opened for review.

Mas automatic review não significa automatic merge. Ela pode ajudar a revelar problemas P0/P1 mais cedo, mas não substitui business owner, CI nem julgamento humano final.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Se a review encontrar um problema, você pode pedir ao Codex para corrigir a partir do PR context, por exemplo com @codex fix the P1 issue. Isso inicia um fluxo de Cloud task, e o diff resultante ainda precisa de revisão.

Se @codex não responder, depure em ordem

Não publique o mesmo comentário várias vezes no PR. Primeiro verifique:

1. Se o repository tem Codex Cloud configurado.
2. Se Code review está ativado para esse repository em Codex settings.
3. Se o comentário contém exatamente @codex review.
4. Se automatic review está ativado e o evento corresponde.
5. Se GitHub app / repository permission permite ler PR diff, comentários e push branch.
6. Se workspace/admin policy, GitHub Enterprise ou private repo access impõem restrições.
7. Se usage limits foram atingidos, principalmente porque code review limits podem ser diferentes do uso normal de chat.

Se Cloud tasks, comentários de review e comentários @codex que não são review se comportam de formas diferentes, registre task, comentário, repository e horário antes de consultar suporte oficial ou workspace admin.

Remote devbox / SSH host não é Cloud

Quando usar uma remote connection

Há tarefas que não encaixam bem nem em Local nem em Cloud: o projeto já vive em uma devbox, máquina GPU, rede interna ou enterprise remote development host.

A separação é esta:

• Codex Cloud: OpenAI managed / configured cloud environment, faz checkout de um repositório GitHub e serve para tarefas de repositório e fluxos de PR longe da sua máquina.
• Remote connection / SSH host: o Codex app conecta ao seu remote host e usa files, credentials, permissions, plugins, browser setup e local tools daquela máquina.

Se a tarefa precisa de serviço interno, GPU, banco remoto ou ferramentas já configuradas em uma devbox, uma remote connection fica mais próxima do ambiente real. O limite de segurança também muda: permissions, credentials e tools disponíveis nesse host viram o limite que você dá ao Codex.

A configuração conservadora usa trusted SSH keys e least-privilege accounts, evita expor app-server transport à Internet pública e prefere VPN ou mesh networking para atravessar redes.

Uma SOP conservadora para Codex Cloud

Para uma primeira configuração de Codex Cloud, siga esta sequência:

1. Escolha uma tarefa pequena com estado de repositório reproduzível, não um refactoring grande.
2. Configure o Cloud environment do repository.
3. Escreva um setup script para tornar repetíveis a instalação de dependências e a verificação alvo.
4. Coloque apenas valores sensíveis de setup phase em secrets; coloque configuração não sensível em env vars.
5. Mantenha agent internet access desligado por padrão; se precisar ativar, allowlist apenas domínios e methods necessários.
6. Escreva o task prompt como um issue: Goal, Context, Scope, Environment, Done when, Stop if.
7. Durante a execução, observe plan, commands e failures.
8. No fim, leia summary, diff, test results e skipped checks.
9. Crie um PR para mudança pequena; para mudanças mais arriscadas, primeiro check out locally.
10. Use @codex review no PR como segunda checagem.
11. Deixe pessoas, CI e processo do time decidirem se haverá merge.
12. Transforme aprendizados repetidos de review em regras no AGENTS.md.

O que torna Cloud confiável não é mais automação. É ter um limite claro em cada etapa: o environment reproduz o repo, o prompt pode ser executado, o diff pode ser revisado e a trilha de review é verificável. É assim que você entrega um requisito concreto a um agente em nuvem, em vez de mandar a incerteza para mais longe.