Codex CLI: configura AGENTS.md, perfiles y permisos sin convertir el repo en una excepción
Codex CLI no se vuelve fiable por instalarlo y darle acceso. La unidad de configuración útil es un repositorio con instrucciones cortas, perfiles de permisos y un sandbox que haga explícito qué puede hacer el agente.
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.
Checklist
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.
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 gratisEjemplo 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.
Puntos a revisar
Lo que conviene comprobar
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.
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.
Checklist
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.
Fuentes y referencias
También te puede interesar
Codex con internet: sandbox y seguridadAGENTS.md y CLAUDE.md: contexto para agentesHooks para agentes de códigoMétricas para agentes de códigoCómo coordinar varios agentes de códigoRecibe una lectura semanal de herramientas IA para devs
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
