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 servidores MCP.

Precedencia de la configuración

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

1. Indicadores de la CLI y anulaciones de --config
2. Archivos de configuración del proyecto: .codex/config.toml, ordenados desde la raíz del proyecto hasta el directorio de trabajo actual (prevalece el más cercano; solo en 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. Configuración del sistema (si existe): /etc/codex/config.toml en Unix
6. 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.

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-5.6"

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 untrusted, on-request y never, consulta Ejecutar sin solicitudes de aprobación y Combinaciones habituales de sandbox y aprobación.

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/.codex y los valores predeterminados de red), consulta Sandbox y aprobaciones, Rutas protegidas en raíces con permiso 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

Al ejecutar Codex de forma nativa en Windows, establece el modo de sandbox nativo en elevated dentro de la tabla windows. Usa unelevated solo si no tienes permisos de administrador o si falla la configuración con privilegios elevados.

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

Modo de búsqueda web

Codex habilita la búsqueda web de forma predeterminada para los chats locales y ofrece 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 indexados previamente en lugar de obtener páginas en vivo. Esto reduce la exposición a la inyección de prompts procedente de contenido arbitrario en vivo, pero aun así debes considerar los resultados web como contenido no confiable. Si usas --yolo u otro ajuste de sandbox con acceso completo, la búsqueda web usa de forma predeterminada resultados en vivo. Elige un modo mediante 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 = "high"

Estilo de comunicación

Establece un estilo de comunicación predeterminado para los modelos compatibles.

personality = "friendly" # or "pragmatic" or "none"

Puedes anularlo posteriormente en una sesión activa mediante /personality o por hilo o turno al usar las API de app-server.

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.