Ir al contenido principal
Español— Elegir un idioma
Menú

Configura tu entorno y AGENTS.md

Lección 3 de 20 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Prepara tu proyecto para Codex
  2. Paso 1: Tu acceso a Codex
  3. Paso 2: Instala la extensión del editor
  4. Paso 3: Instala la CLI
  5. El archivo AGENTS.md: la guía de tu proyecto
  6. Mejores prácticas para AGENTS.md
  7. Puntos clave

Actualizado el 3 de noviembre de 2026 según la documentación de Codex (Codex CLI, Autenticación, Extensión de IDE de Codex, Instrucciones personalizadas con AGENTS.md): el paquete @openai/codex-cli y el comando codex auth login no existen (usa npm install -g @openai/codex y codex login); el identificador de la extensión es openai.chatgpt; la dirección codex.openai.com y los planes “Team, Enterprise o API” se han sustituido por los métodos de acceso actuales; y el orden de lectura de AGENTS.md está clarificado (raíz del proyecto → directorio actual). Fuentes: Codex CLI · Autenticación · AGENTS.md · Precios.

Prepara tu proyecto para Codex

Antes de tu primera tarea, deben estar listas dos cosas: tu acceso a Codex (tu cuenta y la conexión a GitHub) y tu propio proyecto, definido mediante el archivo AGENTS.md que guiará al agente. La primera parte lleva unos 15 minutos y es una configuración única. La segunda determina la calidad de todo lo que obtengas de Codex, marcando la diferencia entre equipos satisfechos con la herramienta y aquellos que la encuentran decepcionante.

Paso 1: Tu acceso a Codex

Puedes usar Codex con una cuenta de ChatGPT o una clave de API. Los planes Free y Go proporcionan acceso, dependiendo del despliegue actual, a GPT-6 Luna en la aplicación de escritorio. A partir del plan Plus, Codex está disponible en la web, en la CLI, en la extensión del editor y en iOS, con integraciones en la nube como la revisión automática de código. Una clave de API funciona para la automatización en entornos compartidos como CI, usando la CLI, el SDK o la extensión, aunque algunas funciones pueden no estar disponibles. Los detalles y los límites de uso se encuentran en la página de precios de Codex.

Para trabajar en la nube con tus repositorios, conecta GitHub cuando crees tu primer entorno de Codex Cloud (Lección 2). Al conceder permisos, mantén el mínimo necesario: limita el acceso únicamente a los repositorios que realmente necesites.

Paso 2: Instala la extensión del editor

En VS Code y sus derivados (Cursor, Windsurf), instala la extensión Codex desde el marketplace; su identificador es openai.chatgpt:

code --install-extension openai.chatgpt

A continuación, abre Codex mediante su icono o a través de la paleta de comandos con Codex: Open Codex Sidebar, e inicia sesión. Xcode y los IDE de JetBrains tienen sus propias integraciones: en JetBrains, abre AI Chat y selecciona Codex.

Paso 3: Instala la CLI

# Instalación (macOS y Linux), o npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Verificar instalación
codex --version

# Iniciar sesión (navegador) o comprobar el estado de la conexión
codex login
codex login status

codex login abre el flujo de inicio de sesión en tu navegador. Para usar una clave de API, pásala mediante la entrada estándar (printenv OPENAI_API_KEY | codex login --with-api-key). Codex almacena en caché las credenciales ya sea en un archivo de texto plano, ~/.codex/auth.json, o en el llavero del sistema, dependiendo de la configuración cli_auth_credentials_store (file, keyring, auto o ephemeral). Si se usa el archivo, trátalo como una contraseña: contiene tokens de acceso, así que nunca lo incluyas en el control de versiones. La CLI y la extensión comparten esta caché.

El archivo AGENTS.md: la guía de tu proyecto

AGENTS.md es fundamental para usar Codex con eficacia. Es un sencillo archivo Markdown que se coloca en la raíz de tu repositorio y que reúne instrucciones, convenciones y comandos específicos de tu proyecto. Cuando Codex clona el repositorio, lee este archivo en primer lugar: piénsalo como una incorporación automática para el agente, exactamente lo que le explicarías oralmente a un nuevo miembro del equipo.

El impacto es inmediato. Sin AGENTS.md, si pides una prueba unitaria en un proyecto que usa Vitest, es muy probable que Codex te devuelva Jest, porque es la opción más común en el ecosistema. Una única línea de convención basta para acertar con Vitest a la primera, ahorrándote tener que hacer la misma corrección cien veces. Esta es la estructura de un archivo básico para un proyecto SaaS de gestión de facturas.

# AGENTS.md

## Contexto del proyecto
Aplicación SaaS de gestión de facturas.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.

## Convenciones de código
- Usar componentes funcionales de React (sin clases)
- Nombrar archivos en kebab-case
- Tipos de TypeScript en archivos .types.ts separados
- Pruebas con Vitest, archivos .test.ts junto al código

## Comandos útiles
- `npm run dev` — servidor de desarrollo
- `npm run test` — ejecutar pruebas
- `npm run lint` — comprobar linting
- `npm run build` — compilación de producción

## Estructura del proyecto
    src/
      app/          → Páginas de Next.js (App Router)
      components/   → Componentes reutilizables de React
      lib/          → Lógica de negocio y utilidades
      prisma/       → Esquema de BD y migraciones

## Reglas estrictas
- NUNCA modificar el esquema de Prisma sin una migración
- NUNCA hacer commit de archivos .env
- Usar siempre Server Actions para las mutaciones

Cómo encuentra Codex los archivos AGENTS.md

Un único archivo en la raíz pronto se vuelve demasiado genérico. Codex te permite apilar instrucciones en un orden preciso que debes conocer:

  1. Nivel global: En tu carpeta de Codex (~/.codex, a menos que CODEX_HOME lo anule), Codex lee AGENTS.override.md si existe; de lo contrario, lee AGENTS.md.
  2. Nivel de proyecto: Partiendo de la raíz del proyecto (normalmente la raíz de Git), Codex desciende hasta el directorio actual y lee, en cada carpeta que atraviesa, AGENTS.override.md o, en su defecto, AGENTS.md.
  3. Fusión: Los archivos se concatenan desde la raíz hasta el directorio actual; los más cercanos al directorio actual van al final y, por tanto, anulan las instrucciones más generales.
my-project/
  AGENTS.md              → Instrucciones del proyecto
  src/
    api/
      AGENTS.md          → "Las rutas de API usan Zod para validación"

Consecuencia práctica: src/api/AGENTS.md solo se lee si Codex está trabajando desde src/api o uno de sus subdirectorios, no cuando se lanza desde la raíz. Los archivos vacíos se ignoran y la concatenación se detiene en 32 KiB por defecto (project_doc_max_bytes). Si tu repositorio ya usa otro nombre, como TEAM_GUIDE.md, añádelo a project_doc_fallback_filenames en ~/.codex/config.toml.

Para verificar qué ha cargado realmente Codex, solo tienes que preguntárselo: codex --ask-for-approval never "Resume las instrucciones actuales.". Codex reconstruye la cadena de instrucciones en cada lanzamiento: si tienes dudas, reinícialo en el directorio correcto.

Mejores prácticas para AGENTS.md

El principio rector es la explicitud. “Usar Vitest, no Jest” es mejor que “Usar nuestro framework de pruebas”, lo cual asume un conocimiento que el agente no tiene. Incluye siempre los comandos: sin ellos, Codex no sabrá cómo ejecutar tus pruebas, el linter o la compilación, y entregará código que no ha podido verificar. Documenta la estructura como un árbol de directorios; esto evita que explore a ciegas y cree archivos en el lugar equivocado.

Por último, enumera las prohibiciones. Las reglas escritas como “NUNCA” son las más rentables en el archivo, porque bloquean errores costosos y difíciles de corregir: hacer commit de un archivo .env, modificar un esquema sin una migración. La disciplina más difícil es mantener el archivo actualizado. Un AGENTS.md que describe el proyecto del año pasado dirige activamente a Codex hacia convenciones abandonadas; esto es mucho peor que no tener ningún archivo, ya que el error se vuelve entonces sistemático.

Puntos clave

  • La configuración inicial requiere una cuenta de OpenAI y una conexión a GitHub
  • La extensión del IDE y la CLI se instalan en minutos
  • AGENTS.md es el archivo más importante para un uso eficaz de Codex
  • Contiene convenciones, comandos y reglas específicas de tu proyecto
  • Los archivos AGENTS.md en subdirectorios permiten instrucciones contextuales