El archivo general de configuración de Codex es config.toml, no config.json. Aun así, conocer el nombre correcto no basta: una opción puede estar bien escrita y no aplicarse porque la pusiste en la capa equivocada, otro valor tiene mayor prioridad o una política administrada la limita.
Los valores personales viven en ~/.codex/config.toml. Un repositorio marcado como de confianza puede añadir .codex/config.toml. Los modos reutilizables se guardan en archivos de perfil separados y los experimentos de una sola ejecución encajan mejor como overrides de CLI. Codex CLI y la extensión de IDE comparten estas capas en el mismo host. OpenAI documenta las ubicaciones en Config basics.
Antes de tocar una capa, respalda solo el archivo afectado. Borrar todo ~/.codex para corregir una tabla puede eliminar también credenciales, perfiles, reglas y estado que siguen funcionando.
La precedencia decide qué valor es efectivo
Codex resuelve la configuración ordinaria de mayor a menor prioridad:
- opciones CLI y
--config; - archivos
.codex/config.tomlde un proyecto de confianza, ganando el más cercano al directorio actual; - el perfil elegido con
--profile; ~/.codex/config.toml;/etc/codex/config.tomlen Unix, si existe;- valores integrados.
Esta es la secuencia actual de Configuration precedence. Si cambias el archivo personal y no ocurre nada, busca primero un override de CLI, proyecto o perfil.
| Necesidad | Capa adecuada | Motivo |
|---|---|---|
| Modelo, razonamiento, avisos o MCP personales | Usuario | Deben acompañarte entre proyectos |
| Límite de ejecución de un repositorio | Proyecto de confianza | La política viaja con ese código |
| Modo de auditoría o revisión profunda | Perfil separado | Cambia un conjunto sin duplicar la base |
| Prueba puntual | CLI override | No se convierte en política persistente |
| Restricción obligatoria de empresa | Requirements administrados | El usuario no puede debilitarla |
Hay claves que un proyecto no puede sobrescribir: clases machine-local de provider, autenticación, selección de perfil, notificaciones y telemetría. La lista actual incluye model_provider, model_providers, profile y otel. Consulta el listado completo en Configuration reference y coloca esas claves en el nivel de usuario.
Un mínimo seguro es mejor que un catálogo
Una base personal puede expresar solo las decisiones necesarias:
tomlmodel = "gpt-5.6" model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached"
Comprueba que el identificador de modelo esté disponible en tu cliente, cuenta y ruta actuales. Es un dato cambiante, no una promesa permanente. Si el default instalado ya sirve, omite la clave: cada valor persistente añade una decisión que tendrás que mantener.
approval_policy controla cuándo Codex se detiene para pedir aprobación. sandbox_mode controla el alcance de los comandos. Son barreras distintas. OpenAI presenta workspace-write con on-request como combinación de menor riesgo para automatización local. danger-full-access con never elimina ambas y no debería ser el atajo cotidiano. Las definiciones actuales están en Sandbox: Configure defaults.
El acceso web también es independiente. El web_search superior admite cached, indexed, live y disabled. Los toggles antiguos bajo [features] están obsoletos; que una plantilla vieja sea TOML válido no significa que siga representando el contrato actual.
Los perfiles actuales son archivos independientes
Un modo de revisión conservador puede vivir en:
toml# ~/.codex/revision.config.toml model_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "read-only"
Se activa así:
bashcodex --profile revision
El perfil solo necesita las diferencias respecto a la base. Proyecto y CLI aún pueden tener prioridad. Desde Codex 0.134.0, --profile ya no lee [profiles.revision] dentro del archivo principal y el selector superior profile = "revision" dejó de estar soportado. El formato vigente está en Advanced Config: Profiles.
El provider es una ruta específica, no parte del mínimo universal
Bedrock, Azure y un provider personalizado tienen contratos diferentes. Antes de copiar su bloque, confirma cuatro hechos: qué superficie de Codex vas a usar, qué identificador de modelo o deployment espera esa ruta, qué endpoint es correcto y dónde obtiene la credencial el proceso.
Una tabla de provider puede analizarse bien aunque el endpoint no exista, el modelo no esté desplegado, la clave pertenezca a otra cuenta o la IDE no herede la variable de entorno. Por eso conviene mantener el baseline general separado de la guía del provider concreto.
No pegues una clave real en el TOML de un repositorio ni en un mensaje de soporte. Cuando el campo admita una variable de entorno, guarda el nombre de la variable y verifica por separado que el proceso CLI, IDE, WSL o runner pueda verla.
Un MCP tiene sintaxis, transporte, credencial y tools
Para un servidor STDIO local:
toml[mcp_servers.docs] command = "docs-server" args = ["--read-only"] env_vars = ["DOCS_TOKEN"] startup_timeout_sec = 20 tool_timeout_sec = 60 enabled = true
Para streamable HTTP:
toml[mcp_servers.tareas] url = "https://mcp.example.internal/mcp" bearer_token_env_var = "TAREAS_MCP_TOKEN" enabled = true
La guía oficial de Model Context Protocol distingue STDIO, streamable HTTP, OAuth, headers desde entorno, timeouts y listas de tools.
Después de editar, usa los comandos que ofrezca tu versión instalada:
bashcodex mcp list codex mcp --help
Para un servidor OAuth existe codex mcp login <server-name>. Aparecer en la lista prueba que Codex leyó la definición; no prueba que el ejecutable arranque, la URL responda, la autenticación funcione ni que una tool concreta sea correcta.
Diagnostica desde el primer límite sin demostrar
Versiones recientes exponen --strict-config y doctor. Comprueba primero tu instalación:
bashcodex --version codex --help codex doctor --help
Si aparecen esas opciones, una pasada de solo lectura es:
bashcodex --strict-config doctor --summary
El modo strict convierte campos no reconocidos en error. doctor revisa instalación, config, auth y runtime. Ninguno sustituye una petición real al provider o una llamada a la tool MCP.
| Síntoma | Primera comprobación |
|---|---|
| Solo se ignora en un repo | Trust y .codex/config.toml más cercano |
| CLI funciona, IDE no ve la clave | Entorno efectivo del proceso IDE |
| Unknown field al iniciar | Versión del cliente y reference actual |
| Cambias model pero sigue otra ruta | model_provider, perfil, proyecto y CLI |
| MCP aparece pero no ofrece tools | Command/URL, auth, timeout y tool individual |
| Un equipo corporativo rechaza full access | requirements.toml administrado |
En Business o Enterprise, requirements.toml puede limitar approval, permission profiles, web search, MCP permitidos, plugins y features. Ante un conflicto, el cliente puede volver a un valor compatible y mostrar un aviso. Admin-enforced requirements describe esa frontera. Mover la misma opción prohibida a otro archivo local no la supera.
Haz que cada cambio tenga un único resultado observable: elige la capa, crea una copia, modifica un bloque, valida sintaxis y precedencia, y ejecuta una tarea de bajo riesgo donde se vea el efecto. Si falla, vuelve al primer límite que todavía no hayas demostrado.
Si la decisión real es elegir agente de programación y no configurar Codex, consulta la comparación entre Claude Code y Codex.
