Guía práctica de Codex Cloud: delegar una tarea de GitHub a un agente en la nube y revisar el resultado

Un GitHub issue dice: “El test de webhook falla en CI, pero ahora mismo no puedo ejecutar el entorno completo en local”. Quieres que Codex Cloud lo corrija en el repositorio remoto y que al final solo te entregue el diff, el registro de pruebas y el PR para revisar.

La clave no es que “la nube” sea más automática. La clave es que una Cloud task corre en un entorno de repositorio limpio y reproducible, separado de tu computadora. No lee tus archivos locales sin commit, tu sesión de navegador ni tu .env local; ese límite es una restricción y, a la vez, una protección útil.

El flujo es este: decidir si la tarea debe ir a Cloud, configurar el environment, escribir el prompt, revisar el resultado y elegir si abrir un PR, traer el diff a local o usar @codex review como segunda comprobación.

Primero decide: ¿esta tarea va a Cloud o se queda en local?

Los límites entre Local, Worktree, Cloud y SSH host

Las distintas entradas de Codex resuelven problemas diferentes. No son simplemente versiones más o menos potentes de lo mismo.

Cloud no es un “Worktree más potente”. Worktree sigue corriendo en tu máquina; solo separa el directorio Git. Cloud es un configured cloud environment que hace checkout del repositorio de GitHub y ejecuta la tarea en un contenedor remoto.

Una buena tarea para Cloud suele tener cuatro rasgos: objetivo claro, estado de repositorio reproducible, entorno scriptable y un Done when que se pueda validar con un comando o un diff. Corregir un CI failure, completar documentación, dar seguimiento a una PR review o añadir tests a un módulo concreto encaja bien.

Tareas que no deberías entregar a Cloud

Algunas tareas pueden beneficiarse de un asistente de IA, pero no deberían salir de tu entorno local.

• Dependen de archivos locales sin commit: Cloud solo ve el estado checkout desde el repositorio remoto.
• Dependen de una sesión de navegador o de un dev server local: el contenedor Cloud no accede automáticamente a Chrome, localhost ni apps de escritorio.
• Requieren secrets de producción en la agent phase: los secrets no deberían exponerse al agent loop.
• Son refactorizaciones grandes y difusas: sin comando de validación, Cloud solo mueve la incertidumbre más lejos.
• Requieren criterio de producto o acuerdos del equipo: Codex puede ayudar a analizar, pero no debería reescribir toda la dirección.

Mi costumbre es que la primera Cloud task sea pequeña. Si no puedes escribir “ejecuta este comando para saber que está terminado”, la tarea aún no está lista para Cloud.

Antes de empezar una Cloud task, haz que el environment reproduzca el repositorio

El ciclo de vida de una Cloud task

Una Cloud task suele correr en este orden:

1. Crear un container remoto.
2. Hacer checkout del branch o commit SHA elegido.
3. Ejecutar el setup script; si se restaura un cached container, se puede ejecutar un maintenance script.
4. Aplicar la política de red.
5. Dejar que el agente lea archivos, modifique código, ejecute comprobaciones e intente validar en una terminal command loop.
6. Devolver answer, summary y diff; después puedes hacer follow-up o crear un PR.

Muchos fallos de Cloud no ocurren porque el agente no sepa escribir código. El environment simplemente no reproduce el repositorio: las dependencias no se instalan, falta una base de datos de prueba, el lockfile no coincide con el runtime o el setup script asume un archivo que solo existe en tu computadora.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

setup script, maintenance script y cache

El setup script debe llevar el contenedor desde “checkout recién hecho” hasta “listo para ejecutar el comando de validación”. Un ejemplo mínimo puede ser corto:

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

No es una plantilla universal. Es un recordatorio: el Cloud environment debe saber cómo instalar dependencias, preparar el entorno de prueba y ejecutar al menos una comprobación que pueda exponer el problema.

El setup suele incluir:

• Instalar dependencias, linter, formatter, typechecker y test tools.
• Inicializar una base de datos de prueba o generar sustitutos seguros de configuración local.
• Preparar autenticación de un solo uso para instalar paquetes privados.
• Poner valores no sensibles que deben persistir en environment settings, en lugar de depender de un export temporal dentro del script.

El cache reduce el tiempo de reinstalar dependencias, pero también añade una capa al diagnóstico. Cambios en setup script, maintenance script, env vars o secrets invalidan el cache y disparan una ejecución nueva. Si las dependencias empiezan a comportarse distinto, resetear el cache también es razonable.

Secrets, variables de entorno y red: tres lugares fáciles de malinterpretar

El ciclo de vida de secrets y environment variables

La diferencia principal entre secrets y environment variables no es el nombre. Es cuándo son visibles.

Los secrets encajan en la fase de setup, por ejemplo para instalar dependencias privadas u obtener paquetes internos. Deben retirarse antes de que empiece la agent phase. Dicho de otro modo: no diseñes una Cloud task que obligue al agente a leer un token de producción mientras modifica código.

Las environment variables duran toda la tarea. Encajan mejor con valores no sensibles como NODE_ENV=test, una API base URL pública o un feature flag.

Activa agent internet access solo cuando la tarea lo necesita

El setup script puede usar Internet para instalar dependencias, pero la agent phase no tiene red por defecto. Ese valor por defecto importa, porque el riesgo cambia cuando el agente lee páginas o APIs externas.

Si debes activar agent internet access, hazlo de forma conservadora:

1. Permite dominios concretos, no todo Internet.
2. Limita HTTP methods cuando sea posible, por ejemplo a GET, HEAD y OPTIONS.
3. No permitas que el agente lea, concatene o suba archivos sensibles.
4. Escribe exactamente qué hechos requieren verificación por red, para que el agente no navegue libremente.

Los riesgos comunes incluyen prompt injection, exfiltración de código o secrets, descarga de dependencias maliciosas y problemas de licencia. Abrir unrestricted networking para ahorrar un paso casi nunca compensa.

Escribe el prompt de Cloud como un issue

Una plantilla de prompt que sí se puede ejecutar

Un prompt de Cloud no debería ser un deseo. Debe parecerse a un GitHub issue pequeño: objetivo, contexto, alcance, entorno, validación y condiciones 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.

Lo importante no es el formato. Lo importante es darle a Codex límites que pueda seguir. Cuanto más se parezca la Cloud task a un issue, más probable es que devuelva un diff revisable.

Stop if sirve más que “ten cuidado”

“Ten cuidado” es demasiado abstracto. El agente no siempre sabe dónde está el límite. Stop if convierte el riesgo en condiciones concretas.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Puedes escribir:

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

Así, cuando la Cloud task llega a un punto de riesgo, es más probable que se detenga y explique la situación en lugar de seguir ampliando el diff.

Cuando la Cloud task termine, revisa el summary, el diff y el registro de comandos

Cuándo hacer follow-up y cuándo abrir un PR

Cuando Cloud termina, no basta con leer “done”. Primero mira cuatro cosas:

1. Si el summary reformula correctamente el objetivo y los cambios.
2. Si el diff se mantiene dentro del scope.
3. Si el registro de comandos incluye el test, lint o typecheck que pediste.
4. Si las comprobaciones omitidas y los riesgos humanos están claramente listados.

Si el diff toca archivos fuera del scope, pregunta primero:

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.

Si no ejecutó el test objetivo, pregunta eso primero:

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

Avanza hacia un PR solo cuando el alcance de cambios esté claro, el comando de validación sea creíble y los riesgos restantes estén nombrados.

Qué revisar al traer el resultado a local

Ambos caminos sirven:

• Cambio pequeño: Create PR y dejar que GitHub review, CI y el proceso del equipo lo manejen.
• Cambio de más riesgo: check out locally y verificar con tus herramientas locales, el Codex app review pane o el IDE.

Al traer el resultado a local, revisa al menos esto:

• Si git status está clean, o si estás en un branch / worktree aislado.
• Si el diff solo contiene el objetivo de la Cloud task.
• Si el test objetivo, lint y typecheck también pasan en local.
• Si cambiaron .env*, secrets, CI config, lockfiles o generated files.
• Si esta lección debería convertirse en una regla en AGENTS.md.

Un Cloud diff no es un botón de merge. Es un intento remoto que vuelve a ti para revisión.

@codex review en GitHub: una segunda puerta, no permiso de merge

Disparo manual y automatic reviews

En un PR de GitHub donde Codex Cloud y Code review están configurados, un comentario puede activar la revisión:

@codex review

También puedes enfocarla:

@codex review for security regressions

Codex review lee el PR diff, sigue la guía del AGENTS.md más cercano a los archivos modificados y se concentra por defecto en problemas de alta prioridad. Los equipos también pueden activar automatic reviews para que la revisión se ejecute cuando un PR se abre for review.

Pero automatic review no significa automatic merge. Puede ayudar a detectar antes problemas tipo P0/P1, pero no reemplaza al business owner, la CI ni el juicio humano final.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Si la review encuentra un problema, puedes pedir a Codex que lo corrija desde el PR context, por ejemplo con @codex fix the P1 issue. Eso inicia un flujo de Cloud task, y el diff resultante también necesita revisión.

Si @codex no responde, depura en orden

No publiques el mismo comentario varias veces en el PR. Primero revisa:

1. Si el repository tiene Codex Cloud configurado.
2. Si Code review está activado para ese repository en Codex settings.
3. Si el comentario contiene exactamente @codex review.
4. Si automatic review está activado y el evento coincide.
5. Si GitHub app / repository permission permite leer el PR diff, comentar y hacer push branch.
6. Si workspace/admin policy, GitHub Enterprise o private repo access añaden restricciones.
7. Si se alcanzaron usage limits, sobre todo porque los code review limits pueden diferir del uso normal de chat.

Si Cloud tasks, comentarios de review y comentarios @codex que no son review se comportan distinto, registra task, comentario, repository y hora antes de consultar soporte oficial o al workspace admin.

Remote devbox / SSH host no es Cloud

Cuándo usar una remote connection

Hay tareas que no encajan bien ni en Local ni en Cloud: el proyecto ya vive en una devbox, una máquina GPU, una red interna o un enterprise remote development host.

La separación es esta:

• Codex Cloud: OpenAI managed / configured cloud environment, hace checkout de un repositorio GitHub y encaja con tareas de repositorio y PR lejos de tu máquina.
• Remote connection / SSH host: la Codex app se conecta a tu remote host y usa los files, credentials, permissions, plugins, browser setup y local tools de esa máquina.

Si la tarea necesita un servicio interno, GPU, base de datos remota o herramientas ya configuradas en una devbox, una remote connection se acerca más al entorno real. Su límite de seguridad también cambia: los permissions, credentials y tools disponibles en ese host son el límite que le das a Codex.

La configuración conservadora usa trusted SSH keys y least-privilege accounts, evita exponer app-server transport a Internet público y prefiere VPN o mesh networking para cruzar redes.

Una SOP conservadora para Codex Cloud

Para una primera configuración de Codex Cloud, sigue esta secuencia:

1. Elige una tarea pequeña con estado de repositorio reproducible, no un refactoring grande.
2. Configura el Cloud environment del repository.
3. Escribe un setup script para que la instalación de dependencias y la comprobación objetivo sean repetibles.
4. Pon solo valores sensibles de setup phase en secrets; pon configuración no sensible en env vars.
5. Mantén agent internet access desactivado por defecto; si debes activarlo, allowlist solo dominios y methods necesarios.
6. Escribe el task prompt como un issue: Goal, Context, Scope, Environment, Done when, Stop if.
7. Mientras corre, mira plan, commands y failures.
8. Al terminar, lee summary, diff, test results y skipped checks.
9. Crea un PR para un cambio pequeño; para cambios de más riesgo, primero check out locally.
10. Usa @codex review en el PR como segunda comprobación.
11. Deja que personas, CI y el proceso del equipo decidan si hacer merge.
12. Convierte aprendizajes repetidos de review en reglas dentro de AGENTS.md.

Lo que hace fiable a Cloud no es más automatización. Es tener un límite claro en cada paso: el environment reproduce el repo, el prompt se puede ejecutar, el diff se puede revisar y la traza de review es verificable. Así delegas un requisito concreto a un agente en la nube, en lugar de mandar la incertidumbre más lejos.