Configuración básica

Codex lee la configuración desde varias ubicaciones. Tus valores predeterminados se guardan en ~/.codex/config.toml y puedes sobrescribirlos para cada proyecto mediante archivos .codex/config.toml. Por seguridad, Codex solo carga las capas de configuración del proyecto en .codex/ si confías en el proyecto.

Archivo de configuración de Codex

Codex guarda la configuración del usuario en ~/.codex/config.toml. Para aplicar ajustes a un proyecto o una subcarpeta en particular, agrega un archivo .codex/config.toml en tu repositorio.

Para abrir el archivo de configuración desde la extensión de Codex para el IDE, selecciona el ícono de engranaje en la esquina superior derecha y luego Configuración de Codex > Abrir config.toml.

La CLI y la extensión para el IDE comparten las mismas capas de configuración. Puedes usarlas para:

• Establecer el modelo y el proveedor predeterminados.
• Configurar las políticas de aprobación y los ajustes del sandbox.
• Configurar servidores MCP.

Orden de prioridad de la configuración

Los requisitos limitan el comportamiento y los valores de configuración establecen los ajustes predeterminados. El acceso a la computadora local con Work Cloud se rige por los siguientes requisitos:

• Entre políticas: una política de mayor prioridad prevalece sobre otra de menor prioridad, incluso si esta última es más específica.
• Dentro de una misma política: los ajustes de entorno específicos de un sistema operativo tienen prioridad sobre los que se aplican a todos los sistemas operativos. La configuración Global ocupa el último lugar.
• Para la ejecución local: los requisitos de MDM y los requisitos heredados para dispositivos administrados tienen prioridad sobre Agent Security. El archivo de requisitos del sistema del dispositivo tiene menor prioridad que Agent Security.
• Para Work Cloud: los contenedores del modo Work en la nube conservan las políticas vigentes de Work Cloud. En el modo Work con acceso local y dots, la política Global compatible rige el orquestador compartido en la nube cuando la política administrada está habilitada. La computadora conectada se rige por los requisitos de ejecución local que correspondan.

Algunos requisitos tienen reglas de combinación específicas para cada campo. Consulta Configuración administrada para conocer el alcance de las políticas y los límites de ejecución, y la Referencia de configuración para consultar la compatibilidad con el modo Work.

Codex determina los valores en este orden, de mayor a menor prioridad:

1. Opciones de la CLI y valores especificados con --config
2. Archivos de configuración del proyecto: .codex/config.toml, desde la raíz del proyecto hasta tu directorio de trabajo actual (prevalece el más cercano al directorio actual y solo se tienen en cuenta los proyectos de confianza)
3. Archivos de perfil seleccionados con --profile profile-name (~/.codex/profile-name.config.toml)
4. Configuración del usuario: ~/.codex/config.toml
5. Valores predeterminados de config.toml administrados en la nube, si se proporcionan para el Espacio de trabajo en el que iniciaste sesión
6. Configuración del sistema (si existe): /etc/codex/config.toml en Unix
7. Valores predeterminados integrados

Aprovecha este orden de prioridad para establecer valores predeterminados compartidos en config.toml e incluir en los archivos de perfil solo los valores que difieran.

Tanto la configuración administrada en la nube como la del sistema permiten definir marketplaces de complementos y determinar si los complementos se habilitan de forma predeterminada. Estos ajustes son independientes de las políticas obligatorias de requirements.toml. Consulta Configurar los marketplaces de complementos y sus valores predeterminados.

Si marcas un proyecto como no confiable, Codex omite las capas de .codex/ propias del proyecto, incluidos la configuración, los hooks y las reglas locales del proyecto. Codex sigue cargando la configuración del usuario y la del sistema, incluidos los hooks y las reglas de usuario y globales.

Para sobrescribir valores en una sola ejecución con -c/--config y conocer las reglas de uso de comillas en TOML, consulta Configuración avanzada.

Opciones de configuración habituales

Estas son algunas de las opciones que se modifican con más frecuencia:

Modelo predeterminado

Elige el modelo que Codex usa de forma predeterminada en la CLI y en el IDE.

model = "gpt-6.1-sol"

Solicitudes de aprobación

Controla cuándo Codex se detiene para solicitar aprobación antes de ejecutar los comandos que genera.

approval_policy = "on-request"

Para conocer las diferencias de comportamiento entre on-request y never, consulta Ejecutar sin solicitudes de aprobación y Combinaciones habituales de sandbox y aprobación. Si una configuración existente usa approval_policy = "untrusted", consulta Migrar desde la política de aprobación untrusted, ya retirada.

Nivel de sandbox

Ajusta el nivel de acceso de Codex al sistema de archivos y a la red durante la ejecución de comandos.

sandbox_mode = "workspace-write"

Para conocer el comportamiento de cada modo, incluidas las rutas protegidas .git, .agents, .codex y .aws y la configuración de red predeterminada, consulta Sandbox y aprobaciones, Rutas protegidas en directorios raíz con permisos de escritura y Acceso a la red.

Perfiles de permisos

Codex también admite perfiles de permisos con nombre para reutilizar políticas de acceso al sistema de archivos y a la red. Los perfiles integrados son :read-only, :workspace y :danger-full-access. Los perfiles personalizados usan tablas [permissions.<name>] y un valor de default_permissions que coincide con el nombre del perfil. Consulta Permisos.

Modo de sandbox en Windows

En Windows, usa preferentemente MXC si el dispositivo y la política lo admiten. Configura una implementación heredada como alternativa:

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

Usa unelevated solo si la configuración con privilegios elevados no está disponible y la política de tu organización lo permite. Consulta la guía del sandbox de Windows para conocer los límites de compatibilidad y los controles de despliegue.

Modo de búsqueda web

Codex habilita la búsqueda web de forma predeterminada en los chats locales y devuelve resultados de una caché de búsqueda web. La caché es un índice de resultados web que mantiene OpenAI, por lo que el modo de caché devuelve resultados ya indexados en lugar de consultar las páginas en tiempo real. Esto reduce la exposición a la inyección de prompts procedente de contenido arbitrario consultado en tiempo real. Trata los resultados web como contenido no confiable. Si usas --yolo u otra configuración del sandbox con acceso completo, la búsqueda web devuelve resultados en tiempo real de forma predeterminada. Elige un modo con web_search:

• "cached" (predeterminado) devuelve resultados de la caché de búsqueda web.
• "indexed" permite el acceso externo a la web solo si el índice de búsqueda autoriza la solicitud.
• "live" obtiene los datos más recientes de la web (equivale a --search).
• "disabled" desactiva la herramienta de búsqueda web.

web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

Esfuerzo de razonamiento

Ajusta el esfuerzo de razonamiento que emplea el modelo si admite esta opción.

model_reasoning_effort = "medium"

Estilo de comunicación

Para omitir las instrucciones de personalidad integradas, usa este ajuste:

personality = "none"

Este ajuste elimina la sección Personality de las instrucciones integradas del modelo. Las instrucciones base personalizadas que hayas definido explícitamente se mantienen. Los valores anteriores friendly y pragmatic ya no permiten seleccionar un estilo. Codex ya no ofrece el comando /personality.

Atajos de teclado de la TUI

Personaliza los atajos de la terminal en tui.keymap. Algunas acciones del editor usan los atajos correspondientes de tui.keymap.global como alternativa. Los atajos específicos del contexto tienen prioridad cuando se admiten. Una lista vacía elimina los atajos asignados a la acción.

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

Entorno de los comandos

Controla qué variables de entorno pasa Codex a los comandos que inicia. Usa filtros por clave para conservar solo las variables que necesitas:

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

El valor predeterminado de ignore_default_excludes es true, por lo que se omite el filtrado automático de variables cuyos nombres contienen KEY, SECRET o TOKEN. Establécelo en false si quieres aplicar ese filtro. Para conocer las reglas de exclusión, el orden de prioridad y la configuración heredada, consulta Política del entorno de shell.

Directorio de registros

Cambia la ubicación donde Codex escribe los archivos de registro locales. Si defines log_dir explícitamente, también habilitas en ese directorio el registro opcional de la TUI en texto plano, codex-tui.log.

log_dir = "/absolute/path/to/codex-logs"

También puedes definir el directorio desde la CLI para una sola ejecución:

codex -c log_dir=./.codex-log

Opciones de activación de funciones

Usa la tabla [features] de config.toml para activar o desactivar funciones opcionales y experimentales.

Opciones habituales de activación de funciones

Para configurar los hooks del ciclo de vida, consulta Hooks.

Activar funciones

• En config.toml, agrega feature_name = true en la sección [features].
• Desde la CLI, ejecuta codex --enable feature_name.
• Para activar más de una función, ejecuta codex --enable feature_a --enable feature_b.
• Para desactivar una función, establece su clave en false en config.toml.