Por qué tu configuración de Codex no funciona: el problema de la carpeta .codex/

Mi configuración de Codex no se aplicaba. Edité config.toml, añadí reglas a AGENTS.md y releí la documentación dos veces. Nada cambiaba. El agente seguía ignorándolo todo.

Al final desmontté la estructura de carpetas entera. El problema no estaba en lo que escribía en los archivos, sino en dónde estaban ubicados.

Dos objetivos conviven en un mismo repositorio

Codex intenta resolver dos cosas a la vez. Por un lado, la experimentación rápida con sus propias funcionalidades en beta. Por otro, la compatibilidad entre agentes, un estándar compartido que herramientas como Claude Code u OpenCode también pueden 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 límites en tiempo de ejecución van aquí. .agents/ es el formato compartido. Las skills, los plugins y el registro del marketplace viven en este lado, legibles por cualquier agente que siga el estándar.

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

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

La config de proyecto y la de usuario comparten el mismo nombre

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

La .codex/ del proyecto contiene los ajustes que compartes con tu 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 revisor en ~/.codex/agents/ y no entendía por qué mis compañeros no lo tenían. Solo existía en mi máquina. Al mover el archivo al .codex/agents/reviewer.toml del proyecto, viajaba con el repositorio al clonarlo.

La confusión aumenta 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. La frontera entre “mis cosas” y “cosas del proyecto” se difumina más de lo que debería.

La prioridad de configuración sigue un orden concreto: la config gestionada tiene precedencia sobre los overrides de sesión, que a su vez tienen precedencia sobre la config de usuario. Cuando algo no se aplica, comprueba en qué nivel estás editando.

El nivel de confianza es la verdadera barrera

Aquí es donde la mayoría se bloquea, y yo perdí tiempo real antes de entender el motivo.

Codex no carga la .codex/ del proyecto desde repositorios que no son de confianza. En absoluto. Puedes editar config.toml todo lo que quieras en un repositorio recién clonado y nada se aplicará. El archivo está ahí, 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 entren en tu entorno. Cualquier repositorio podría incluir una config maliciosa. Así que Codex tomó esa decisión: mayor compatibilidad con el ecosistema de agentes, pero verificación de confianza más estricta para los ajustes proporcionados por el repositorio. Tienes que marcar explícitamente un proyecto como de confianza antes de que su configuración .codex/ se active.

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

Pasé cerca de una hora editando un config.toml de proyecto que estaba siendo ignorado por completo porque no había configurado el nivel de confianza. Sin mensaje de error, sin advertencia. Solo silencio. Probablemente sea la fuente de frustración más común al configurar Codex, y un mejor sistema de mensajes de error ahorraría mucho tiempo a mucha gente.

La complejidad no es accidental

La estructura de carpetas es desordenada, pero no de forma aleatoria. Codex persigue dos objetivos que tiran en direcciones opuestas.

La iteración beta rápida 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 las skills y el contenido del marketplace. Y como .agents/ abre la puerta a código externo, la capa de verificación de confianza tenía que existir.

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

Cuando tu configuración no funciona, no empieces editando el contenido del archivo. Comprueba en qué carpeta está y si el repositorio es de confianza. Ahí es donde casi siempre está el problema.