Codex config.toml no empieza con “pega este ejemplo”. Empieza con una decisión de propietario: qué debe vivir en tu configuración personal, qué puede viajar con un repositorio trusted, qué solo debe afectar una ejecución y qué conviene convertir en profile.
Las páginas oficiales de OpenAI sobre Codex config, MCP, authentication y sandbox se revisaron el 21 de abril de 2026. Los comandos locales se comprobaron contra codex-cli 0.121.0, así que conviene volver a mirar codex --help si tu instalación cambia.
Primero elige la capa correcta
| Quieres cambiar | Mejor capa | Por qué |
|---|---|---|
| Modelo por defecto, approvals, notificaciones, credential store | ~/.codex/config.toml | Debe seguirte a ti, no al repositorio |
| Instrucciones del repo, sandbox conservador, defaults MCP de equipo | .codex/config.toml en un proyecto trusted | Es policy compartida y revisable |
| Modelo, sandbox o nested key para una sola ejecución | CLI flag o --config | No muta archivos permanentes |
| Modo repetible como review o local edit | [profiles.<name>] | Se activa explícitamente con --profile |
| Nuevo MCP server | Primero codex mcp add | El helper reduce errores de TOML y env |
Si todavía estás decidiendo entre subscription y API key, empieza por la guía de Codex API key vs subscription. Si el problema es cuota, ve a límites de uso de Codex.
Precedence: qué gana en un conflicto
El orden actual, de más fuerte a más débil, es:
| Rango | Capa | Consecuencia |
|---|---|---|
| 1 | CLI flags y --config | Una ejecución puede pisar todos los archivos inferiores |
| 2 | Profile seleccionado con --profile <name> | Un preset con nombre pisa defaults normales |
| 3 | Project .codex/config.toml | Solo aplica en proyectos trusted; gana el archivo trusted más cercano al cwd |
| 4 | User ~/.codex/config.toml | Tu capa personal |
| 5 | System /etc/codex/config.toml | Defaults de máquina u organización |
| 6 | Built-in defaults | Lo que queda cuando nada más define la clave |
Por eso, cuando una edición no parece funcionar, revisa primero alias de shell, flags, --config, profile activo, cwd y trust del proyecto.
User config: defaults personales sin secretos
Un archivo pequeño suele ser mejor que una plantilla completa:
toml#:schema https://developers.openai.com/codex/config-schema.json model = "gpt-5.4" approval_policy = "on-request" sandbox_mode = "workspace-write" allow_login_shell = false cli_auth_credentials_store = "keyring"
Ese bloque fija modelo, approval policy, permisos de workspace, login shell y credential store. No guarda tokens. auth.json puede contener access tokens; no lo compartas ni lo subas al repo. API keys y bearer tokens deben vivir en environment variables, keyring o un secret manager privado.
Project config: policy compartida, no estado privado
El project config debe ser conservador:
toml#:schema https://developers.openai.com/codex/config-schema.json approval_policy = "untrusted" sandbox_mode = "workspace-write" allow_login_shell = false developer_instructions = """ Follow this repository's AGENTS.md. Keep generated assets in documented project paths. Do not commit credentials, auth state, or provider tokens. """
Esto sí es policy de repo. No expone tokens, no abre toda la máquina y no impone tu ruta privada a otras personas. Ten especial cuidado con danger-full-access y approval_policy = "never": juntos solo tienen sentido en un entorno aislado y conscientemente confiable.
MCP y provider route
Para MCP, usa primero el helper:
bashcodex mcp add docs --env DOCS_TOKEN="$DOCS_TOKEN" -- node ./mcp/docs-server.mjs codex mcp get docs --json
Si necesitas TOML directo, deja el secreto fuera:
toml[mcp_servers.docs] command = "node" args = ["./mcp/docs-server.mjs"] env_vars = ["DOCS_TOKEN"] startup_timeout_sec = 10 tool_timeout_sec = 60 required = true
Para un MCP HTTP, usa una variable:
toml[mcp_servers.internal_docs] url = "https://mcp.example.com" bearer_token_env_var = "DOCS_MCP_TOKEN" enabled = true required = true
openai_base_url cambia el endpoint del built-in OpenAI provider. No decide por sí solo si estás usando ChatGPT subscription, API billing o una policy de workspace.
Sandbox, approvals, overrides y profiles
Para desarrollo local normal, workspace-write con on-request es un buen punto de partida. Para review, read-only suele ser suficiente. danger-full-access debe reservarse para entornos aislados donde de verdad hace falta autoridad amplia.
Los experimentos van mejor como comando:
bashcodex --model gpt-5.4-mini codex --sandbox read-only codex --config model='"gpt-5.4"' codex --config sandbox_workspace_write.network_access=true
Un preset repetible puede ser profile:
toml[profiles.review] model = "gpt-5.4" sandbox_mode = "read-only" approval_policy = "on-request"
bashcodex --profile review
OpenAI describe profiles como experimental y no soportados en la IDE extension. Trátalos como comodidad de CLI, no como policy universal de todas las superficies Codex.
Cuando el config no aplica
| Revisa | Qué mirar |
|---|---|
| Current command | alias, flags, --config, --profile |
| Current directory | pwd, repo root, nested .codex/config.toml |
| Project trust | project config se omite si el proyecto no está trusted |
| TOML syntax | quotes, arrays, table names, schema hint |
| Key support | official config reference y local codex --help |
| MCP server | codex mcp get <name> --json |
| Auth state | auth.json, keyring, env vars |
Si estás configurando trabajo visual de escritorio o permisos de navegador, esa es otra capa. Para app permissions y browser workflows, usa la guía de Codex Computer Use.
FAQ
¿Dónde está Codex config.toml?
El user config está en ~/.codex/config.toml. Un proyecto trusted puede tener .codex/config.toml. El system config puede estar en /etc/codex/config.toml.
¿Debo poner API keys en config.toml?
No en el project config compartido. Usa environment variables, OS keyring, private user config cuando corresponda o el flujo de autenticación esperado por Codex.
¿Por qué no aplica .codex/config.toml?
Comprueba project trust, cwd, archivos .codex/config.toml más cercanos, selected profile, flags y --config.
¿Cuándo uso --config?
Para experimentos de una ejecución: modelo, sandbox, web/search behavior o nested keys. Si se vuelve hábito, pásalo a user config o profile.
¿danger-full-access es válido?
Sí, pero solo en un entorno aislado donde la tarea necesita broad access. No es un default razonable para un repo compartido.
¿Dónde está el schema oficial?
En https://developers.openai.com/codex/config-schema.json. Puedes añadir #:schema https://developers.openai.com/codex/config-schema.json arriba del TOML si tu editor lo aprovecha.