Detalles de configuración de config.toml: controlando todos los interruptores desde un solo archivo
📚 Navegación de la serie: El artículo anterior 17 · Control del ordenador y del navegador (Computer Use) le dio manos a Codex: permitirle ver la pantalla, hacer clics en el escritorio y abrir el navegador. Este artículo regresa de la interfaz gráfica a un simple archivo de texto:
config.toml. Lo has visto de forma dispersa en los capítulos anteriores (al configurar el sandbox, activar la memoria o asignar modelos); en esta sección lo detallaremos de forma sistemática: dónde se guarda este archivo, cómo se estructura, qué controla cada clave y quién tiene prioridad cuando se superponen varios archivos.
Se suele decir que los archivos de configuración son cosas "para ver después de instalar" y que es mejor no tocarlos si funcionan; la verdad es que con Codex ocurre exactamente lo contrario.
Mi propia experiencia fue la siguiente: cuando empecé a usarlo en marzo de 2026, no toqué para nada config.toml; cada vez que abría Codex, cambiaba el modelo manualmente con /model, ajustaba permisos con /permissions y activaba la red temporalmente con --search, repitiendo las mismas acciones siete u ocho veces al día. Hasta que un día hice la cuenta: solo para la combinación de "cambiar al modelo avanzado + habilitar la escritura en el espacio de trabajo", esa semana había escrito las instrucciones no menos de treinta veces. En ese momento me di cuenta: había convertido algo que se "escribe una vez y dura para siempre" en un proceso de "empezar de cero cada vez".
El valor de config.toml reside precisamente aquí: no está diseñado para que los expertos presuman de sus habilidades, sino para ahorrar trabajo a todos aquellos que prefieren evitar molestias. Cuanto más perezoso seas para configurarlo en cada ocasión, más te convendrá dedicar diez minutos a estructurarlo correctamente.
Aún más importante, oculta una trampa muy común para los principiantes: el mismo bloque de configuración escrito en tu directorio principal y en el directorio de un proyecto puede comportarse de forma totalmente diferente, o incluso la versión del proyecto puede no aplicarse en absoluto. Este artículo desglosará las reglas de "dónde se ubican los archivos y quién tiene prioridad" para que entiendas el flujo con claridad al escribir la configuración.
Al terminar este artículo, obtendrás:
- Una explicación sencilla sobre qué es config.toml y cómo se divide el trabajo frente a AGENTS.md (no los vuelvas a confundir).
- Dónde guardar, qué controlan y qué debe incluir el archivo config.toml a nivel de usuario (
~/.codex/config.toml) y a nivel de proyecto (.codex/config.toml). - Una tabla de prioridad de "quién sobrescribe a quién", junto con una restricción de seguridad clave para principiantes (ciertas claves escritas en el proyecto simplemente se ignorarán).
- Qué hacen y cuáles son los valores predeterminados de las siete u ocho opciones que modificarás con más frecuencia (
model,approval_policy,sandbox_mode,web_search,[features]...). - Una plantilla mínima que puedes copiar + comandos temporales con
-c+ práctica real para alternar perfiles con--profile, que podrás verificar por ti mismo.
01 Comprender primero: qué es realmente config.toml y cómo se divide el trabajo frente a AGENTS.md
Definamos el concepto de entrada: config.toml es el "conjunto de interruptores de comportamiento" de Codex: gestiona modelos, aprobaciones, sandboxing, servidores MCP e interruptores en formato TOML; es un sistema diferente a AGENTS.md, donde uno controla "cómo trabajar" y el otro controla "qué recordar".
Muchos suelen confundir ambos al principio. En el artículo 11 · AGENTS.md escribiste la documentación del proyecto, y en el artículo 15 · Permisos, sandbox y aprobaciones configuraste el sandbox; el primero se define en AGENTS.md y el segundo en config.toml, almacenando contenidos completamente distintos.
Analogía: El "manual del conductor" del coche frente a los "mandos de la consola central". AGENTS.md es como el manual de instrucciones en la guantera: contiene directrices en lenguaje natural dirigidas al modelo del tipo "este coche usa gasolina de 95 octanos" o "deja calentar el motor en invierno antes de circular", leyéndose al iniciar como contexto general. config.toml es diferente: equivale a la fila de mandos físicos en la consola: temperatura del climatizador, calefacción de asientos activa o modo deportivo o eco predeterminado; son interruptores específicos que la máquina ejecuta directamente. El manual es "lo que le explicas a Codex", los mandos son "las acciones que le impones".
El formato del archivo es TOML (Tom's Obvious Minimal Language, un formato de configuración diseñado para ser fácil de leer y escribir) y se estructura con variables key = value a nivel de raíz y grupos definidos con [nombre_de_tabla]. Veamos un vistazo rápido:
# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"La documentación oficial lo define de forma muy directa:
Codex stores user-level configuration at
~/.codex/config.toml. Codex almacena la configuración a nivel de usuario en~/.codex/config.toml.
En las situaciones reales a las que te enfrentarás, config.toml gestiona lo siguiente:
- "Quiero usar siempre un modelo específico sin tener que cambiarlo manualmente": escribe
model - "En esta máquina quiero permisos de escritura en el espacio de trabajo por defecto y alertas al salir de límites": escribe
sandbox_mode+approval_policy - "Quiero búsquedas web en tiempo real, no con caché": escribe
web_search - "Quiero activar o desactivar una función experimental": escribe
[features]
Estas directrices no son "explicaciones para Codex", sino mandos que modifican físicamente su comportamiento. Esta es la diferencia fundamental de funciones entre config.toml y AGENTS.md.
💡 Resumen en una frase:
AGENTS.mdcontiene las directrices en lenguaje natural para Codex;config.tomlrepresenta los interruptores físicos del comportamiento del sistema; el primero gestiona el contexto de memoria, y el segundo la ejecución; no los mezcles.
02 Dónde se ubican los archivos: uno a nivel de usuario y otro a nivel de proyecto
Lo primero que debes comprender sobre config.toml no son sus variables, sino que se guarda en dos ubicaciones posibles: un archivo en tu directorio principal (global) y otro dentro del proyecto (específico para esa tarea). La trampa descrita al inicio se debió a no distinguir estas dos ubicaciones.
Analogía: El cuadro eléctrico general frente al interruptor de la habitación. Tu casa cuenta con un cuadro general (habitualmente en la entrada) que define los valores por defecto de la vivienda: por ejemplo, "limitar la potencia general por la noche". Cada habitación tiene además su propio interruptor en la pared que solo controla la luz de ese cuarto y con mayor prioridad: si quieres encender la luz del estudio, usas el de su pared sin alterar el resto de la casa. config.toml funciona en estas dos capas: el archivo del directorio principal es el cuadro general (aplica a todos los proyectos), y el del proyecto es el interruptor del cuarto (específico para ese proyecto con mayor prioridad).
La documentación oficial detalla las siguientes ubicaciones:
| Nivel | Ubicación del archivo | Alcance | Qué incluir | Requisito |
|---|---|---|---|---|
| Usuario (User) | ~/.codex/config.toml | Afecta a todos tus proyectos | Preferencias personales: modelo habitual, perfiles de permisos, servidores MCP, notificaciones | Ninguno |
| Proyecto (Project) | <repo>/.codex/config.toml | Solo al trabajar en este repositorio | Específico del proyecto: modelo deseado, modo de sandbox adecuado | Requiere confiar en el proyecto para cargarse |
Hay tres puntos que los principiantes deben memorizar:
Primero: La ruta del archivo del directorio principal es fija: ~/.codex/config.toml. El directorio ~/.codex se denomina CODEX_HOME y almacena todos los recursos locales del sistema (configuraciones, credenciales de inicio de sesión, historiales, registros), ubicándose por defecto en tu directorio de usuario. Si el archivo no existe créalo tú mismo, Codex lo detectará.
Segundo: El archivo a nivel de proyecto debe guardarse en el subdirectorio .codex/ del repositorio (nota que es .codex/config.toml, una carpeta oculta con punto inicial, con el mismo nombre pero diferente ubicación que ~/.codex del usuario). Se aplicará únicamente al trabajar en ese proyecto.
Tercero (muy fácil de omitir): la configuración a nivel de proyecto solo se carga si "se confía en el proyecto". Este es un diseño de seguridad de Codex para evitar que, al clonar un repositorio desconocido, su archivo .codex/config.toml intente elevar permisos de forma encubierta. La explicación oficial es directa:
If you mark a project as untrusted, Codex skips project-scoped
.codex/layers, including project-local config, hooks, and rules. Si marcas un proyecto como no confiable, Codex omitirá las capas del directorio.codex/a nivel de proyecto, incluyendo la configuración local del proyecto, hooks y reglas.
En la práctica, esto significa que si escribes un archivo .codex/config.toml en un proyecto no confiable, ninguna línea se aplicará, aunque el archivo de tu directorio de usuario se cargará con normalidad. Si configuras la opción del proyecto por primera vez y ves que no responde, comprueba si has aceptado confiar en el proyecto (la alerta que muestra Codex la primera vez que accedes).
Cómo clasificarlas en la práctica: dónde guardar cada opción
Para decidir si guardar una opción en el directorio principal o en el del proyecto, solo debes hacerte una pregunta: "¿esta opción se asocia con mis hábitos personales o con este proyecto específico?"
- "Quiero aplicarlo a todos mis proyectos" → Nivel de usuario (
~/.codex/config.toml). Por ejemplo, "quiero usargpt-5.5por defecto", "mis servidores MCP" o "los scripts de notificaciones de escritorio"; defínelo una vez y estará activo en cualquier proyecto. - "Aplica solo a este proyecto" → Nivel de proyecto (
<repo>/.codex/config.toml). Por ejemplo, "este proyecto heredado requiere un modelo específico" o "este proyecto debe restringirse a solo lectura". Se almacena en el repositorio y tus compañeros obtendrán la misma configuración al clonarlo (siempre que acepten confiar en el proyecto).
Mi método es sencillo: defino mis hábitos en el directorio de usuario y mantengo vacíos por lo general los archivos del proyecto; solo en repositorios específicos con requerimientos estrictos (como una base de código de un cliente donde solo permito lectura y prohíbo escrituras) añado la línea sandbox_mode = "read-only" en su archivo .codex/config.toml. Esto evita cambiar el sandbox manualmente en cada ocasión sin arrastrar la restricción a los demás proyectos.
💡 Resumen en una frase: Configuración de usuario en
~/.codex/config.toml(dentro deCODEX_HOME, aplica a todos los proyectos) y de proyecto en<repo>/.codex/config.toml(aplica solo al repositorio activo y requiere confiar en el proyecto para cargarse); la pauta es decidir si se asocia a tus hábitos o a la tarea.
03 Quién sobrescribe a quién: prioridad de carga y una restricción de seguridad clave
Como es posible definir la misma variable en ambas partes, surge la duda: si el usuario define gpt-5.5 y el proyecto otra opción, ¿cuál prevalece? Esto es lo que regula la prioridad de carga y suele causar confusión en config.toml.
En la práctica existen más de dos niveles: al incorporar parámetros de consola, perfiles elegidos con --profile (perfiles de configuración nombrados) y configuraciones del sistema, se superponen hasta seis capas. La jerarquía completa oficial de mayor a menor prioridad es la siguiente:
| Prioridad | Origen | Significado |
|---|---|---|
| 1 (Más alta) | Parámetros de consola / --config | Definido para la ejecución actual, aplica solo a esta sesión |
| 2 | Nivel de proyecto <repo>/.codex/config.toml | Configuración del proyecto (si es confiable, de la raíz al directorio activo, el más cercano prevalece) |
| 3 | Perfil seleccionado con --profile ~/.codex/<nombre>.config.toml | El archivo de configuración de perfil al que cambiaste |
| 4 | Nivel de usuario ~/.codex/config.toml | Tus valores por defecto globales |
| 5 | Nivel de sistema /etc/codex/config.toml (en Unix, si existe) | Definido por el administrador para toda la máquina |
| 6 (Más baja) | Valores por defecto integrados | La configuración por defecto interna de Codex |
Esta jerarquía de mayor a menor prioridad se ilustra en el siguiente diagrama (los niveles superiores sobrescriben a los inferiores si definen la misma variable):
Este diagrama apila los seis niveles de configuración de mayor a menor prioridad: el nivel superior "parámetros de consola / --config" es el más específico y tiene preferencia sobre todos, seguido en orden por el nivel de proyecto, el perfil seleccionado con --profile, el nivel de usuario, el de sistema y, finalmente, los valores integrados por defecto; las capas superiores sobrescriben los valores definidos en las inferiores si coinciden las variables, por lo que prevalece la opción más cercana a la ejecución actual.
Memoriza la jerarquía con esta regla: prevalece el valor más específico frente a los valores globales. Los parámetros de consola (esta ejecución) tienen preferencia sobre el proyecto (este repositorio), el proyecto sobre el perfil, el perfil sobre el usuario, el usuario sobre el sistema y el sistema sobre los valores por defecto integrados. La recomendación oficial detalla:
Use that precedence to set shared defaults in
config.tomland keep profile files focused on the values that differ. Utiliza esta jerarquía para definir valores compartidos enconfig.tomly mantén los archivos de perfil enfocados solo en las variables que difieran.
En resumen: el directorio de usuario define tu comportamiento habitual, el perfil especifica diferencias temporales y la consola de comandos gestiona casos excepcionales. Esto responde al pequeño pensamiento del capítulo anterior: para que una preferencia se aplique por defecto en cada inicio, escríbela en el config.toml de usuario.
La restricción clave de seguridad: ciertas variables se ignorarán a nivel de proyecto
Mencionamos que el nivel de proyecto sobrescribe al de usuario. Sin embargo, algunas variables son una excepción: si las escribes en el .codex/config.toml de proyecto, Codex las ignorará por completo mostrando una alerta al iniciar. Esta es una medida de protección de seguridad predeterminada y es muy común cometer este error al principio.
¿Por qué se bloquean? Piénsalo: si un repositorio desconocido pudiera modificar en su .codex/config.toml la dirección del proveedor de modelo, cambiar el método de autenticación o inyectar comandos de notificación en tu máquina, el riesgo sería muy alto. Por tanto, las variables que "alteran la seguridad a nivel de sistema" se restringen estrictamente al nivel de usuario. La documentación oficial detalla:
Codex ignores
openai_base_url,chatgpt_base_url,apps_mcp_product_sku,model_provider,model_providers,notify,profile,profiles,experimental_realtime_ws_base_url, andotelwhen they appear in a project-local.codex/config.toml. Codex ignoraopenai_base_url,chatgpt_base_url,apps_mcp_product_sku,model_provider,model_providers,notify,profile,profiles,experimental_realtime_ws_base_urlyotelcuando se definen en un archivo.codex/config.tomllocal del proyecto.
En lenguaje sencillo, las siguientes variables se ignorarán a nivel de proyecto debiendo guardarse a nivel de usuario:
| Tipo de variable | Propósito | Motivo de restricción al nivel de usuario |
|---|---|---|
model_provider / model_providers | Proveedor y ruta de conexión del modelo | Evita que un repositorio desconocido redirija tus peticiones web |
openai_base_url / chatgpt_base_url | URL base del servicio integrado | Similar al caso anterior, alterar la URL compromete el destino de datos |
notify | Comandos externos a ejecutar tras completar tareas | Evita que el repositorio ejecute scripts silenciosamente en tu sistema |
otel | Telemetría y exportación de registros | Evita la transmisión silenciosa de datos de ejecución |
profile / profiles | Seleccionar la preconfiguración del perfil | Los perfiles se definen en consola con --profile, impidiendo que el repositorio los asigne por ti |
Recuerda la regla: variables de sistema como el proveedor del modelo, notificaciones, telemetría o selección de perfiles se definen en el directorio de usuario; a nivel de proyecto solo configuras model, sandbox_mode o approval_policy que regulan la ejecución local. Si agregas model_providers a nivel de proyecto y no funciona, no es un error de sintaxis; ha sido bloqueado deliberadamente.
💡 Resumen en una frase: La jerarquía se rige por "el valor más cercano a la ejecución prevalece" (consola > proyecto > perfil > usuario > sistema > por defecto); ten en cuenta que el nivel de proyecto ignora variables de sistema como
model_provider,notify,oteloprofile, requiriendo guardarlas a nivel de usuario.
04 Variables más habituales: propósitos y valores por defecto
Una vez comprendidos los niveles y prioridades, veamos las variables que modificarás con mayor frecuencia. Existen decenas de claves compatibles oficialmente (listadas en la Config Reference oficial), pero la gran mayoría utiliza solo este conjunto. Detallamos su función y valor predeterminado; conocer los valores por defecto te ayuda a saber qué variables no requieres escribir:
| Clave | Función | Valor por defecto | Ejemplo de sintaxis |
|---|---|---|---|
model | Modelo a utilizar por defecto | Definido por el sistema Codex | model = "gpt-5.5" |
approval_policy | Cuándo solicitar confirmación manual | on-request | approval_policy = "on-request" |
sandbox_mode | Límites de modificación (archivos y red) | workspace-write (en repositorios Git, ver nota) | sandbox_mode = "workspace-write" |
model_reasoning_effort | Esfuerzo de razonamiento del modelo | Según modelo o preajuste | model_reasoning_effort = "high" |
web_search | Modo de búsqueda en la red | cached (con caché) | web_search = "live" |
personality | Estilo de conversación del modelo | friendly (valor de ejemplo) | personality = "pragmatic" |
file_opener | Editor para abrir archivos al hacer clic en enlaces | vscode | file_opener = "cursor" |
Nota aclaratoria sobre el valor por defecto de
sandbox_mode: ejecutarcodexdirectamente aplica la preconfiguración Auto: es escribible (workspace-write) en repositorios Git por defecto, y de solo lectura (read-only) en directorios sin control de versiones. El valorworkspace-writese define en la documentación oficial como "el modo de sandbox por defecto" haciendo referencia a repositorios Git convencionales.
Detallemos algunos aspectos clave sobre cada opción:
model / model_reasoning_effort / approval_policy / sandbox_mode
Estas cuatro variables son las principales pero ya las explicamos en capítulos anteriores: la elección de modelos en el artículo 05 · Modelos de terceros y la estrategia de aprobación (approval_policy) junto con el sandbox (sandbox_mode) en el artículo 15 · Permisos, sandbox y aprobaciones. Aquí basta con recordar: todas cuentan con su clave correspondiente en config.toml y definirlas guarda el comportamiento por defecto, evitando tener que cambiarlas en consola con /model o --sandbox.
La opción model_reasoning_effort define la intensidad de razonamiento; los niveles oficiales son minimal | low | medium | high | xhigh (si el modelo lo admite). Elige un nivel bajo para tareas sencillas para ahorrar tiempo y saldo, y high ante tareas complejas.
web_search: búsqueda web, con caché por defecto en lugar de tiempo real
Esta variable tiene un valor predeterminado contraintuitivo. Codex habilita la búsqueda web por defecto pero usa el modo cached (con caché): consulta un índice de páginas de OpenAI para devolver resultados recopilados previamente en lugar de cargar páginas web en vivo. Se diseña así para reducir los riesgos de inyección de prompts, ya que el contenido de caché es más seguro que las páginas reales.
En una ocasión pedí a Codex buscar "el número de versión más reciente de cierta librería" y devolvió un valor desactualizado; tras investigar descubrí que usaba el índice antiguo del modo de caché. Para búsquedas en tiempo real debes indicarlo explícitamente:
web_search = "live" # 实时抓取，等价于命令行 --search
# web_search = "cached" # 默认：走缓存索引
# web_search = "disabled" # 彻底关掉搜索工具Una excepción a tener en cuenta: si utilizas --yolo o el acceso completo en el sandbox, web_search cambiará automáticamente a live.
personality: cambiar el estilo de conversación de Codex
La opción personality ajusta la personalidad; las opciones oficiales son none | friendly | pragmatic (amistosa o práctica). Se puede alternar temporalmente en el chat con /personality. Personalmente uso pragmatic para obtener respuestas directas sin rodeos.
file_opener: hacer clic en enlaces de archivos
Las respuestas de Codex suelen incluir referencias como archivo.py:42. La variable file_opener define qué editor abrir al hacer clic, con opciones como vscode por defecto, vscode-insiders | windsurf | cursor | none. Si utilizas Cursor cámbialo a cursor para que las referencias sean enlaces clicables que abran el archivo en la línea correspondiente.
Un detalle de TOML: las variables raíz deben preceder a las tablas
Este es el error de sintaxis más común al escribir en config.toml. Las reglas de TOML determinan: todas las variables key = value a nivel de raíz deben preceder a las declaraciones de [tabla]. La documentación oficial lo advierte en los comentarios del archivo de ejemplo:
Root keys must appear before tables in TOML. Las variables raíz deben declararse antes de las tablas en TOML.
Compara las estructuras:
| ❌ Incorrecto (variables raíz declaradas después de una tabla) | ✅ Correcto (variables raíz antes de la tabla) |
|---|---|
[features]hooks = truemodel = "gpt-5.5" ← Error | model = "gpt-5.5"[features]hooks = true |
Regla práctica: escribe primero todas las variables simples sin corchetes (model, approval_policy...) y añade las tablas [tabla] después. Alterar el orden provocará fallos en el analizador de TOML con alertas difíciles de interpretar.
💡 Resumen en una frase: Las variables habituales son
model,approval_policy,sandbox_mode,model_reasoning_effort,web_search(con caché por defecto en lugar de tiempo real),personalityyfile_opener; no requieres definirlas si usas sus valores por defecto, y recuerda que en TOML las variables simples deben preceder a las tablas.
05 [features]: panel de control de funciones opcionales y experimentales
Detallemos la tabla [features], que actúa como panel de control para habilitar o deshabilitar las funciones experimentales u opcionales. Las herramientas de memoria, hooks o colaboración de agentes que explicamos anteriormente se controlan aquí.
Analogía: Las opciones de desarrollo o laboratorio en los ajustes del móvil. Las funciones estables vienen activas de fábrica, pero se ofrece un menú de "laboratorio" con interruptores manuales que activan o desactivan las novedades. La sección [features] es el laboratorio de Codex: ofrece variables booleanas para cada función, asignando true para activar, false para desactivar o respetando los valores predeterminados del sistema al omitirse.
Se declara como una tabla [features] con las variables correspondiente debajo:
[features]
memories = true # 开启 Memory（记忆）
shell_snapshot = true # 快照 shell 环境、加速重复命令
hooks = false # 关掉生命周期 hooksDetallemos los interruptores de funciones habituales (sus valores por defecto se rigen por la documentación oficial):
| Variable | Por defecto | Estado | Función |
|---|---|---|---|
hooks | true | Estable | Hooks de ciclo de vida (scripts disparados por eventos) |
multi_agent | true | Estable | Herramienta de colaboración de subagentes |
shell_snapshot | true | Estable | Capturas del entorno de consola para hacer los comandos repetidos más rápidos |
fast_mode | true | Estable | Modo de respuesta rápida (ahorra tiempos de espera) |
shell_tool | true | Estable | Herramienta de consola integrada (para ejecutar comandos) |
personality | true | Estable | Controles de selección del estilo de comunicación |
memories | false | Estable | Memoria del agente (se detalla en el artículo 19) |
codex_git_commit | false | Experimental | Generación automática de mensajes de commit de Git |
apps | false | Experimental | Soporte para ChatGPT Apps y conectores |
undo | false | Estable | Historial rápido con git ghost para admitir deshacer cambios |
Un error habitual: las sintaxis antiguas (como usar codex_hooks = true en [features]) se han quedado obsoletas; el estándar oficial es hooks, y codex_hooks se conserva solo como alias en desuso. Usa los nombres de variables oficiales actualizados en lugar de guías desfasadas.
Se ofrecen tres métodos de configuración oficiales:
- En
config.toml: añadenombre_de_variable = true(ofalse) bajo la tabla[features]. - Temporalmente en consola: usa
codex --enable nombre_de_variable, o acumula perfiles con--enable a --enable b. - Desactivar: cambia la variable correspondiente a
falseen[features].
Recomendación: evita activar todas las opciones experimentales si eres principiante. Si deseas probar la memoria (explicada en el artículo 19) usa memories = true y mantén el resto por defecto. Habilitar demasiadas funciones experimentales dificulta el diagnóstico ante fallos del sistema.
💡 Resumen en una frase: La tabla
[features]gestiona las funciones opcionales mediante variables booleanas (true/falsepara cambiar y omitir para usar sus valores por defecto comohooksomulti_agentactivos ymemoriesinactivo por defecto); se puede activar en consola con--enableusando siempre los nombres de variables actualizados.
06 Modificación temporal frente a cambiar perfiles completos: -c y --profile
Existen dos necesidades que no se resuelven puramente escribiendo en config.toml: querer modificar una variable para la ejecución actual y restaurarla después, o bien contar con diferentes perfiles de configuración para alternar. Codex ofrece herramientas para ambos casos:
Modificación temporal: -c / --config (sin alterar el archivo)
Para probar un parámetro sin editar los archivos de configuración, aplícalo directamente en consola:
# 优先用专属 flag（有的话）
codex --model gpt-5.4
# 没有专属 flag 的键，用 -c / --config 通用覆盖（值是 TOML 写法，不是 JSON）
codex --config model='"gpt-5.4"'
codex -c log_dir=./.codex-logHay dos detalles donde es fácil cometer errores de suposición:
- El valor de
-cse analiza como TOML, no como JSON. Por tanto, los valores de cadena de texto requieren comillas internas (comomodel='"gpt-5.4"'con comillas simples para la consola y comillas dobles para TOML); encierra el bloque si tienes dudas para evitar que la consola lo divida por espacios. - Las variables anidadas se enlazan con punto: por ejemplo,
codex -c mcp_servers.context7.enabled=false.
Este recurso es ideal para probar parámetros temporales: si funciona lo guardas en el archivo y, si no, simplemente cierras la sesión conservando la configuración original intacta.
Cambiar perfiles completos: --profile (perfiles de configuración)
El concepto de profile se describió en el artículo 15; completemos su funcionamiento. Un perfil de configuración es un archivo separado guardado en CODEX_HOME con el formato <nombre_de_perfil>.config.toml:
# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"Selecciónalo con --profile:
codex --profile deep-review
codex exec --profile deep-review "review this change"El funcionamiento: Codex lee primero tu configuración de usuario en ~/.codex/config.toml y luego superpone el archivo ~/.codex/deep-review.config.toml. Por tanto, el archivo de perfil solo requiere especificar las variables que difieran de tu configuración base, omitiendo el resto.
Un detalle a tener en cuenta sobre cambios de versión:
⚠️ Cambios de versión según la documentación oficial. A partir de Codex 0.134.0, la opción
--profileya no carga bloques del tipo[profiles.nombre]declarados enconfig.toml, y la clave de raízprofile = "nombre"ha dejado de ser compatible. Debes migrar el contenido de los bloques antiguos[profiles.x]a archivos independientes~/.codex/x.config.toml. Comprueba tu versión de uso y la documentación oficial para confirmar el comportamiento.
Personalmente utilizo dos perfiles: quick (modelo ligero y solo lectura para revisar código) y build (modelo avanzado y escritura habilitada para tareas pesadas). Ejecutar codex --profile build aplica todas las preferencias al instante, evitando cambiar variables individualmente; es la solución ideal a los problemas de configuración del inicio.
💡 Resumen en una frase: Para cambios temporales usa
-c key=value(analizado como TOML, con comillas para texto y punto para variables anidadas) sin alterar archivos; para perfiles completos, guarda las diferencias en~/.codex/<nombre>.config.tomle invoca con--profile <nombre>, teniendo en cuenta que la sintaxis[profiles.x]ya no se admite a partir de 0.134.0.
07 Manos a la obra: guardar configuración, sobrescribir temporalmente y alternar perfiles
La teoría sin práctica no sirve. Recorreremos la secuencia completa de "guardar archivo → sobrescribir en consola → alternar perfiles". Utilizaremos un caso mínimo sin dependencias. Los comandos siguen las directrices oficiales, y empleamos el modelo de ejemplo gpt-5.5 que debes sustituir por tu modelo de uso real.
Primer paso: Comprobar la ubicación de tu archivo de configuración de usuario (en la consola)
ls -la ~/.codex/config.tomlResultado esperado: se muestra el archivo o alerta de que no existe. Si no existe lo crearemos en el siguiente paso.
Segundo paso: Escribir una configuración de usuario básica
Copia el siguiente bloque en ~/.codex/config.toml (asegúrate de colocar las variables de raíz antes de la tabla [features]):
# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
web_search = "cached"
[features]
memories = falseResultado esperado: tras guardar el archivo, este define tus valores por defecto globales. Lo comprobaremos en el siguiente paso.
Tercer paso: Iniciar la sesión y comprobar la configuración con /status
codexEscribe durante la sesión:
/statusResultado esperado: la información de estado en la pantalla muestra el modelo activo y la estrategia de aprobación, coincidiendo con los parámetros que acabas de guardar; esto demuestra que config.toml se ha cargado con éxito. (El comando /status se describió en el artículo 12 para revisar el estado del sistema).
Cuarto paso: Sobrescribir una variable temporalmente con -c sin editar el archivo
Sal de la sesión y arranca Codex forzando la búsqueda web en tiempo real:
codex -c web_search='"live"'Escribe /status nuevamente durante la sesión.
Resultado esperado: el modo de búsqueda figura como live para esta sesión, pero la variable web_search = "cached" de tu archivo permanece intacta. Sal e inicia codex de forma convencional y volverá a figurar como cached. Este comportamiento temporal confirma la regla de la sección 06: los parámetros de consola sobrescriben a los archivos y aplican solo a esta ejecución.
Quinto paso: Crear un perfil de configuración para alternar parámetros
Crea el archivo ~/.codex/quick.config.toml especificando solo las diferencias con tu configuración base:
# ~/.codex/quick.config.toml
model = "gpt-5.5"
sandbox_mode = "read-only"
approval_policy = "untrusted"Inicia la sesión invocando el perfil:
codex --profile quickEscribe /status para comprobar.
Resultado esperado: el sandbox figura como read-only y la aprobación como untrusted (más restrictivos que tu archivo base) debido a que el perfil superpone sus valores a los del usuario. La aplicación de esta configuración restrictiva confirma el funcionamiento de la sección 06: los perfiles se guardan como archivos separados e invocan con --profile. Iniciar de forma convencional sin el parámetro volverá a aplicar tus opciones de usuario.
Al completar estos cinco pasos habrás verificado de forma práctica el funcionamiento básico de config.toml: definir valores por defecto en archivos, comprobar la carga con /status, aplicar cambios temporales con -c y alternar perfiles completos con --profile; el comportamiento es idéntico para cualquier otra variable.
💡 Resumen en una frase: Prueba la secuencia: escribir configuración de usuario → comprobar carga con
/status→ sobrescribir con-csin editar el archivo → alternar perfiles con--profile; completar estos pasos consolida los conceptos de valores por defecto, cambios temporales y perfiles.
08 Resumen
En este artículo hemos revisado los interruptores de config.toml: su naturaleza, ubicaciones de guardado, prioridades de carga, variables habituales y cómo sobrescribir o alternar perfiles, consolidando la gestión de la configuración.
Repasemos los puntos clave consolidados:
| Objetivo | Detalle | Noción clave |
|---|---|---|
| Relación con AGENTS.md | Son sistemas distintos | AGENTS.md gestiona el contexto de memoria; config.toml la ejecución |
| Ubicaciones del archivo | Dos opciones | Nivel de usuario (~/.codex/config.toml) y nivel de proyecto (.codex/config.toml, requiere confianza) |
| Prioridad ante conflictos | El más específico prevalece | Consola > proyecto > perfil > usuario > sistema > por defecto |
| Restricciones de seguridad | Áreas restringidas en el proyecto | Claves de sistema como model_provider, notify, otel o profile solo se admiten en el usuario |
| Variables habituales | Claves principales | model, approval_policy, sandbox_mode, web_search (con caché por defecto) y [features] |
| Cambios temporales / perfiles | -c y --profile | -c modifica de forma temporal; --profile aplica perfiles de configuración separados |
Ahora deberías ser capaz de: distinguir las funciones de config.toml y AGENTS.md; decidir si guardar una opción a nivel de usuario o de proyecto; evaluar la jerarquía de prioridad de seis niveles y la restricción de variables del sistema en proyectos; reconocer las variables habituales como model, approval_policy, sandbox_mode, web_search o [features] con sus valores por defecto; y sobrescribir temporalmente con -c o alternar perfiles con --profile. Esta capacidad de control centralizado te permite adaptar Codex a tus hábitos de desarrollo desde el inicio.
Los inconvenientes de configuración del inicio se resumen en un punto: no haber guardado en config.toml las preferencias que solo se configuran una vez. Tras este capítulo, evitarás pasos repetidos: cuando veas que aplicas los mismos parámetros constantemente, detente y evalúa si conviene escribirlos en la configuración de usuario o de proyecto.
El próximo artículo 19 · El sistema de memoria (Memories y Chronicle): viste la variable memories desactivada por defecto en la tabla [features], ¿lo recuerdas? En el siguiente capítulo explicaremos: cómo permitir que Codex "recuerde" tus hábitos de desarrollo y la estructura de tu proyecto, pasando de actuar como un asistente nuevo en cada sesión a un compañero con contexto compartido. Un pequeño pensamiento: el capítulo anterior le dio "ojos para ver la pantalla", y este le otorgará "cerebro para recordar"; ¿qué diferencia hay entre un asistente visual con memoria y la herramienta que usas actualmente?