Configuración avanzada

Usa estas opciones cuando necesites tener más control sobre los proveedores, las políticas y las integraciones. Para comenzar rápidamente, consulta Conceptos básicos de configuración.

Para obtener información general sobre las instrucciones del proyecto, las capacidades reutilizables, los comandos de barra personalizados, los flujos de trabajo con subagentes y las integraciones, consulta Personalización. Para conocer las claves de configuración, consulta la Referencia de configuración.

Perfiles

Los perfiles te permiten guardar capas de configuración con nombre y alternar entre ellas desde la CLI. Cuando proporcionas --profile profile-name, Codex carga ~/.codex/config.toml y, a continuación, superpone ~/.codex/profile-name.config.toml. Los nombres de perfil pueden contener letras, números, guiones y guiones bajos.

Crea un archivo TOML independiente para cada perfil. Usa claves de configuración de nivel superior en el archivo del perfil; no las anides en [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Como el archivo del perfil es una capa situada por encima de tu configuración de usuario base y por debajo de la configuración del proyecto y de la CLI, solo necesita los valores que difieran de tu configuración base. Los archivos de perfil también pueden reemplazar model_catalog_json; Codex usa el valor del perfil cuando ambos archivos lo definen.

En Codex 0.134.0 y versiones posteriores, --profile ya no lee [profiles.profile-name] desde config.toml, y el selector de nivel superior profile = "profile-name" ya no es compatible. Mueve la configuración de perfiles heredada a ~/.codex/profile-name.config.toml y, a continuación, elimina la tabla [profiles.profile-name] correspondiente y el selector profile = "profile-name" de config.toml.

Reemplazos puntuales desde la CLI

Además de editar ~/.codex/config.toml, puedes reemplazar la configuración para una sola ejecución desde la CLI:

• Da preferencia a las opciones específicas cuando existan (por ejemplo, --model).
• Usa -c / --config cuando necesites reemplazar una clave arbitraria.

Ejemplos:

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Notas:

• Las claves pueden usar notación de puntos para establecer valores anidados (por ejemplo, mcp_servers.context7.enabled=false).
• Los valores de --config se analizan como TOML. En caso de duda, pon el valor entre comillas para que el shell no lo divida en los espacios.
• Si el valor no se puede analizar como TOML, Codex lo trata como una cadena.

Ubicaciones de la configuración y el estado

Codex almacena su estado local en CODEX_HOME (el valor predeterminado es ~/.codex).

Archivos habituales que puedes encontrar allí:

• config.toml (tu configuración local)
• auth.json (si usas almacenamiento de credenciales basado en archivos) o el llavero de tu sistema operativo
• history.jsonl (si está activada la persistencia del historial)
• Otros datos de estado por usuario, como registros y cachés

Para obtener información sobre la autenticación (incluidos los modos de almacenamiento de credenciales), consulta Autenticación. Para ver la lista completa de claves de configuración, consulta la Referencia de configuración.

Para conocer los valores predeterminados, las reglas y las skills compartidos que se registran en repositorios o rutas del sistema, consulta Configuración de equipo.

Si solo necesitas dirigir el proveedor integrado de OpenAI a un proxy de LLM, un enrutador o un proyecto con residencia de datos activada, establece openai_base_url en config.toml en lugar de definir un proveedor nuevo. Esto cambia la URL base del proveedor integrado openai sin necesidad de una entrada model_providers.<id> independiente.

openai_base_url = "https://us.api.openai.com/v1"

Archivos de configuración del proyecto (.codex/config.toml)

Además de tu configuración de usuario, Codex lee reemplazos específicos del proyecto desde archivos .codex/config.toml dentro de tu repositorio. Codex recorre la ruta desde la raíz del proyecto hasta tu directorio de trabajo actual y carga todos los archivos .codex/config.toml que encuentra. Si varios archivos definen la misma clave, prevalece el archivo más cercano a tu directorio de trabajo.

Por motivos de seguridad, Codex solo carga los archivos de configuración específicos del proyecto cuando este es de confianza. Si el proyecto no es de confianza, Codex ignora las capas .codex/ del proyecto, incluidos .codex/config.toml, los hooks locales del proyecto y las reglas locales del proyecto. Las capas de usuario y del sistema permanecen separadas y se siguen cargando.

Las rutas relativas dentro de la configuración de un proyecto (por ejemplo, model_instructions_file) se resuelven con respecto a la carpeta .codex/ que contiene el archivo config.toml.

Los archivos de configuración del proyecto no pueden reemplazar ajustes que redirijan credenciales, modifiquen los metadatos de solicitudes de aplicaciones controlados por el host, cambien la autenticación del proveedor, seleccionen perfiles de configuración o ejecuten comandos locales de notificación o telemetría. Codex ignora las siguientes claves en el archivo .codex/config.toml local del proyecto y muestra una advertencia al iniciarse cuando las encuentra: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url y otel. Establece las claves de proveedor, notificación y telemetría en tu archivo ~/.codex/config.toml de usuario; selecciona perfiles de configuración con --profile profile-name y ~/.codex/profile-name.config.toml.

Hooks

Codex también puede cargar hooks del ciclo de vida desde archivos hooks.json o tablas [hooks] insertadas en archivos config.toml situados junto a las capas de configuración activas.

En la práctica, las cuatro ubicaciones más útiles son:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Los hooks locales del proyecto solo se cargan cuando la capa .codex/ del proyecto es de confianza. Los hooks de usuario no dependen de la confianza del proyecto.

Los hooks TOML insertados usan la misma estructura de eventos que hooks.json:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

Si una misma capa contiene tanto hooks.json como [hooks] insertado, Codex carga ambos y muestra una advertencia. Da preferencia a una sola representación por capa.

Para consultar la lista actual de eventos, los campos de entrada, el comportamiento de salida y las limitaciones, consulta Hooks.

Roles de agente ([agents] en config.toml)

Para configurar los roles de los subagentes ([agents] en config.toml), consulta Subagentes.

Detección de la raíz del proyecto

Codex detecta la configuración del proyecto (por ejemplo, las capas .codex/ y AGENTS.md) recorriendo los directorios hacia arriba desde el directorio de trabajo hasta llegar a la raíz de un proyecto.

De manera predeterminada, Codex considera que un directorio que contiene .git es la raíz del proyecto. Para personalizar este comportamiento, establece project_root_markers en config.toml:

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

Establece project_root_markers = [] para omitir la búsqueda en directorios superiores y tratar el directorio de trabajo actual como la raíz del proyecto.

Proveedores de modelos personalizados

Un proveedor de modelos define cómo se conecta Codex a un modelo (URL base, API de comunicación, autenticación y encabezados HTTP opcionales). Los proveedores personalizados no pueden reutilizar los identificadores reservados de los proveedores integrados: openai, ollama y lmstudio.

Define proveedores adicionales y dirige model_provider a ellos:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Si un proveedor personalizado admite el endpoint independiente de búsqueda web, declara esa capacidad en su configuración:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

El valor predeterminado de este ajuste es false para los proveedores personalizados. La búsqueda web independiente está en desarrollo y desactivada de manera predeterminada. Establecer la capacidad del proveedor en true no la activa: el proveedor debe admitir un endpoint compatible, y el modelo y el entorno de ejecución seleccionados deben admitir la búsqueda independiente. El modo web_search configurado y las restricciones administradas de búsqueda siguen aplicándose.

Añade encabezados de solicitud cuando sea necesario:

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Usa autenticación mediante comandos cuando un proveedor necesite que Codex obtenga tokens de portador de un asistente de credenciales externo:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

El comando de autenticación no recibe ningún stdin y debe imprimir el token en stdout. Codex elimina los espacios en blanco circundantes, considera que un token vacío es un error y lo actualiza de forma preventiva en refresh_interval_ms; establece refresh_interval_ms = 0 para actualizarlo solo después de un reintento de autenticación. No combines [model_providers.<id>.auth] con env_key, experimental_bearer_token ni requires_openai_auth.

Proveedor Amazon Bedrock

Codex incluye un proveedor de modelos amazon-bedrock integrado. Establécelo directamente como model_provider; a diferencia de los proveedores personalizados, este proveedor integrado solo admite los reemplazos anidados del perfil y la región de AWS.

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

Si omites profile, Codex usa la cadena de credenciales estándar de AWS. Establece region en la región de Bedrock compatible que deba gestionar las solicitudes.

Para consultar el flujo de configuración completo, las opciones de autenticación, los modelos compatibles y la disponibilidad de las funciones, consulta Usar ChatGPT Work y Codex con Amazon Bedrock.

Modo OSS (proveedores locales)

Codex puede ejecutarse con un proveedor local de «código abierto», como Ollama o LM Studio, cuando proporcionas --oss. Elige uno para una única ejecución con --local-provider o establece oss_provider como valor predeterminado. Si no se establece ninguno, la CLI interactiva te solicita que elijas; codex exec finaliza con un error.

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Proveedor de Azure y ajustes por proveedor

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Para cambiar la URL base del proveedor integrado de OpenAI, usa openai_base_url; no crees [model_providers.openai], porque no puedes reemplazar los identificadores de proveedores integrados.

Clientes de ChatGPT que usan residencia de datos

Los proyectos creados con la residencia de datos activada pueden crear un proveedor de modelos para actualizar base_url con el prefijo correcto.

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

Razonamiento del modelo, nivel de detalle y límites

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity solo se aplica a proveedores que usan Responses API. Los proveedores de Chat Completions ignorarán este ajuste.

Políticas de aprobación y modos de sandbox

Elige el nivel de exigencia de las aprobaciones (determina cuándo se detiene Codex) y el nivel del sandbox (determina el acceso a archivos y a la red).

Para conocer los detalles operativos que debes tener en cuenta al editar config.toml, consulta Combinaciones habituales de sandbox y aprobación, Rutas protegidas en raíces con permiso de escritura y Acceso a la red.

Para obtener información sobre los perfiles de permisos beta que configuran conjuntamente el acceso al sistema de archivos y a la red, consulta Permisos.

También puedes usar una política de aprobación granular (approval_policy = { granular = { ... } }) para permitir o rechazar automáticamente categorías concretas de solicitudes. Esto resulta útil cuando quieres aprobaciones interactivas normales en algunos casos, pero deseas que otras solicitudes, como request_permissions o las de scripts de skills, se rechacen automáticamente de forma segura.

Establece approvals_reviewer = "auto_review" para dirigir las solicitudes interactivas de aprobación admitidas a una revisión automática. Esto cambia al revisor, no los límites del sandbox.

Usa [auto_review].policy para las instrucciones de la política del revisor local. La configuración administrada guardian_policy_config tiene prioridad.

approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

Perfiles de permisos con nombre

Para conocer los perfiles integrados, la sintaxis de perfiles personalizados y el modelo completo de configuración del sistema de archivos y de la red, consulta Permisos.

Para consultar la lista completa de claves y las restricciones de requisitos, consulta la Referencia de configuración y la Configuración administrada.

Desactiva por completo el sandbox (úsalo solo si tu entorno ya aísla los procesos):

sandbox_mode = "danger-full-access"

Política del entorno del shell

shell_environment_policy controla qué variables de entorno transmite Codex a los comandos iniciados. Comienza con un entorno vacío mediante inherit = "none" o hereda un conjunto reducido mediante inherit = "core". Añade valores explícitos y filtros por clave para evitar transmitir secretos innecesarios a los comandos iniciados.

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

Los patrones de filtro no distinguen entre mayúsculas y minúsculas y admiten * y ?. Usa "exclude" para eliminar las variables coincidentes. Cuando algún patrón usa "include", Codex conserva solo las variables que coincidan con un patrón de inclusión. Las inclusiones no restauran variables que ya se hayan excluido. Las claves de filtro se combinan sin distinguir entre mayúsculas y minúsculas en las capas de configuración.

El valor predeterminado de ignore_default_excludes es true, por lo que Codex no elimina automáticamente los nombres de variables que contengan KEY, SECRET o TOKEN. Establécelo en false para aplicar esas exclusiones automáticas antes de ejecutar tus filtros explícitos.

Codex aplica primero las exclusiones automáticas, después las exclusiones personalizadas, los valores de set y, por último, la lista de permitidos basada en patrones de inclusión. Como set se ejecuta después de las exclusiones, puede restaurar una variable excluida. Una lista de permitidos basada en patrones de inclusión aún puede eliminar ese valor restaurado.

Las matrices antiguas exclude y include_only siguen siendo compatibles con las configuraciones existentes. No combines ninguna de estas matrices con [shell_environment_policy.filters] en la misma capa de configuración; Codex rechaza esa combinación.

Servidores MCP

Consulta la documentación de MCP específica para conocer los detalles de configuración.

Observabilidad y telemetría

Activa la exportación de registros de OpenTelemetry (OTel) para supervisar las ejecuciones de Codex (solicitudes de API, SSE/eventos, solicitudes, aprobaciones/resultados de herramientas). Está desactivada de manera predeterminada; actívala mediante [otel]:

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

Elige un exportador:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Si exporter = "none", Codex registra los eventos, pero no envía nada. Los exportadores agrupan los datos de forma asíncrona y los vacían al cerrarse. Los metadatos de los eventos incluyen el nombre del servicio, la versión de la CLI, la etiqueta del entorno, el identificador de la conversación, el modelo, la configuración del sandbox y de las aprobaciones, y campos específicos de cada evento (consulta la Referencia de configuración).

Datos que se emiten

Codex emite eventos de registro estructurados sobre las ejecuciones y el uso de herramientas. Algunos tipos de eventos representativos son:

• codex.conversation_starts (modelo, ajustes de razonamiento y política del sandbox y de aprobaciones)
• codex.api_request (intento, estado/éxito, duración y detalles del error)
• codex.sse_event (tipo de evento del flujo, éxito/fallo, duración y recuentos de tokens en response.completed)
• codex.websocket_request y codex.websocket_event (duración de la solicitud y tipo/éxito/error de cada mensaje)
• codex.user_prompt (longitud; contenido oculto salvo que se active explícitamente)
• codex.tool_decision (aprobado/denegado y si la decisión provino de la configuración o del usuario)
• codex.tool_result (duración, éxito y fragmento de la salida)

Métricas OTel emitidas

Cuando la canalización de métricas OTel está activada, Codex emite contadores e histogramas de duración de la actividad de la API, los flujos y las herramientas.

Cada métrica siguiente también incluye etiquetas de metadatos predeterminadas: auth_mode, originator, session_source, model y app.version.

Para obtener más orientación sobre seguridad y privacidad relacionada con la telemetría, consulta Seguridad.

Métricas

De manera predeterminada, Codex envía periódicamente a OpenAI una pequeña cantidad de datos anónimos sobre el uso y el estado. Esto ayuda a detectar cuándo Codex no funciona correctamente y muestra qué funciones y opciones de configuración se utilizan, para que el equipo de Codex pueda centrarse en lo más importante. Estas métricas no contienen información de identificación personal (PII). La recopilación de métricas es independiente de la exportación de registros y trazas de OTel.

Si quieres desactivar por completo la recopilación de métricas en la aplicación de escritorio de ChatGPT, Codex CLI y la extensión de IDE de un equipo, establece la opción de análisis en tu configuración:

[analytics]
enabled = false

Cada métrica incluye sus propios campos, además de los campos de contexto predeterminados que se indican a continuación.

Campos de contexto predeterminados (se aplican a todos los eventos y métricas)

• auth_mode: swic | api | unknown.
• model: nombre del modelo utilizado.
• app.version: versión de Codex.

Catálogo de métricas

Cada métrica incluye los campos obligatorios, además de los campos de contexto predeterminados anteriores. Los nombres de las métricas que aparecen a continuación omiten el prefijo codex.. La mayoría de los nombres de métricas están centralizados en codex-rs/otel/src/metrics/names.rs; también se incluyen aquí las métricas específicas de funciones emitidas fuera de ese archivo. Si una métrica incluye el campo tool, este refleja la herramienta interna utilizada (por ejemplo, apply_patch o shell) y no contiene el comando del shell ni el parche reales que codex intenta aplicar.

Entorno de ejecución y transporte del modelo

La métrica cloud_requirements.fetch_attempt incluye los campos trigger, attempt, outcome y status_code. La métrica cloud_requirements.fetch_final incluye los campos trigger, outcome, reason, attempt_count y status_code.

Actividad de turnos y herramientas

Las métricas mcp.call y mcp.call.duration_ms incluyen status; las emisiones normales de llamadas a herramientas también incluyen tool, además de connector_id y connector_name cuando están disponibles. Las llamadas bloqueadas de MCP de Codex Apps pueden emitir mcp.call solo con status.

Hilos, tareas y funciones

La métrica shell_snapshot incluye success y, cuando hay fallos, failure_reason.

Memoria y estado local

Las métricas external_agent_config.detect y external_agent_config.import incluyen migration_type; las migraciones de skills también incluyen skills_count.

Sandbox de Windows

Las métricas de errores de configuración con privilegios elevados incluyen code y message cuando están disponibles los detalles del error de configuración de Windows, y pueden incluir originator cuando se emiten desde la ruta de configuración compartida. La métrica windows_sandbox.legacy_setup_preflight_failed incluye originator cuando se emite desde la ruta de configuración compartida, pero es posible que los errores de comprobación previa del mensaje alternativo no incluyan ningún campo.

Controles de comentarios

De forma predeterminada, los clientes locales permiten que los usuarios envíen comentarios desde /feedback. Para desactivar la recopilación de comentarios en la aplicación de escritorio ChatGPT, Codex CLI y la extensión de IDE de un equipo, actualiza la configuración:

[feedback]
enabled = false

Cuando está desactivada, /feedback muestra un mensaje de desactivación y Codex rechaza los envíos de comentarios.

Ocultar o mostrar eventos de razonamiento

Si quieres reducir el ruido de la salida de "razonamiento" (por ejemplo, en los registros de CI), puedes suprimirla:

hide_agent_reasoning = true

Si quieres mostrar el contenido de razonamiento sin procesar cuando un modelo lo emite:

show_raw_agent_reasoning = true

Activa el razonamiento sin procesar solo si es aceptable para tu flujo de trabajo. Algunos modelos o proveedores (como gpt-oss) no emiten razonamiento sin procesar; en ese caso, esta configuración no tiene ningún efecto visible.

Notificaciones

Usa notify para activar un programa externo cada vez que Codex emita eventos compatibles (actualmente, solo agent-turn-complete). Esto resulta útil para notificaciones de escritorio, webhooks de chat, actualizaciones de CI o cualquier alerta por un canal secundario que no cubran las notificaciones integradas de la TUI.

notify = ["python3", "/path/to/notify.py"]

Ejemplo de notify.py (truncado) que reacciona a agent-turn-complete:

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

El script recibe un único argumento JSON. Los campos habituales incluyen:

• type (actualmente, agent-turn-complete)
• thread-id (identificador de sesión)
• turn-id (identificador de turno)
• cwd (directorio de trabajo)
• input-messages (mensajes del usuario que dieron lugar al turno)
• last-assistant-message (texto del último mensaje del asistente)

Coloca el script en alguna ubicación del disco y dirige notify a él.

notify frente a tui.notifications

• notify ejecuta un programa externo (adecuado para webhooks, notificadores de escritorio y enlaces de CI).
• tui.notifications está integrado en la TUI y, opcionalmente, puede filtrar por tipo de evento (por ejemplo, agent-turn-complete y approval-requested).
• tui.notification_method controla cómo emite la TUI las notificaciones del terminal (auto, osc9 o bel).
• tui.notification_condition controla si las notificaciones de la TUI solo se activan cuando el terminal está unfocused o always.

En el modo auto, Codex da prioridad a las notificaciones OSC 9 (una secuencia de escape del terminal que algunos terminales interpretan como una notificación de escritorio) y, en caso contrario, recurre a BEL (\x07).

Consulta la Referencia de configuración para conocer las claves exactas.

Persistencia del historial

De forma predeterminada, Codex guarda las transcripciones de las sesiones locales en CODEX_HOME (por ejemplo, ~/.codex/history.jsonl). Para desactivar la persistencia del historial local:

[history]
persistence = "none"

Para limitar el tamaño del archivo de historial, establece history.max_bytes. Cuando el archivo supera el límite, Codex elimina las entradas más antiguas y compacta el archivo, a la vez que conserva los registros más recientes.

[history]
max_bytes = 104857600 # 100 MiB

Citas en las que se puede hacer clic

Si usas una integración de terminal o editor compatible, Codex puede representar las citas de archivos como enlaces en los que se puede hacer clic. Configura file_opener para elegir el esquema de URI que utiliza Codex:

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

Ejemplo: una cita como /home/user/project/main.py:42 puede convertirse en un enlace vscode://file/...:42 en el que se puede hacer clic.

Detección de instrucciones del proyecto

Codex lee AGENTS.md (y archivos relacionados) e incluye una cantidad limitada de indicaciones del proyecto en el primer turno de una sesión. Dos opciones controlan su funcionamiento:

• project_doc_max_bytes: cuánto se debe leer de cada archivo AGENTS.md
• project_doc_fallback_filenames: nombres de archivo adicionales que se deben probar cuando falta AGENTS.md en un nivel del directorio

Para obtener una explicación detallada, consulta Instrucciones personalizadas con AGENTS.md.

Escritorio

Las opciones de esta sección solo se aplican a la aplicación de escritorio ChatGPT.

Añadir controladores de archivos personalizados

En tu archivo ~/.codex/config.toml de usuario, añade entradas en desktop.custom_file_handlers para abrir archivos en editores o iniciadores internos que la aplicación de escritorio ChatGPT no admite de forma predeterminada. Cada entrada añade un destino de editor a los menús Abrir en de la aplicación. La aplicación muestra el destino cuando command es una ruta absoluta existente o se resuelve desde el PATH de la aplicación.

El siguiente ejemplo muestra tres formas de pasar un archivo a un controlador:

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

Guarda config.toml y, a continuación, reinicia la aplicación de escritorio ChatGPT.

El ID del controlador es el segmento final del encabezado de la tabla TOML. Debe contener entre 1 y 64 caracteres, comenzar con una letra o un número ASCII y contener en el resto solo letras y números ASCII, puntos, guiones bajos o guiones. La aplicación expone el ID con el prefijo custom:; por ejemplo, company_editor se convierte en custom:company_editor. Pon entre comillas un ID que contenga un punto para que TOML no lo interprete como una tabla anidada. Por ejemplo:

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

Cada controlador admite estos campos:

El valor input controla lo que aparece después de args:

• path añade la ruta como argumento final del comando.
• json_argument añade un objeto JSON con target, path, appPath y location. El valor location es un objeto con valores line y column basados en 1, o null.
• json_stdin escribe el objeto JSON en la entrada estándar en lugar de añadir un argumento. También incluye hostConfig, remoteWorkspaceRoot y remotePath; estos campos son null cuando no se aplican.

Por ejemplo, company_editor puede recibir este argumento cuando el usuario abre una ubicación específica del código fuente:

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

Al seleccionar un controlador personalizado como editor preferido, la elección se conserva del mismo modo que al seleccionar un editor integrado, incluidas las preferencias por proyecto.

Opciones de la TUI

Al ejecutar codex sin ningún subcomando, se inicia la interfaz de usuario interactiva del terminal (TUI). Codex ofrece algunas opciones de configuración específicas de la TUI en [tui], entre ellas:

• tui.notifications: activa o desactiva las notificaciones (o las restringe a tipos específicos)
• tui.notification_method: elige auto, osc9 o bel para las notificaciones del terminal
• tui.notification_condition: elige unfocused o always para determinar cuándo se activan las notificaciones
• tui.animations: activa o desactiva las animaciones ASCII y los efectos de brillo
• tui.alternate_screen: controla el uso de la pantalla alternativa (establécelo en never para conservar el búfer de desplazamiento del terminal)
• tui.show_tooltips: muestra u oculta los consejos de incorporación en la pantalla de bienvenida

El valor predeterminado de tui.notification_method es auto. En el modo auto, Codex da prioridad a las notificaciones OSC 9 (una secuencia de escape del terminal que algunos terminales interpretan como una notificación de escritorio) cuando parece que el terminal las admite y, en caso contrario, recurre a BEL (\x07).

Consulta la Referencia de configuración para ver la lista completa de claves.