Por qué tu config de Codex no funciona: el problema con la carpeta .codex/

Mi config de Codex no se estaba aplicando. Edité config.toml, agregué reglas a AGENTS.md, revisé la documentación dos veces. Nada cambiaba. El agente seguía ignorando todo.

Terminé desenredando toda la estructura de carpetas. El problema no era lo que escribía en los archivos. Era dónde estaban ubicados.

Dos objetivos conviven en un mismo repo

Codex intenta resolver dos cosas al mismo tiempo. Una es la experimentación rápida con sus propias funcionalidades beta. La otra es la compatibilidad entre agentes, un estándar compartido que herramientas como Claude Code u OpenCode también puedan leer.

Esta división genera dos carpetas.

.codex/ es el espacio de configuración exclusivo de Codex. Las políticas de sandbox, las reglas de aprobación y los controles de ejecución van ahí. .agents/ es el formato compartido. Las skills, los plugins y el registro del marketplace viven en este lado, y cualquier agente que siga el estándar puede leerlos.

Al principio no sabía nada de esta división. Puse un archivo SKILL.md dentro de .codex/ y la skill nunca cargó. Moverlo a .agents/skills/ lo resolvió al instante. El límite es estricto: si otro agente tiene que poder leerlo, pertenece a .agents/. Todo lo demás va en .codex/.

Ambas carpetas reciben protección de solo lectura en modo workspace-write, igual que .git/.

La config del proyecto y la del usuario tienen el mismo nombre

Existe una carpeta .codex/ en la raíz del proyecto y una ~/.codex/ en el directorio home. Hacen cosas completamente distintas.

La .codex/ del proyecto guarda configuraciones que se comparten con el equipo: políticas de sandbox, flujos de aprobación, definiciones de agentes. La ~/.codex/ guarda el estado personal: tokens de autenticación, historial de comandos, archivos de gestión de worktrees.

Creé un agente reviewer en ~/.codex/agents/ y no entendía por qué mis compañeros no lo tenían. Solo existía en mi máquina. Mover el archivo a .codex/agents/reviewer.toml en el proyecto hizo que viajara con el repo al hacer clone.

La confusión empeora porque Codex sigue en beta. Los archivos de worktree de la app de escritorio, los datos de sesión y las credenciales de autenticación se acumulan todos en ~/.codex/ sin una separación clara. El límite entre “mis cosas” y “cosas del proyecto” se difumina más de lo que debería.

La prioridad de configuración sigue un orden específico: la config administrada tiene precedencia sobre los overrides de sesión, que tienen precedencia sobre la config del usuario. Cuando algo no se aplica, revisá qué nivel estás editando.

El nivel de confianza es el verdadero obstáculo

Aquí es donde la mayoría se queda atascada, y yo perdí tiempo real antes de entender por qué.

Codex no carga la .codex/ del proyecto desde repos que no son de confianza. Para nada. Podés editar config.toml todo lo que quieras en un repo recién clonado y nada se va a aplicar. El archivo existe, la sintaxis es correcta, y Codex lo ignora en silencio.

La razón tiene sentido una vez que la ves. .agents/ abre un camino para que skills externas fluyan hacia tu entorno. Cualquier repo podría traer una config maliciosa. Entonces Codex tomó una decisión: mayor compatibilidad con el ecosistema de agentes, pero verificación de confianza más estricta para las configuraciones que vienen del repo. Tenés que marcar explícitamente un proyecto como confiable antes de que su config .codex/ se active.

Configurá projects.<path>.trust_level = "trusted" en tu config de usuario. El acceso a la red también está bloqueado por defecto, con la búsqueda web ofreciendo tres modos: cached, live o disabled. Incluso en modo workspace-write, .git/ y .codex/ permanecen protegidas contra escritura.

Pasé cerca de una hora editando un config.toml del proyecto que estaba siendo completamente ignorado porque no había configurado el nivel de confianza. Sin mensaje de error, sin advertencia. Solo silencio. Este es probablemente el punto de fricción más común al configurar Codex, y un mejor sistema de mensajes de error acá le ahorraría mucho tiempo a mucha gente.

La complejidad no es accidental

La estructura de carpetas es desordenada, pero no de manera aleatoria. Codex está persiguiendo dos objetivos que tiran en direcciones opuestas.

La iteración rápida en beta hace que .codex/ acumule archivos de configuración, definiciones de reglas, hooks y artefactos de gestión de la app a un ritmo que supera la documentación. La compatibilidad entre agentes hace que .agents/ necesite una estructura separada y portable para skills y contenido del marketplace. Y como .agents/ abre la puerta a código externo, la capa de verificación de confianza tuvo que existir.

Cuando no estés seguro de dónde va un archivo, hacete una pregunta: ¿esto es específico de Codex, o debería que otros agentes también puedan leerlo? La primera respuesta apunta a .codex/. La segunda apunta a .agents/.

Cuando tu config no esté funcionando, no empieces por editar el contenido del archivo. Revisá en qué carpeta está y si el repo tiene confianza. Casi siempre el problema está ahí.