Conceptos básicos de configuración

Codex lee los detalles de configuración desde más de una ubicación. Tus valores predeterminados personales se encuentran en ~/.codex/config.toml, y puedes añadir anulaciones de proyecto mediante archivos .codex/config.toml. Por seguridad, Codex solo carga las capas .codex/ del proyecto cuando confías en él.

Archivo de configuración de Codex

Codex almacena la configuración del usuario en ~/.codex/config.toml. Para limitar la configuración a un proyecto o una subcarpeta específicos, añade un archivo .codex/config.toml al repositorio.

Para abrir el archivo de configuración desde la extensión de Codex para IDE, selecciona el icono de engranaje de la esquina superior derecha y, a continuación, selecciona Codex Settings > Open config.toml.

La CLI y la extensión para 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 MCP servers.

Precedencia de la configuración

Los requisitos restringen el comportamiento; los valores de configuración proporcionan valores predeterminados. El acceso al equipo local con Work Cloud sigue estos requisitos:

• Entre políticas: Una política de mayor prioridad prevalece sobre una de menor prioridad, incluso cuando esta última es más específica.
• Dentro de una misma política: Las anulaciones de entorno específicas de un sistema operativo tienen prioridad sobre las aplicables a todos los sistemas operativos, seguidas de Global.
• Para la ejecución local: Los requisitos de MDM y los requisitos heredados de 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 de Work en la nube conservan las políticas existentes de Work Cloud. Para 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; los requisitos de ejecución local aplicables rigen el equipo conectado.

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 del entorno de ejecución, y la Referencia de configuración para conocer la compatibilidad con Work.

Codex resuelve los valores en este orden (primero los de mayor precedencia):

1. Opciones de CLI y ajustes mediante --config
2. Archivos de configuración del proyecto: .codex/config.toml, ordenados desde la raíz del proyecto hasta tu directorio de trabajo actual (prevalece el más cercano; solo para 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, cuando se proporcionan para el espacio de trabajo en el que has iniciado sesión
6. Configuración del sistema (si existe): /etc/codex/config.toml en Unix
7. Valores predeterminados integrados

Usa esa precedencia para establecer valores predeterminados compartidos en config.toml y mantener los archivos de perfil centrados en los valores que difieren.

La configuración administrada en la nube y la del sistema pueden definir mercados de plugins y establecer si los plugins están habilitados de forma predeterminada. Estas configuraciones son independientes de las políticas obligatorias de requirements.toml. Consulta Configurar mercados de plugins y valores predeterminados.

Si marcas un proyecto como no confiable, Codex omite las capas .codex/ específicas del proyecto, incluidas la configuración, los hooks y las reglas locales del proyecto. La configuración del usuario y del sistema sigue cargándose, incluidos los hooks y las reglas del usuario o globales.

Para anulaciones puntuales mediante -c/--config (incluidas las reglas de comillas de TOML), consulta Configuración avanzada.

Opciones de configuración habituales

Estas son algunas de las opciones que se cambian con mayor frecuencia:

Modelo predeterminado

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

model = "gpt-6.1-sol"

Solicitudes de aprobación

Controla cuándo Codex se detiene para pedir permiso antes de ejecutar comandos generados.

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 retirada untrusted.

Nivel del sandbox

Ajusta el nivel de acceso al sistema de archivos y a la red que tiene Codex al ejecutar comandos.

sandbox_mode = "workspace-write"

Para conocer el comportamiento de cada modo (incluidas las rutas protegidas .git, .agents, .codex y .aws y los valores predeterminados de red), 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 del sistema de archivos y de red. Los perfiles integrados son :read-only, :workspace y :danger-full-access. Los perfiles personalizados usan tablas [permissions.<name>] y un valor default_permissions correspondiente. Consulta Permisos.

Modo de sandbox de Windows

En Windows, da preferencia a MXC cuando el dispositivo y la política lo permitan. Configura una implementación heredada como alternativa:

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

Usa unelevated solo cuando la configuración con privilegios elevados no esté disponible y la política de tu organización lo permita. Consulta la guía del sandbox de Windows para conocer las limitaciones de compatibilidad y los controles de implementación gradual.

Modo de búsqueda web

Codex habilita la búsqueda web de forma predeterminada para los chats locales y proporciona resultados desde una caché de búsqueda web. La caché es un índice de resultados web mantenido por OpenAI, por lo que el modo en caché devuelve resultados previamente indexados en lugar de obtener páginas en tiempo real. Esto reduce la exposición a la inyección de instrucciones procedente de contenido arbitrario en tiempo real. Trata los resultados web como contenido no confiable. Si usas --yolo u otro ajuste de sandbox con acceso completo, la búsqueda web usa resultados en tiempo real de forma predeterminada. Elige un modo con web_search:

• "cached" (predeterminado) ofrece resultados desde la caché de búsqueda web.
• "indexed" permite el acceso externo a la web solo cuando el índice de búsqueda autoriza la solicitud.
• "live" obtiene los datos más recientes de la web (igual que --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 cuánto esfuerzo de razonamiento aplica el modelo cuando es compatible.

model_reasoning_effort = "medium"

Estilo de comunicación

Para omitir las instrucciones de personalidad integradas, establece:

personality = "none"

Esto elimina la sección Personality de las instrucciones integradas del modelo. No modifica las instrucciones base personalizadas explícitas. Los valores anteriores friendly y pragmatic ya no seleccionan un estilo. Codex ya no ofrece el comando /personality.

Mapa de teclas de la TUI

Personaliza los atajos del terminal en tui.keymap. Las acciones seleccionadas del redactor recurren a las vinculaciones tui.keymap.global correspondientes; las vinculaciones específicas del contexto tienen precedencia cuando son compatibles. Una lista vacía desvincula 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 comandos

Controla qué variables de entorno reenvía Codex a los comandos que inicia. Usa filtros con clave para conservar solo las variables que necesites:

[shell_environment_policy]
ignore_default_excludes = false

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

El valor predeterminado de ignore_default_excludes es true, lo que omite el filtrado automático de los nombres de variables que contienen KEY, SECRET o TOKEN. Establécelo en false cuando quieras aplicar ese filtrado automático. Para consultar las reglas de exclusión, la precedencia y la configuración heredada, consulta Política del entorno de shell.

Directorio de registros

Anula la ubicación donde Codex escribe los archivos de registro locales. Establecer log_dir explícitamente también habilita el registro de texto sin formato opcional de la TUI, codex-tui.log, en ese directorio.

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

Para ejecuciones puntuales, también puedes establecerlo desde la CLI:

codex -c log_dir=./.codex-log

Indicadores de funciones

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

Indicadores de funciones habituales

Para configurar hooks de ciclo de vida, consulta Hooks.

Habilitar funciones

• En config.toml, añade feature_name = true debajo de [features].
• Desde la CLI, ejecuta codex --enable feature_name.
• Para habilitar más de una función, ejecuta codex --enable feature_a --enable feature_b.
• Para deshabilitar una función, establece la clave en false dentro de config.toml.