Codex CLI: configura AGENTS.md, perfiles y permisos sin convertir el repo en una excepción

Codex CLI es el cliente local de terminal para inspeccionar, editar, ejecutar comandos y automatizar trabajo repetible sobre un repositorio. La keyword principal es Codex CLI; la intención de búsqueda es práctica: instalarlo no basta, un developer quiere saber qué poner en AGENTS.md, dónde vive config.toml, cómo usar perfiles y cómo evitar permisos globales que nadie pueda explicar.

TL;DR

La configuración que recomiendo tiene tres capas: instrucciones de repo para el comportamiento, configuración personal para preferencias de máquina y perfiles para el riesgo de cada tarea. No metas todas las reglas en un prompt, ni todos los permisos en un config.toml global.

Mi postura: el preset cómodo de escritura en workspace es buen punto de partida para desarrollo local; danger-full-access y red abierta no son un perfil de productividad. Son excepciones temporales que deben tener un motivo, una tarea y una revisión.

Qué configura Codex CLI exactamente

Codex CLI puede trabajar de forma interactiva, con codex exec en scripts o CI, y con la misma base de configuración que la extensión de IDE. La CLI tiene comandos visibles para iniciar instrucciones (/init), consultar el estado (/status), elegir permisos (/permissions) y revisar cambios (/review). El valor no es el terminal en sí: es poder convertir ese ciclo en una configuración reproducible.

Separa dos preguntas que suelen mezclarse: qué sabe el agente sobre el proyecto y qué puede hacer. AGENTS.md explica comandos, restricciones y criterios de aceptación; sandbox, red y approval policy controlan capacidades reales. Una frase que prohíbe publicar no bloquea un token con permisos para publicar.

La instrucción guía la tarea; el perfil y el sandbox delimitan lo que el agente puede hacer; la aprobación decide cuándo debe detenerse.

La jerarquía que evita sorpresas

Las opciones no viven en un único archivo. Codex aplica primero flags de CLI y valores --config, después .codex/config.toml desde la raíz al subdirectorio actual, después el perfil seleccionado, después ~/.codex/config.toml y finalmente valores por defecto. Los ficheros de proyecto solo se cargan cuando confías en el proyecto; eso evita que clonar un repo active configuración, hooks o reglas sin tu decisión.

Usa esa precedencia para no crear una bola de nieve. En ~/.codex/config.toml deja defaults personales que no dependen del repo. En .codex/config.toml deja solo ajustes de proyecto que el equipo puede revisar. En un perfil coloca la diferencia de riesgo: por ejemplo, revisión de solo lectura frente a edición local con red controlada.

AGENTS.md es un contrato operativo, no un README duplicado

Codex construye una cadena de instrucciones al inicio de cada ejecución: lee una guía global y después recorre desde la raíz Git hasta el directorio actual. En cada nivel, AGENTS.override.md gana a AGENTS.md; los archivos más cercanos al código aparecen al final y por tanto refinan las reglas generales. No conviertas esto en una enciclopedia: el límite combinado es de 32 KiB por defecto y una instrucción crítica enterrada deja de ser una instrucción.

Un AGENTS.md de raíz debería responder a preguntas operativas: cómo instalar, qué comandos validan, qué rutas son sensibles, qué cambio exige migración o revisión, y qué nunca debe incluirse en logs o commits. Un override bajo services/payments/ puede añadir comandos y límites de esa zona sin contaminar el resto del monorepo.

No guardes secretos, claves, playbooks de incidente completos ni datos de clientes. El archivo se entrega como contexto a un agente: es un contrato de trabajo, no una caja fuerte.

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Ejemplo mínimo: un repo con guardrails verificables

Este ejemplo es deliberadamente corto. No intenta describir el producto; declara las pocas reglas que cambian el resultado de una tarea. Las políticas reales de aprobación y red viven en configuración, no en Markdown.

Lo que conviene comprobar

AGENTS.md

# Contrato de trabajo del repositorio

## Antes de editar
- Lee docs/architecture.md y ejecuta npm ci.
- No modifiques .github/workflows, infra/ ni migraciones sin pedir aprobación.

## Validación
- Ejecuta npm run lint y npm test para cambios en src/.
- Explica en el resultado los tests que no pudiste ejecutar.

## Datos
- Nunca imprimas variables de entorno ni copies datos de producción a fixtures.

Para comprobar qué se cargó, inicia una sesión nueva desde la raíz y pide a Codex que enumere las instrucciones activas; desde un subdirectorio, repite la comprobación. Si la explicación no coincide con tu jerarquía, corrige el archivo más cercano o un override olvidado antes de automatizar nada.

Perfiles: el permiso debe seguir la tarea

Un perfil no es una identidad de persona; es una política para un tipo de trabajo. Crea uno de lectura para explorar o revisar, uno de edición de workspace para cambios locales y uno aislado para una tarea que necesita red. Evita el perfil todopoderoso que se convierte en el default por pereza.

Los perfiles viven junto a la configuración de usuario y se seleccionan con --profile. Eso permite que config.toml guarde una base común mientras cada perfil cambia lo mínimo: sandbox, política de aprobación y, cuando sea imprescindible, la política de red. No intentes mover credenciales de proveedor o telemetría a .codex/config.toml del repo: la documentación reserva esas claves para el nivel de usuario.

La regla que funciona: el CI no hereda el perfil de tu portátil, y el repositorio no puede rebajar la política de tu máquina. Define la cuenta, secretos y permisos del runner por separado y ejecuta un modo no interactivo solo si ya tienes un contrato de validación y rollback.

Un config.toml razonable para empezar

El siguiente perfil permite editar dentro del workspace y deja las decisiones que amplían capacidad bajo aprobación. No es una configuración universal: es un punto de partida que debes probar en un repositorio sin datos sensibles.

~/.codex/local-edit.config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false
Lánzalo con codex --profile local-edit y consulta /status antes de la primera tarea. Si necesitas documentación o una dependencia, no conviertas la sesión entera en red abierta: crea un perfil de investigación limitado o pide aprobación para esa operación concreta.

Sandbox, aprobación y red son controles distintos

El sandbox define la frontera técnica —por ejemplo, lectura, escritura en workspace o acceso más amplio—; la approval policy define cuándo Codex se detiene para pedir autorización. Con el modo Auto (workspace-write y on-request), puede editar y ejecutar dentro del directorio de trabajo, pero debe pedir permiso para salir de ese límite o usar la red.

La red merece una decisión aparte. Con workspace-write, está apagada salvo que la actives. Si la activas sin proxy, el tráfico saliente es directo y no queda limitado por una lista de dominios. Para restringir destinos, activa features.network_proxy y declara reglas allowlist; el proxy no concede red por sí solo. * equivale a red pública amplia, no a una lista de seguridad.

Las tools MCP y las integraciones no quedan automáticamente filtradas por ese proxy de comandos. Revisa sus propios scopes, sus anotaciones de efectos y sus políticas de aprobación. El modelo puede encadenar herramientas: analizar cada permiso aislado es menos útil que mirar el flujo completo de datos.

Qué no automatizar todavía

No ejecutes con approval_policy = "never" una acción que publique, borre, migre datos, rote secretos, cambie infraestructura o escriba fuera de un entorno de pruebas. El modo no interactivo es para operaciones repetibles cuyo diff, test, destino y rollback ya están definidos; no para eliminar fricción cuando aún no hay control.

Tampoco confundas tests verdes con autorización. Un test puede demostrar comportamiento local y aun así no saber si el usuario tiene permiso para enviar un correo, desplegar un cambio o leer un recurso de otro tenant. Esas barreras viven en el backend, los tokens y los entornos, no en la conversación.

Checklist de adopción para un equipo

Añadir un AGENTS.md raíz de menos de dos pantallas con setup, validación, rutas sensibles y manejo de datos.
Crear un override solo donde la regla sea realmente local, y probar qué archivos carga Codex desde esa carpeta.
Definir perfiles de lectura, edición y red limitada; empezar por lectura o edición sin red.
Mantener on-request para cambios de entorno, red, rutas protegidas y herramientas con efectos.
Separar la configuración del runner de CI de la configuración personal de un developer.
Revisar el diff, los comandos y los tests, y registrar por qué se permitió una excepción de permisos.
Medir bloqueos, reintentos, revisiones rechazadas y tiempo ahorrado antes de ampliar autonomía.

Preguntas frecuentes

¿Qué es Codex CLI?

Es el cliente de terminal de Codex para inspeccionar repositorios, editar archivos, ejecutar comandos y automatizar flujos repetibles desde el directorio del proyecto.

¿Dónde vive config.toml?

La configuración personal vive en ~/.codex/config.toml; los repos pueden añadir .codex/config.toml, que Codex carga solo para proyectos de confianza y que no puede reemplazar claves sensibles de nivel máquina.

¿Qué diferencia hay entre AGENTS.md y config.toml?

AGENTS.md aporta instrucciones y contexto; config.toml controla opciones del cliente como perfiles, sandbox, aprobaciones, red y servidores MCP. Un archivo de instrucciones no concede ni revoca permisos técnicos.

¿Debo usar approval_policy never?

Solo en automatizaciones estrechas y verificadas donde la acción, el entorno, el rollback y los límites de datos ya estén definidos. Para trabajo exploratorio o mutaciones sensibles, conserva aprobación humana.

¿La allowlist de red se activa sola al declarar dominios?

No. Debes habilitar red y el network proxy; con red apagada el proxy no hace nada, y con red encendida sin proxy el tráfico sigue siendo directo.

¿Puedo usar el mismo perfil en mi portátil y CI?

No es buena idea. CI necesita una identidad, secretos, permisos y rollback específicos; no debe heredar una configuración interactiva personal.

Cómo configurar Codex CLI en un repositorio de forma segura

Crear un checkpoint. Confirma que el repositorio está limpio o registra el estado actual antes de pedir un cambio al agente.
Escribir el contrato raíz. Añade AGENTS.md con setup, comandos de validación, rutas sensibles y reglas de datos que el equipo pueda comprobar.
Probar la jerarquía. Desde la raíz y desde un subdirectorio, pide a Codex que enumere las instrucciones activas y corrige overrides inesperados.
Elegir el perfil base. Empieza con lectura o workspace-write con approval_policy on-request y red desactivada.
Separar excepciones. Crea un perfil de investigación o una aprobación puntual para red; no rebajes el perfil base por una única tarea.
Configurar la red con límites. Si necesitas red, activa network_proxy y permite solo hosts concretos necesarios para la tarea.
Ejecutar una tarea reversible. Usa documentación, tests o un cambio pequeño en un repositorio de riesgo medio y revisa comandos, diff y evidencia.
Medir antes de ampliar. Registra bloqueos de permisos, tests fallidos, reintentos y hallazgos de revisión durante varias tareas.
Automatizar al final. Usa codex exec en CI solo cuando las entradas, acciones permitidas, aprobación, validación y rollback estén definidos fuera del prompt. > ### Límite sano > > Paraleliza investigación y tareas acotadas. No paralelices criterio técnico ni integración final.