Configuración avanzada

Usa estas opciones cuando necesites un mayor 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 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.6-sol"
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 difieren 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] de 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 de 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, escribe el valor entre comillas para que el shell no lo divida por 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 (de forma predeterminada, ~/.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á habilitada la persistencia del historial)
• Otro estado específico del usuario, como registros y cachés

Para obtener detalles 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 habilidades compartidos e incorporados 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 habilitada, establece openai_base_url en config.toml en lugar de definir un proveedor nuevo. Esto cambia la URL base del proveedor openai integrado sin requerir 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 del repositorio. Codex recorre la ruta desde la raíz del proyecto hasta el directorio de trabajo actual y carga cada .codex/config.toml que encuentra. Si varios archivos definen la misma clave, prevalece el archivo más cercano al directorio de trabajo.

Por motivos de seguridad, Codex solo carga 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, incluidas .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. Define las claves del proveedor, las notificaciones y la telemetría en tu archivo ~/.codex/config.toml de nivel 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 desde 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 nivel de usuario son independientes 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 sola capa contiene tanto hooks.json como [hooks] insertado, Codex carga ambos y muestra una advertencia. Usa preferentemente 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 roles de 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 ascendentes desde el directorio de trabajo hasta llegar a la raíz de un proyecto.

De forma 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 los 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 la configuración del proveedor:

[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 ajuste tiene como valor predeterminado false para los proveedores personalizados. La búsqueda web independiente está en desarrollo y desactivada de forma predeterminada. Establecer la capacidad del proveedor en true no la habilita: 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 siendo aplicables.

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, trata un token vacío como un error y lo actualiza de forma proactiva 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 sola ejecución con --local-provider o establece oss_provider como predeterminado. Si no se establece ninguno, la CLI interactiva te pide que elijas; codex exec termina 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 de OpenAI integrado, usa openai_base_url; no crees [model_providers.openai], ya que no puedes reemplazar los identificadores de proveedores integrados.

Organizaciones de API que usan residencia de datos

Los proyectos creados con la residencia de datos habilitada pueden crear un proveedor de modelos para actualizar base_url con el prefijo correcto. En los espacios de trabajo de ChatGPT con residencia de datos, no se requiere un proveedor personalizado; Codex respeta la configuración de residencia del espacio de trabajo cuando inicias sesión con ChatGPT.

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

Razonamiento, nivel de detalle y límites del modelo

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 los proveedores que usan la 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.

Codex y ChatGPT Work ya no admiten approval_policy = "untrusted". Consulta Migrar desde la política de aprobación retirada untrusted para conocer los ajustes admitidos y las aprobaciones más estrictas derivadas del proyecto.

Para conocer 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 individuales de solicitudes. Esto resulta útil cuando quieres aprobaciones interactivas normales para algunos casos, pero quieres que otros, como request_permissions o las solicitudes de scripts de habilidades, se rechacen de forma segura automáticamente.

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

Usa [auto_review].policy para las instrucciones de la política del revisor local. El valor administrado guardian_policy_config tiene prioridad.

approval_policy = "on-request"  # Other options: 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 obtener información sobre los perfiles integrados, la sintaxis de los perfiles personalizados y el modelo completo de configuración del sistema de archivos y la red, consulta Permisos.

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

Deshabilita 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 pasa Codex a los comandos generados. 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 pasar secretos innecesarios a los comandos generados.

[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 un patrón usa "include", Codex conserva solo las variables que coinciden con un patrón de inclusión. Las inclusiones no restauran las variables que ya se hayan excluido. Las claves de filtro se combinan sin distinguir entre mayúsculas y minúsculas en todas 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 contienen 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 patrones de inclusión permitidos. Como set se ejecuta después de las exclusiones, puede restaurar una variable excluida. Una lista de patrones de inclusión permitidos todavía puede eliminar ese valor restaurado.

Las matrices anteriores 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 obtener detalles sobre la configuración.

Observabilidad y telemetría

Habilita la exportación de registros de OpenTelemetry (OTel) para hacer seguimiento de las ejecuciones de Codex (solicitudes de API, SSE/eventos, solicitudes, aprobaciones/resultados de herramientas). Está deshabilitada de forma 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 procesan lotes 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 las aprobaciones, y campos específicos de cada evento (consulta la Referencia de configuración).

Qué se emite

Codex emite eventos de registro estructurados para las ejecuciones y el uso de herramientas. Estos son algunos tipos de eventos representativos:

• codex.conversation_starts (modelo, configuración de razonamiento y política de sandbox/aprobación)
• codex.api_request (intento, estado/éxito, duración y detalles del error)
• codex.sse_event (tipo de evento de 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 habilite explícitamente)
• codex.tool_decision (aprobado/denegado y si la decisión procede de la configuración o del usuario)
• codex.tool_result (duración, éxito y fragmento de la salida)

Métricas de OTel emitidas

Cuando la canalización de métricas de OTel está habilitada, 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 las 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 forma predeterminada, Codex envía periódicamente a OpenAI una pequeña cantidad de datos anónimos de uso y 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 deshabilitar por completo la recopilación de métricas en la aplicación de escritorio 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 las 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 real ni el parche 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 a MCP de Codex Apps pueden emitir mcp.call únicamente con status.

Hilos, tareas y funciones

La métrica shell_snapshot incluye success y, en caso de fallo, failure_reason.

Memoria y estado local

Las métricas external_agent_config.detect y external_agent_config.import incluyen migration_type; las migraciones de habilidades 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 de los errores 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 los errores de comprobación previa del mensaje alternativo podrían no incluir ningún campo.

Controles de comentarios

De forma predeterminada, los clientes locales permiten a los usuarios enviar 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 tu 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 produce ningún efecto visible.

Notificaciones

Usa notify para ejecutar un programa externo cada vez que Codex emita eventos compatibles (actualmente, solo agent-turn-complete). Esto resulta útil para notificaciones emergentes 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 (abreviado) 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. Entre los campos habituales se 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 algún lugar del disco y haz que notify apunte a él.

notify frente a tui.notifications

• notify ejecuta un programa externo (útil 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, de lo 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, conservando los registros más recientes.

[history]
max_bytes = 104857600 # 100 MiB

Citas en las que se puede hacer clic

Si utilizas 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 se puede convertir 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 leer de cada archivo AGENTS.md
• project_doc_fallback_filenames: nombres de archivo adicionales que probar cuando falte AGENTS.md en un nivel del directorio

Para ver una guía 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 ~/.codex/config.toml de usuario, añade entradas bajo desktop.custom_file_handlers para abrir archivos en editores o iniciadores internos que la aplicación de escritorio ChatGPT no admita 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 puede resolver 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, después, 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, en el resto, contener solo letras ASCII, números, 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 los ID que contengan un punto para que TOML no los 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 sigue a 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 de 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 corresponden.

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 opció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 terminal interactiva (TUI). Codex ofrece algunas opciones de configuración específicas de la TUI en [tui], entre ellas:

• tui.notifications: activar o desactivar las notificaciones (o restringirlas a tipos específicos)
• tui.notification_method: elegir auto, osc9 o bel para las notificaciones del terminal
• tui.notification_condition: elegir unfocused o always para determinar cuándo se activan las notificaciones
• tui.animations: activar o desactivar las animaciones ASCII y los efectos de brillo
• tui.alternate_screen: controlar el uso de la pantalla alternativa (establécelo en never para conservar el historial de desplazamiento del terminal)
• tui.show_tooltips: mostrar u ocultar las sugerencias 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 el terminal parece admitirlas y, de lo contrario, recurre a BEL (\x07).

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