Codex lee los detalles de configuración desde varias ubicaciones. Tus valores predeterminados personales están en ~/.codex/config.toml y puedes usar archivos .codex/config.toml para reemplazarlos en proyectos específicos. Por seguridad, Codex solo carga las capas .codex/ de un proyecto si confías en él.
Archivo de configuración de Codex
Codex almacena la configuración del usuario en ~/.codex/config.toml. Para que los ajustes se apliquen a un proyecto o una subcarpeta específicos, agrega un archivo .codex/config.toml en tu repositorio.
Para abrir el archivo de configuración desde la extensión de Codex para IDE, selecciona el ícono de engranaje en la esquina superior derecha y luego selecciona Configuración de Codex > Abrir 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 políticas de aprobación y ajustes del sandbox.
- Configurar servidores MCP.
Prioridad de la configuración
Codex resuelve los valores en este orden (primero los de mayor prioridad):
- Flags de la CLI y valores definidos mediante
--config - Archivos de configuración del proyecto:
.codex/config.toml, ordenados desde la raíz del proyecto hasta tu directorio de trabajo actual (el más cercano tiene prioridad; solo para proyectos de confianza) - Archivos de perfil seleccionados con
--profile profile-name(~/.codex/profile-name.config.toml) - Configuración del usuario:
~/.codex/config.toml - Valores predeterminados de
config.tomladministrados en la nube, cuando se proporcionan para el espacio de trabajo en el que iniciaste sesión - Configuración del sistema (si existe):
/etc/codex/config.tomlen Unix - Valores predeterminados integrados
Usa ese orden de prioridad para establecer valores predeterminados compartidos en config.toml y reservar los archivos de perfil para los valores que difieren.
La configuración administrada en la nube y la del sistema pueden definir marketplaces de complementos y establecer
si los complementos están habilitados de forma predeterminada. Estas configuraciones son independientes de las políticas obligatorias de requirements.toml.
Consulta Configurar marketplaces de complementos y valores predeterminados.
Si marcas un proyecto como no confiable, Codex omite las capas .codex/ específicas del proyecto, incluidos su configuración local, hooks y reglas. La configuración del usuario y la del sistema se siguen cargando, incluidos los hooks y las reglas del usuario y globales.
Para reemplazar valores de forma puntual mediante -c/--config (incluidas las reglas de uso de comillas en TOML), consulta Configuración avanzada.
En equipos administrados, tu organización también puede imponer restricciones mediante
requirements.toml (por ejemplo, prohibir approval_policy = "never" o
sandbox_mode = "danger-full-access"). Consulta Configuración
administrada y Requisitos impuestos
por el administrador.
Opciones de configuración comunes
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 el IDE.
model = "gpt-5.6"Solicitudes de aprobación
Controla cuándo Codex se detiene para solicitar aprobación antes de ejecutar los 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 comunes 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/.codex y los valores predeterminados de red), consulta Sandbox y aprobaciones, Rutas protegidas en directorios raíz 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 de default_permissions que coincida. Consulta Permisos.
Modo del sandbox de Windows
Cuando ejecutes Codex de forma nativa en Windows, establece el modo del 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 unavailableModo 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 que mantiene OpenAI, por lo que el modo de caché devuelve resultados indexados previamente en lugar de obtener páginas en tiempo real. Esto reduce la exposición a inyecciones de prompts provenientes de contenido arbitrario en tiempo real, pero aun así debes tratar los resultados web como datos no confiables. Si usas --yolo u otra configuración del sandbox con acceso completo, la búsqueda web usa resultados en tiempo real de forma predeterminada. Elige un modo con web_search:
"cached"(predeterminado) proporciona resultados desde la caché de búsqueda web."indexed"permite el acceso web externo 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 sea compatible con esta opción.
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 cambiarlo más adelante en una sesión activa con /personality, o por hilo o turno cuando uses las API de app-server.
Asignación de teclas de la TUI
Personaliza los atajos de la terminal en tui.keymap. Algunas acciones del editor recurren a las asignaciones correspondientes de tui.keymap.global como alternativa; las asignaciones específicas del contexto tienen prioridad cuando son compatibles. Una lista vacía elimina las asignaciones de 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 transmite 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, 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 conocer las reglas de exclusión, el orden de prioridad y
la configuración heredada, consulta Política del entorno
del shell.
Directorio de registros
Cambia dónde escribe Codex los archivos de registro locales. Establecer log_dir explícitamente también
habilita en ese directorio el registro opcional de la TUI en texto plano, codex-tui.log.
log_dir = "/absolute/path/to/codex-logs"Para ejecuciones puntuales, también puedes establecerlo desde la CLI:
codex -c log_dir=./.codex-logFlags de funciones
Usa la tabla [features] en config.toml para activar o desactivar capacidades opcionales y experimentales.
Flags de funciones comunes
| Clave | Valor predeterminado | Madurez | Descripción |
|---|---|---|---|
apps | true | Estable | Activa las integraciones con apps (conectores) |
goals | true | Estable | Activa los objetivos persistentes y la continuación automática |
hooks | true | Estable | Activa los hooks del ciclo de vida desde hooks.json o mediante [hooks] en la propia configuración. Consulta Hooks. |
fast_mode | true | Estable | Activa la selección del Modo rápido y su uso mediante service_tier = "fast" |
memories | false | Experimental | Activa las Memorias |
multi_agent | true | Estable | Activa las herramientas de colaboración entre subagentes |
personality | true | Estable | Activa los controles de selección de personalidad |
remote_plugin | true | Estable | Activa el catálogo remoto de complementos |
shell_snapshot | true | Estable | Crea una instantánea del entorno de tu shell para acelerar la ejecución de comandos repetidos |
shell_tool | true | Estable | Activa la herramienta shell predeterminada |
unified_exec | true excepto en Windows | Estable | Usa la herramienta exec unificada basada en PTY |
web_search | true | En desuso | Opción heredada; usa preferentemente la configuración web_search de nivel superior |
web_search_cached | false | En desuso | Opción heredada que equivale a web_search = "cached" cuando no se ha definido la configuración |
web_search_request | false | En desuso | Opción heredada que equivale a web_search = "live" cuando no se ha definido la configuración |
Esta tabla enumera las opciones de uso común disponibles para los usuarios, no todas las funciones internas o en desarrollo. La columna Madurez usa etiquetas como Experimental, Beta y Estable. Consulta Madurez de las funciones para saber cómo interpretar estas etiquetas.
Para configurar los hooks del ciclo de vida, consulta Hooks.
Activar funciones
- En
config.toml, agregafeature_name = truedentro de[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 la clave en
falseenconfig.toml.