Codex CLI: instalación, permisos, AGENTS.md y costes

Codex CLI es el agente de programación de OpenAI que se utiliza desde un terminal: puede examinar un proyecto, modificar sus archivos y ejecutar comprobaciones según los permisos concedidos. Para utilizarlo correctamente, conviene distinguir la instalación del programa, el acceso al modelo, los límites técnicos del entorno aislado y las reglas de aprobación. Esta guía explica esos ajustes, el archivo AGENTS.md y los costes, con fuentes oficiales consultadas el 24 de octubre de 2026.

Qué instala y qué trabajo delega

Una sesión de Codex CLI puede servir para entender una función, preparar una corrección o investigar una regresión. El terminal permite trabajar directamente con el proyecto y sus herramientas habituales. Sin embargo, para hacerlo necesita saber si un comando es adecuado, leer las diferencias entre archivos e interpretar el resultado de una prueba.

El programa instalado y el servicio que proporciona el modelo son componentes distintos. Por tanto, la licencia del cliente no determina ni su consumo ni las condiciones de tratamiento de sus datos. El repositorio oficial publica el cliente con licencia Apache-2.0 y documenta los métodos de instalación.

Para decidir qué delegar, parta de un resultado observable: corregir un comportamiento descrito, explicar una dependencia o añadir una comprobación concreta. Una petición genérica de mejora deja más margen para cambios innecesarios y dificulta la revisión posterior.

Esta guía está dirigida a personas capaces de retomar el trabajo si falla un comando. Para situar este método entre otras formas de trabajar, el artículo sobre el funcionamiento de los agentes de programación explica su ciclo de trabajo. Después puede consultar sus fichas en nuestro directorio de agentes de IA.

Requisitos previos: prepare el proyecto antes de la sesión

Prepare un terminal operativo, acceso al servicio de modelos elegido y una copia de trabajo cuyo estado conozca. Si opta por instalar mediante un gestor de paquetes, este debe estar disponible de antemano. Los comandos que aparecen a continuación son alternativas: elija un método de instalación.

Antes de empezar:

identifique la carpeta exacta que desea examinar;
guarde una copia de los cambios existentes y localice los archivos sin seguimiento;
compruebe cómo se compila el proyecto y cómo se ejecutan sus pruebas;
retire del entorno de trabajo los secretos innecesarios;
defina qué operaciones necesitan su autorización.

Partir de un estado limpio facilita saber quién ha hecho cada cambio. Si varias personas o herramientas modifican los mismos archivos, prepare un espacio de trabajo separado. Así evitará tener que pedir después al agente que distinga sus modificaciones de las realizadas por otra persona.

Prepare también un ejemplo del resultado esperado. Si se trata de un fallo de visualización, describa el comportamiento visible; si afecta al procesamiento de datos, aporte un ejemplo anonimizado. Un criterio de éxito concreto resulta más útil que una descripción extensa de sus intenciones.

Además, una prueba puede escribir archivos, contactar con un servicio o utilizar credenciales presentes en el entorno. Examine los scripts del proyecto antes de encargárselos a un agente, especialmente si el repositorio procede de una fuente desconocida.

1. Instalar Codex CLI con un método oficial

La documentación de inicio ofrece un instalador independiente para macOS y Linux. El siguiente comando, comprobado en la documentación de Codex CLI, descarga y ejecuta el script de instalación:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Para Windows, el repositorio oficial proporciona este comando de PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Si ya utiliza npm o Homebrew, el mismo repositorio documenta estas alternativas:

npm install -g @openai/codex

brew install --cask codex

Elija el método compatible con las políticas de su equipo. Si trabaja en un equipo administrado por su organización, siga el procedimiento de distribución de software previsto. Evite acumular instalaciones: un ejecutable antiguo puede conservar la prioridad en la ruta de búsqueda del terminal.

Para actualizar una instalación independiente en macOS o Linux, la documentación indica que debe ejecutar de nuevo el mismo instalador. Antes de actualizar varios equipos, conserve la configuración utilizada y compruebe el comportamiento en un proyecto sin datos sensibles.

No es necesario fijar aquí una versión para seguir el procedimiento. Sin embargo, al documentar una incidencia, anote la versión instalada: una opción que aparece en la documentación actual puede no estar disponible en un cliente antiguo.

2. Elegir la autenticación y el presupuesto

Puede iniciar el acceso interactivo con:

codex login

La documentación de autenticación distingue entre el acceso con una cuenta de ChatGPT y el acceso con una clave API. El primero depende de los derechos de la cuenta o del espacio de trabajo; el segundo, de los de la organización de la API.

Si la clave ya está disponible en la variable de entorno correspondiente, el comando oficial es:

printenv OPENAI_API_KEY | codex login --with-api-key

Este ejemplo requiere un intérprete de comandos que disponga de printenv. No sustituya la variable por una clave escrita directamente en un comando que vaya a compartir. Utilice preferentemente el sistema de gestión de secretos de su entorno.

Para comprobar el método activo:

codex login status

En un equipo sin navegador, la documentación contempla la autenticación mediante código de dispositivo en fase beta, siempre que esté activada en los ajustes de la cuenta o del espacio de trabajo:

codex login --device-auth

Las credenciales pueden guardarse en un archivo local o en el almacén de credenciales del sistema. Trate cualquier caché de autenticación como un secreto.

Antes de iniciar una tarea costosa, compruebe la cuenta activa y el presupuesto al que se cargará el consumo. Haber iniciado sesión correctamente no demuestra que esté utilizando el presupuesto previsto por su equipo.

3. Separar la aprobación del entorno aislado

El entorno aislado o sandbox establece un límite técnico: qué archivos son accesibles, dónde se puede escribir y qué acceso a la red tienen los comandos. La aprobación determina cuándo una acción debe someterse a validación. Las instrucciones escritas en la conversación constituyen otra capa distinta.

A fecha de 24 de octubre de 2026, la documentación del sandbox describe los siguientes modos anteriores y señala que la política untrusted ya no se puede seleccionar.

Ajuste anterior	Inspección	Escritura	Uso recomendado
`read-only`	Consulta del proyecto	Sin edición dentro del ámbito ordinario	Diagnóstico inicial
`workspace-write`	Lectura de los archivos accesibles	Dentro del espacio autorizado	Corrección acotada
`danger-full-access`	Acceso sin restricciones del sandbox	Sin límites impuestos por el sandbox	Entorno aislado y preparado

Las políticas actuales de aprobación son on-request y never. Esta última elimina las solicitudes de validación; no debe interpretarse como una autorización editorial o de negocio para cualquier acción.

En Linux y WSL2, la documentación recomienda instalar bubblewrap. Para Ubuntu o Debian:

sudo apt install bubblewrap

Para Fedora:

sudo dnf install bubblewrap

Aplique el procedimiento correspondiente a su sistema. Si falla el aislamiento, investigue la causa técnica antes de ampliar los permisos.

En la práctica, empiece por el principio de mínimo privilegio: conceda acceso al proyecto necesario y amplíe el ámbito solo cuando lo requiera una etapa concreta. La rapidez de trabajo no justifica por sí sola el acceso a carpetas personales ni a credenciales de producción.

4. Iniciar una sesión con permisos explícitos

Las siguientes opciones figuran en la referencia oficial de comandos, consultada el 24 de octubre de 2026. Desde la carpeta del proyecto, este comando permite inspeccionar sin solicitar una ampliación de permisos:

codex --sandbox read-only --ask-for-approval never

Para trabajar en una corrección dentro del espacio autorizado, con solicitudes de aprobación cuando sea necesario:

codex --sandbox workspace-write --ask-for-approval on-request

La referencia también ofrece una revisión automática de las solicitudes de aprobación que cumplen los requisitos:

codex --approve-for-me

Esta opción utiliza un sandbox con permiso de escritura en el espacio de trabajo. Entra en conflicto con determinadas opciones manuales de sandbox y aprobación; no las combine.

Elija el modo en función del trabajo solicitado. Un análisis de código no suele necesitar los mismos permisos que una migración de dependencias. Publicar, enviar datos o modificar infraestructura requiere una decisión específica, aparte de autorizar cambios en los archivos.

La aprobación humana exige leer el comando y entender su contexto. Antes de validarlo, identifique la carpeta afectada, los destinos de red y los efectos persistentes. Si la solicitud no permite entender estos elementos, pida que se concrete la acción.

Por último, evite convertir una autorización puntual en un permiso general por comodidad. La guía para proteger un agente de IA desarrolla este método más allá del terminal.

Perfiles de permisos: una configuración distinta

La documentación actual también ofrece perfiles de permisos en fase beta. Entre ellos figuran :read-only, :workspace y :danger-full-access, con una sintaxis diferente a la de los modos anteriores.

Una selección mínima en la configuración puede tener esta forma:

default_permissions = ":read-only"

Estos perfiles no se combinan con los ajustes anteriores sandbox_mode y sandbox_workspace_write. La presencia de un ajuste antiguo o de la opción de inicio correspondiente puede hacer que se utilice el sistema anterior; la documentación contempla una excepción para las listas de perfiles impuestas por la administración.

Para preparar una migración, elija expresamente qué sistema va a utilizar. Examine todas las capas de configuración que se cargan y compruebe por separado la lectura, la escritura y la red. En un entorno administrado, los perfiles disponibles pueden estar restringidos.

La consecuencia práctica es sencilla: copiar un ejemplo de configuración sin revisar lo que ya existe puede producir un comportamiento distinto del esperado. Mantenga una configuración breve y explique el motivo de cada excepción.

Prepare también comprobaciones con datos ficticios para confirmar que las restricciones funcionan: un intento de escritura fuera del ámbito autorizado debe fallar si ese límite es necesario. No realice esta comprobación solicitando una operación peligrosa sobre archivos reales.

Conserve un registro de los permisos efectivos junto con los procedimientos de su equipo. Ese registro ayuda más a diagnosticar problemas que una simple copia de las preferencias personales de quien instaló la herramienta.

5. Redactar un AGENTS.md breve y verificable

AGENTS.md permite transmitir las convenciones de trabajo del proyecto. Según la documentación oficial sobre AGENTS.md, Codex combina instrucciones globales con las que encuentra entre la raíz del proyecto y el directorio actual.

En cada carpeta, AGENTS.override.md tiene prioridad sobre AGENTS.md. Las instrucciones más cercanas al directorio actual se incorporan después de las generales. Tras modificar estos archivos, reinicie la sesión para reconstruir la cadena de instrucciones.

Este es un ejemplo de contenido que puede adaptar, sin dar por supuesto ningún comando de pruebas:

# Règles du projet

## Périmètre
- Limiter les changements à la demande formulée.
- Signaler toute modification nécessaire hors du périmètre prévu.
- Ne pas publier ni déployer sans accord explicite.

## Vérifications
- Lire les scripts du projet avant de lancer les contrôles.
- Exécuter les vérifications pertinentes pour les fichiers modifiés.
- Distinguer les contrôles réussis, échoués et non exécutés.

## Livraison
- Expliquer le comportement corrigé.
- Signaler les limites et les décisions restant à prendre.

Para examinar las instrucciones que se han tenido en cuenta, la documentación proporciona este comando:

codex --ask-for-approval never "Summarize the current instructions."

Revise la respuesta y compárela con los archivos esperados. Esta inspección ayuda a detectar un archivo de instrucciones prioritarias que haya pasado por alto.

Evite las reglas vagas y las obligaciones imposibles de aplicar. Indique dónde encontrar los procedimientos en lugar de copiar toda la documentación. Sobre todo, una prohibición escrita no equivale a una restricción técnica: proteja también los recursos que deben quedar fuera del alcance del agente.

6. Realizar una tarea y comprobar el resultado

Empiece por una petición cuyo alcance sea claro. Por ejemplo: examinar un fallo de validación, proponer una corrección limitada e indicar las comprobaciones necesarias. Esta formulación es un ejemplo de tarea, no un resultado observado.

Continúe en este orden:

Pida un diagnóstico. Solicite los archivos afectados, la hipótesis elegida y las pruebas que la respaldan.
Compruebe el alcance. Confirme que la corrección propuesta resuelve el fallo sin reescrituras ajenas al problema.
Autorice la edición adecuada. Conceda los permisos necesarios para el cambio previsto.
Examine las comprobaciones. Busque una prueba que hubiera detectado el fallo inicial.
Revise todas las diferencias. Incluya las dependencias, las configuraciones y los archivos generados.
Decida si integra el cambio. Reserve esa decisión para después de la revisión.

Una comprobación superada solo aporta pruebas sobre aquello que cubre. Un conjunto de pruebas puede pasar por alto un problema de accesibilidad, un dato mal migrado o una exposición de información. Ajuste las pruebas al riesgo del cambio.

Pida también un informe claro de las comprobaciones que no se han ejecutado. Una instalación de dependencias bloqueada, un servicio ausente o un entorno incompleto deben quedar reflejados en la entrega.

La guía detallada para trabajar con un agente de programación ayuda a dividir las peticiones en tareas manejables. El método sigue siendo aplicable aunque cambie el modelo o la interfaz.

Costes: distinguir la suscripción, la API y el trabajo humano

La página oficial de precios, consultada el 24 de octubre de 2026, muestra, entre otras opciones, el plan Plus por unos 20 dólares al mes y Pro desde unos 100 dólares al mes. Compruebe si su cuenta cumple los requisitos y qué funciones puede utilizar en el CLI antes de elegir un plan.

Criterio	Acceso con ChatGPT	Clave API
Recursos disponibles	Derechos y límites del plan	Consumo facturado a través de la API
Seguimiento	Panel de uso de la cuenta	Seguimiento de la organización de la API
Punto de atención	Créditos y usos compartidos	Consumo de las tareas automatizadas

Los límites dependen, entre otros factores, del modelo, del tamaño del contexto y de la complejidad de las tareas. Por tanto, un mensaje del usuario no tiene un coste fijo. El siguiente comando de sesión permite consultar los límites restantes cuando esa información está disponible:

/status

Al preparar su presupuesto, distinga la factura del servicio, la ejecución de las herramientas y el tiempo de revisión. Mida el coste de una tarea aceptada, incluidas sus correcciones, en lugar de quedarse con el de la primera respuesta.

Defina el alcance antes de empezar e interrumpa las exploraciones que ya no aporten pruebas útiles. Aun así, una petición breve puede requerir mucho trabajo: supervise tanto el resultado como el consumo.

El artículo sobre el coste real de un agente de IA amplía este análisis. Para obtener una estimación basada en volúmenes de tokens concretos, utilice la calculadora de precios de LLM.

Problemas frecuentes

El terminal no encuentra Codex. Compruebe el método de instalación y la ruta de los ejecutables. Vuelva a abrir el terminal después de modificar ese entorno. Reinstalar mediante otro método puede complicar el diagnóstico.

El inicio de sesión funciona, pero falta el acceso esperado. Compruebe el método de autenticación, la cuenta y el espacio de trabajo activos. Revise después los permisos administrativos y el plan asociado. No dé por hecho que se trata de un fallo de instalación.

El agente puede leer, pero no corregir. Examine los permisos efectivos y el directorio de trabajo. Si el objetivo es únicamente inspeccionar, este comportamiento puede ser el correcto. En caso contrario, conceda permiso de escritura dentro del ámbito necesario.

Parece que las reglas se ignoran. Busque un archivo de instrucciones prioritarias y compruebe desde qué carpeta ha iniciado la sesión. Compare las instrucciones que el agente resume con las esperadas y empiece después una sesión nueva.

Las pruebas fallan después de la corrección. Distinga entre un fallo introducido por el cambio, un problema preexistente y una dependencia ausente. Conserve los mensajes de error útiles y evite encadenar modificaciones sin una hipótesis explícita.

La tarea se amplía sin producir un resultado que pueda revisarse. Pida que se detenga y detalle los archivos modificados, el diagnóstico alcanzado y las dudas pendientes. Retome el trabajo con una petición más acotada.

En todos los casos, cambie un solo ajuste cada vez. Así podrá entender qué ha resuelto el problema y evitará conservar permisos innecesarios.

Lista de comprobación antes de confiarle un proyecto real

Páginas relacionadas

Preguntas frecuentes

¿Se puede usar Codex CLI sin una suscripción a ChatGPT?

Puede utilizar una clave API de OpenAI y pagar el consumo correspondiente. Este método de autenticación no utiliza los créditos incluidos en una suscripción a ChatGPT; el acceso a las funciones vinculadas a la nube también puede variar.

¿Codex CLI funciona íntegramente en local?

Que los comandos se ejecuten en local no significa que el modelo funcione en su equipo. Si utiliza un modelo alojado, los elementos necesarios para procesar la tarea se transmiten al servicio; revise las condiciones aplicables a su cuenta antes de enviar código confidencial.

¿Puede AGENTS.md impedir que se borren archivos?

Puede incluir una instrucción explícita, pero este archivo no sustituye una restricción técnica. Para proteger una carpeta, configure los permisos adecuados y mantenga una copia de seguridad independiente.

¿Conviene autorizar todos los comandos para evitar interrupciones?

Un ámbito de trabajo bien definido ya permite realizar muchas acciones sin interrupciones. Ampliar todos los permisos para resolver un bloqueo puntual también deja expuestos archivos y servicios ajenos a la tarea.

¿Se puede utilizar Codex CLI en un proceso de integración continua?

Sí, la documentación contempla usos programáticos y recomienda la autenticación mediante API para la automatización general. Prepare un entorno aislado, limite los secretos disponibles y establezca una validación independiente antes de publicar.

Codex CLI, guía de referencia: instalación, modos de aprobación, entorno aislado, AGENTS.md y costes