Cómo usar Codex: guía completa para empezar con CLI, extensión IDE, Codex Cloud y app de escritorio

La primera vez que uses Codex, no le pidas que refactorice todo el proyecto. Abre primero el repositorio y dale una tarea pequeña que puedas validar en unos 20 minutos.

Panorama de puntos de entrada

OpenAI Codex no es solo una herramienta de terminal ni un plugin de editor. Es un coding agent que se puede usar desde varios puntos de entrada. En la documentación oficial verás CLI, IDE extension, Codex app y Codex web/cloud. Comparten autenticación y capacidades base, pero sirven para trabajos distintos.

Comparativa de los cuatro puntos de entrada

Punto de entrada	Definición	Mejor para	Usuario típico	Limitación
CLI	Coding agent que corre en la terminal local	Repositorios locales existentes, cambios pequeños, flujo de línea de comandos	Usuarios intensivos de terminal, entornos CI	Requiere un repositorio Git local; los cambios se ven en archivos locales
IDE Extension	Colaboración desde la barra lateral del editor	Trabajo actual en el editor, contexto corto con open files / selected code	Usuarios de VS Code / Cursor / Windsurf / JetBrains	Depende del entorno del editor; las tareas complejas pueden delegarse a Cloud
Codex App	Command center de escritorio	Varios hilos, worktrees, automations, gestión Git	Usuarios locales con varias tareas en paralelo	Disponible en macOS / Windows; revisa la disponibilidad de Linux en la página oficial
Codex Cloud/Web	Agente en la nube conectado a GitHub	Repositorios remotos, PR, tareas asíncronas, trabajo lejos de la computadora	Equipos y flujos con repositorios remotos	Un Enterprise workspace puede requerir admin setup

Autenticación y diferencias de funciones

Codex admite dos formas de autenticación, pero el alcance de funciones no es igual.

Autenticación	Puntos de entrada disponibles	Disponibilidad de funciones Cloud	Uso recomendado
ChatGPT account (Plus/Pro/Business/Edu/Enterprise)	Todos los puntos de entrada (CLI/IDE/App/Cloud)	Incluye GitHub code review, Slack y otras cloud-based features	Usuarios individuales con suscripción y equipos
API key	CLI, SDK, IDE Extension	No incluye GitHub code review, Slack ni otras cloud-based features	CI, automatización y flujos facturados por API

Precios, límites y funciones habilitadas deben revisarse en la página oficial de pricing y en tu account dashboard. Si inicias sesión con una API key y las funciones Cloud no aparecen, no es una avería: es una diferencia de surface.

Punto de entrada CLI

El CLI es un coding agent que corre en tu terminal local. Puede leer el código del directorio seleccionado, modificar archivos, ejecutar comandos y revisar resultados. Por eso encaja bien cuando ya tienes un repositorio local.

Definición y casos de uso del CLI

La capacidad central del CLI es trabajar dentro de un repositorio local: leer código, editar archivos, ejecutar tests, ejecutar lint, revisar errores y generar un diff. No necesitas tener el archivo abierto en el editor. Basta con describir la tarea en la terminal.

El CLI encaja si:

• ya tienes un repositorio Git local;
• la tarea toca varios archivos o necesita verificación por comandos;
• quieres ver los cambios localmente para git diff y commit;
• trabajas en CI o con scripts de automatización.

El CLI encaja menos si:

• aún no tienes un repositorio local y primero debes clonar;
• solo quieres cambiar el archivo abierto, donde IDE extension es más cómodo;
• necesitas un flujo de PR remoto, donde Cloud encaja mejor.

Instalación e inicio de sesión del CLI

La instalación y el inicio de sesión pueden cambiar. Toma esto como flujo general y consulta la página oficial del CLI para los comandos exactos.

1. Elegir el método de instalación en la página oficial del CLI: la página oficial actual ofrece un standalone installer. Algunos artículos antiguos pueden mencionar npm, pero debe prevalecer la página oficial vigente.
2. Primer arranque: después de instalar, ejecuta codex y sigue el flujo de inicio de sesión.
3. Elegir el método de inicio de sesión: puedes usar un ChatGPT account o una API key. Un ChatGPT account cubre todas las surfaces; una API key se limita a CLI, SDK e IDE extension, sin funciones Cloud.

El CLI admite macOS, Windows y Linux. En Windows puedes usar PowerShell native sandbox o WSL2; revisa los detalles en la página oficial del CLI.

Comandos CLI comunes

El CLI ofrece modos interactive y non-interactive. Estos son los seis comandos o grupos de flags que conviene reconocer primero. Los nombres pueden cambiar, así que revisa la CLI reference cuando necesites sintaxis exacta.

Comando	Uso	Ejemplo
codex	Modo interactive para trabajar por conversación en la terminal	codex
codex exec	Modo non-interactive para CI o scripts	codex exec "fix the CI failure"
codex login	Iniciar sesión o cambiar cuenta	codex login
codex update	Actualizar el CLI	codex update
codex doctor	Revisar configuración del entorno y problemas comunes	codex doctor
Flags comunes	Ajustar permisos, modelo, sandbox y approvals	--sandbox read-only, --model, --ask-for-approval

La CLI reference incluye más comandos y flags, como codex apply, codex cloud y codex app. Algunos pueden tener distintos niveles de madurez. Al principio, domina primero el modo interactive; codex exec queda para automatización.

Primera tarea con CLI

La regla para la primera tarea es simple: elige un repositorio existente y dale a Codex una tarea que puedas validar en unos 20 minutos.

Las best practices oficiales recomiendan un prompt con cuatro partes.

Parte del prompt	Qué significa	Ejemplo
Goal	Resultado esperado	”Corregir el comando de instalación obsoleto en el README”
Context	Contexto relevante	”Es un proyecto Node.js. El README menciona npm install, pero ahora el proyecto usa yarn.”
Constraints	Límites del cambio	”Modifica solo el README. No cambies otros archivos. Después ejecuta node README-example.js para confirmar que el comando funciona.”
Done when	Criterio de aceptación	”El comando del README está actualizado y node README-example.js imprime el resultado esperado.”

Buenas primeras tareas:

• corregir un comando o enlace obsoleto en el README;
• agregar un test faltante o arreglar un test que falla;
• corregir un bug pequeño con mensaje de error claro;
• limpiar un comentario TODO;
• agregar una anotación de tipo simple a un módulo.

Evita como primera tarea:

• tocar secrets o datos de producción;
• hacer una refactorización grande o una funcionalidad completa;
• pedir algo sin criterio de validación, como “optimizar rendimiento”.

Checklist de validación del CLI

Cuando el CLI termine, valida el resultado en este orden.

1. Leer el diff: ejecuta git diff en la terminal y confirma que el cambio coincide con la tarea. No te quedes solo con el mensaje “terminado”.
2. Ejecutar tests: si el proyecto tiene tests, ejecuta npm test o el comando correspondiente.
3. Ejecutar lint o typecheck: si existen, confirma que no aparezcan nuevos errores.
4. Revisar la salida del comando: si la tarea incluía ejecutar un comando, confirma que la salida sea la esperada.
5. Mantener los secrets fuera de la primera tarea: si la tarea toca configuración sensible, revisa primero si de verdad el agent debe modificarla.

Haz commit o push solo después de validar. Si el cambio no encaja, revierte con Git, ajusta el prompt y vuelve a intentarlo.

Punto de entrada IDE Extension

IDE extension permite trabajar con Codex desde la barra lateral del editor. Encaja cuando ya estás trabajando en el IDE. Su ventaja es un contexto más corto y preciso: open files, selected code y referencias @file, sin tener que describir todo el proyecto en la terminal.

Definición y casos de uso del IDE

IDE extension no reemplaza el editor. Integra Codex como coding agent dentro del workflow del editor. Toma contexto de los archivos abiertos, del código seleccionado o de los archivos que referencias explícitamente con @file, así que puede ser más preciso para cambios locales.

IDE extension encaja si:

• trabajas en VS Code, Cursor, Windsurf o JetBrains;
• la tarea trata sobre el archivo actual o pocos archivos relacionados;
• quieres ver los cambios en el editor mientras ocurren;
• necesitas referenciar un archivo específico como contexto.

Encaja menos si:

• no tienes entorno de editor, donde el CLI es más simple;
• la tarea debe ejecutarse mucho tiempo en segundo plano, donde Cloud puede tomar el relevo;
• la tarea toca muchos archivos o flujos de comandos complejos, donde CLI o Cloud pueden ser mejores.

IDE compatibles

IDE extension admite los siguientes editores. Revisa la disponibilidad actual en la página oficial del IDE.

Editor	Nota
VS Code	Compatibilidad oficial
Cursor	Fork de VS Code compatible con la VS Code extension
Windsurf	Fork de VS Code compatible con la VS Code extension
JetBrains	Admite Rider, IntelliJ, PyCharm, WebStorm e IDE relacionados, según disponibilidad oficial

Si trabajas en Cursor o Windsurf, Codex extension y las funciones de IA integradas del editor pueden convivir. Codex es otro coding agent que eliges según la tarea.

Instalación e inicio de sesión en IDE

Sigue la página oficial del IDE para los pasos actuales.

1. Instalar desde el marketplace de extensiones: busca Codex extension en VS Code, Cursor, Windsurf o JetBrains.
2. Iniciar sesión: usa un ChatGPT account o una API key. Un ChatGPT account cubre todas las surfaces; una API key no incluye funciones Cloud.

Contexto disponible en el IDE

El valor principal de IDE extension es el contexto del editor.

Tipo de contexto	Qué significa	Ejemplo
Open files	Los archivos abiertos sirven como contexto	Abre example.tsx y Codex puede inspeccionarlo directamente
Selected code	El fragmento seleccionado se vuelve contexto	Selecciona una función y pide a Codex que la explique o refactorice
Referencia @file	Referenciar explícitamente otro archivo por nombre	@example.tsx revisa las definiciones de tipos de este componente
Reasoning effort	Ajustar cuánto razona el agent	low/medium/high; usa más esfuerzo para tareas difíciles

IDE extension también admite modos Chat, Agent y Agent Full Access. La diferencia está en permisos y nivel de automatización. Empieza con el modo Agent por defecto y ajusta cuando entiendas los trade-offs.

Delegar desde IDE a Cloud

IDE extension puede delegar una tarea a Codex Cloud. Úsalo cuando:

• la tarea pueda ejecutarse durante mucho tiempo;
• implique un repositorio remoto;
• necesites alejarte de la máquina mientras el trabajo continúa;
• quieras que una tarea compleja corra en segundo plano y revisar el resultado después.

Las slash commands comunes pueden incluir las siguientes. Los nombres pueden cambiar, así que revisa la página IDE features.

Comando	Uso
/cloud	Delegar la tarea actual a Cloud
/local	Ejecutar la tarea localmente
/review	Revisar la base branch, cambios sin commit o un commit
/status	Consultar el estado de una tarea Cloud

Después de usar /cloud, el IDE muestra el estado de la tarea. Cuando la tarea Cloud termina, vuelve para revisar el diff y el resultado.

Punto de entrada Codex App

Codex app es un command center de escritorio para trabajo multi-hilo y gestión Git. No es otra ventana de chat. Puede recuperar historial y configuración del CLI y del IDE extension, lo que facilita continuar en un proyecto existente.

Definición y casos de uso de la app

La app se centra en varios threads, worktrees, automations y operaciones Git. Es útil cuando necesitas tareas paralelas, un diff pane e integración Git en un mismo espacio local.

La app encaja si:

• necesitas varios task threads al mismo tiempo;
• quieres aislar trabajo paralelo mediante worktrees;
• quieres un diff pane visual y operaciones Git;
• prefieres un workflow de escritorio con terminal integrada.

Encaja menos si:

• solo quieres modificar el archivo abierto, donde IDE extension es más cómodo;
• no tienes repositorio local, en cuyo caso usa Cloud o clona primero;
• solo necesitas una tarea rápida, donde el CLI es más directo.

Compatibilidad de plataformas de la app

Codex app admite macOS y Windows. Revisa la disponibilidad para Linux en la página oficial de la app.

Instalación e inicio de sesión de la app

Sigue la página oficial de la app para los pasos actuales.

1. Descargar e instalar: obtiene el instalador de macOS o Windows desde la página oficial de la app.
2. Iniciar sesión: usa un ChatGPT account o una API key. Algunas funciones pueden no estar disponibles con API key, según la guía oficial.
3. Elegir un proyecto: en el primer inicio, la app pide seleccionar un directorio de proyecto local.

App Thread Mode

La app ofrece tres thread modes: Local, Worktree y Cloud.

Thread Mode	Qué hace	Mejor para
Local	Trabaja directamente en el directorio actual del proyecto	Cambios pequeños, trabajo de un solo hilo, primer mensaje por defecto
Worktree	Crea un worktree aislado para el thread	Tareas paralelas, cambios aislados, evitar conflictos
Cloud	Delega la tarea a Codex Cloud	Repositorios remotos, PR, tareas largas

Deja el workflow Worktree detallado para una guía posterior. Para empezar, el modo Local basta.

Funciones principales de la app

Las funciones centrales de la app incluyen:

Función	Qué hace
Diff pane	Permite inspeccionar cambios de archivos y hacer stage / revert por chunks
Operaciones Git	Soporta commit, push, creación de PR y acciones del flujo Git
Terminal integrada	Cmd+J abre la terminal en macOS; revisa los atajos actuales en la página oficial
Sincronización con IDE	IDE extension y app pueden sincronizarse dentro del mismo proyecto
MCP settings compartidos	CLI, IDE y app pueden compartir MCP settings

La app también incluye un in-app browser, pero no usa páginas que requieren tu perfil de navegador iniciado. Para páginas con login, abre un navegador externo.

Punto de entrada Codex Cloud/Web

Codex web/cloud se conecta a un GitHub account y permite que Codex trabaje en un repositorio remoto y cree PR. Encaja con equipos, repositorios remotos y tareas que deben seguir ejecutándose cuando no estás frente a la computadora.

Definición y casos de uso de Cloud

Cloud trata de repositorios remotos, PR y trabajo asíncrono. Crea un contenedor en la nube, hace checkout del repo, ejecuta setup scripts, realiza la tarea y devuelve un diff y una respuesta.

Cloud encaja si:

• trabajas en un repositorio remoto que no quieres modificar localmente;
• quieres que Codex cree o revise una PR;
• el trabajo debe continuar mientras no estás en la máquina;
• el workflow implica revisión y colaboración de equipo.

Cloud encaja menos si:

• se trata de un cambio local pequeño, donde CLI o IDE son mejores;
• es tu primera tarea, que conviene validar localmente;
• la tarea requiere mucha interacción, porque Cloud es asíncrono.

Tareas adecuadas para Cloud

Cloud funciona bien para estos tipos de tarea:

Tipo de tarea	Descripción
PR review	Revisar una PR en un repositorio remoto
Trabajo complejo o largo	Ejecutar tareas que necesitan más tiempo
Tareas paralelas	Delegar varias tareas al mismo tiempo
Cambios en repositorios remotos	Modificar sin tocar tu checkout local

No envíes a Cloud una refactorización grande o una funcionalidad completa el primer día. Usa primero CLI o IDE en local, aprende a leer el resultado y luego mueve a Cloud las tareas adecuadas.

Un Enterprise workspace puede requerir admin setup. Revisa la página oficial de Cloud y la policy de tu workspace.

Flujo de Cloud

Una Cloud task suele seguir cinco pasos:

1. Crear un contenedor: Cloud crea el entorno de ejecución.
2. Checkout repo: hace checkout del repositorio de GitHub.
3. Ejecutar setup script: si existe, ejecuta el setup script configurado.
4. Ejecutar el agent loop: el agent ejecuta comandos, revisa resultados y continúa hasta terminar la tarea.
5. Devolver el diff y la respuesta: al terminar, se muestra el diff y una respuesta.

El caché del contenedor puede durar hasta 12 horas. Revisa la política actual en la página oficial Cloud environments.

Notas de seguridad de Cloud

Cloud tiene algunos límites de seguridad importantes:

Elemento de seguridad	Qué significa
Los secrets solo están disponibles durante setup	Los secrets están disponibles para setup scripts y se eliminan antes del agent phase. No hagas que el agent phase dependa de scripts que leen secrets.
El agent phase no tiene internet por defecto	El acceso a internet está off por defecto durante el agent phase, aunque puede configurarse como limited o unrestricted access. No asumas que el agent puede contactar servicios externos.
El caché dura hasta 12 horas	El caché del contenedor no es almacenamiento a largo plazo. No asumas que el estado persistirá indefinidamente.

La configuración de seguridad detallada queda para una guía posterior sobre permisos, sandboxes y secrets.

Siguientes pasos

Después de la primera tarea, si Codex repite el mismo error en la segunda o tercera ejecución, es momento de escribir una guía AGENTS.md del proyecto. AGENTS.md da instrucciones específicas del proyecto a los coding agents para que no tengas que repetir el mismo contexto en cada prompt.

Temas recomendados después:

• Reglas de proyecto AGENTS.md: conservar instrucciones del proyecto y reducir contexto repetido.
• Aislamiento con worktree: ejecutar varias tareas en paralelo sin mezclar cambios.
• Workflow Cloud: repositorios remotos, PR y configuración de entorno.
• Permisos, sandboxes y secrets: límites de seguridad y configuración.
• Comparativa de tres herramientas: Codex vs Claude Code vs Cursor en proyectos reales.
• Automatización con codex exec: llamadas desde CI y scripts.

Artículos relacionados de BetterLink:

• Panorama 2026 de AI coding tools
• Guía de productividad con Claude Code CLI
• Práctica de workflow con Cursor
• Codex gateway y harness