Configuración avanzada

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

Para obtener más información sobre las instrucciones del proyecto, las capacidades reutilizables, los comandos slash personalizados, los flujos de trabajo de subagentes y las integraciones, consulta Personalización. Para conocer las claves de configuración, consulta Referencia de configuración.

Perfiles

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

Crea un archivo TOML separado 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 que tiene prioridad sobre la configuración base del usuario, pero no sobre la configuración del proyecto ni de la CLI, solo necesita los valores que difieren de tu configuración base. Los archivos de perfil también pueden sobrescribir 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 los perfiles antiguos a ~/.codex/profile-name.config.toml y luego elimina la tabla correspondiente [profiles.profile-name] y el selector profile = "profile-name" de config.toml.

Sobrescrituras para una sola ejecución desde la CLI

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

• Usa preferentemente los indicadores específicos cuando existan (por ejemplo, --model).
• Usa -c / --config cuando necesites sobrescribir cualquier clave.

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 la notación de puntos para establecer valores anidados (por ejemplo, mcp_servers.context7.enabled=false).
• Los valores de --config se interpretan como TOML. Si tienes dudas, encierra el valor entre comillas para que el shell no lo divida por los espacios.
• Si el valor no se puede interpretar como TOML, Codex lo trata como una cadena de texto.

Ubicaciones de la configuración y el estado

Codex almacena su estado local en CODEX_HOME (de forma predeterminada, ~/.codex).

Archivos comunes 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 la persistencia del historial está habilitada)
• Otros datos de estado por 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 Referencia de configuración.

Para obtener información sobre los valores predeterminados compartidos, las reglas y las habilidades guardados en repositorios o rutas del sistema, consulta Configuración del equipo.

Si solo necesitas que el proveedor integrado de OpenAI apunte 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 integrado openai 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 las sobrescrituras específicas del proyecto de los archivos .codex/config.toml dentro de tu repositorio. Codex recorre los directorios desde la raíz del proyecto hasta tu directorio de trabajo actual y carga cada archivo .codex/config.toml que encuentra. Si varios archivos definen la misma clave, tiene prioridad el archivo más cercano a tu directorio de trabajo.

Por seguridad, Codex carga los archivos de configuración específicos del proyecto solo cuando el proyecto es de confianza. Si el proyecto no es de confianza, Codex ignora sus capas .codex/, incluidos .codex/config.toml, los hooks locales del proyecto y las reglas locales del proyecto. Las capas del usuario y del sistema se mantienen 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 sobrescribir ajustes que redirijan credenciales, alteren los metadatos de solicitudes de apps controlados por el host, cambien la autenticación del proveedor, seleccionen perfiles de configuración o ejecuten comandos de notificación o telemetría locales de la máquina. Codex ignora las siguientes claves en el archivo .codex/config.toml local del proyecto y muestra una advertencia al iniciar 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 del proveedor, las notificaciones y la telemetría en tu archivo de configuración de usuario ~/.codex/config.toml; selecciona los 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] incluidas en archivos config.toml ubicados 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 se cargan solo cuando la capa .codex/ del proyecto es de confianza. Los hooks de usuario son independientes del estado de confianza del proyecto.

Los hooks incluidos en TOML 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] en línea, Codex carga ambos y muestra una advertencia. Usa preferentemente una sola representación por capa.

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

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

Para obtener información sobre la configuración de roles de subagentes ([agents] en config.toml), consulta Subagentes.

Detección de la raíz del proyecto

Codex encuentra la configuración del proyecto (por ejemplo, las capas .codex/ y AGENTS.md) recorriendo los directorios superiores 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 considerar 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 ID reservados de los proveedores integrados: openai, ollama y lmstudio.

Define proveedores adicionales y configura model_provider para que apunte 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 punto de acceso de búsqueda web independiente, 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 valor predeterminado del ajuste es 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 punto de acceso compatible, y el modelo seleccionado y el entorno de ejecución deben admitir la búsqueda independiente. El modo web_search configurado y las restricciones de búsqueda administradas siguen vigentes.

Agrega 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 la autenticación mediante comandos cuando un proveedor necesite que Codex obtenga tokens de portador de una herramienta externa de gestión de credenciales:

[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 datos por stdin y debe escribir el token en stdout. Codex elimina los espacios en blanco al principio y al final, considera un token vacío como un error y lo renueva de forma proactiva según refresh_interval_ms; establece refresh_interval_ms = 0 para renovarlo 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 de Amazon Bedrock

Codex incluye un proveedor de modelos integrado, amazon-bedrock. Establécelo directamente como model_provider; a diferencia de los proveedores personalizados, este proveedor integrado solo admite las sobrescrituras anidadas 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 compatible de Bedrock que deba procesar las solicitudes.

Para conocer el proceso completo de configuración, las opciones de autenticación, los modelos compatibles y la disponibilidad de funciones, consulta Usa 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 pasas --oss. Elige uno para una sola ejecución con --local-provider, o configura oss_provider para establecer el proveedor predeterminado. Si no se establece ninguna de estas opciones, la CLI interactiva te pide que elijas uno; 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 integrado de OpenAI, usa openai_base_url; no crees [model_providers.openai], porque no puedes sobrescribir los ID de los proveedores integrados.

Organizaciones de la API que usan residencia de datos

En los proyectos creados con residencia de datos habilitada, puedes crear un proveedor de modelos para actualizar base_url con el prefijo correcto. Los espacios de trabajo de ChatGPT con residencia de datos no requieren 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 esta configuración.

Políticas de aprobación y modos de sandbox

Elige el grado de exigencia de las aprobaciones (determina cuándo se pausa 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 comunes de sandbox y aprobación, Rutas protegidas en directorios raíz con permisos 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 las opciones de configuración compatibles y las aprobaciones más estrictas derivadas del proyecto.

Para obtener información sobre los perfiles de permisos en 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 prompts. Esto es útil cuando quieres las aprobaciones interactivas habituales para algunos casos, pero que otros, como los prompts de request_permissions o de scripts de habilidades, se bloqueen automáticamente.

Establece approvals_reviewer = "auto_review" para que las solicitudes de aprobación interactivas que cumplan los requisitos pasen por una revisión automática. Esto cambia quién revisa, pero no los límites del sandbox.

Usa [auto_review].policy para las instrucciones locales de la política del revisor. La configuración administrada 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 consultar la lista completa de claves y las restricciones de los requisitos, consulta Referencia de configuración y Configuración administrada.

Desactiva por completo el entorno aislado (usa esta opción solo si tu entorno ya aísla los procesos):

sandbox_mode = "danger-full-access"

Política del entorno de shell

shell_environment_policy controla qué variables de entorno pasa Codex a los comandos que inicia. Comienza con un entorno vacío usando inherit = "none", o hereda un conjunto reducido usando inherit = "core". Agrega valores explícitos y filtros por clave para evitar pasar secretos innecesarios a los comandos que se inician.

[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 que coincidan. Cuando algún 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 excluyeron. Las claves de filtro se combinan entre las capas de configuración sin distinguir entre mayúsculas y minúsculas.

El valor predeterminado de ignore_default_excludes es true, por lo que Codex no elimina automáticamente las variables cuyos nombres 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, luego 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.

Los arreglos anteriores exclude y include_only siguen siendo compatibles con las configuraciones existentes. No combines ninguno de los dos arreglos 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 para conocer los detalles de configuración.

Observabilidad y telemetría

Habilita la exportación de registros de OpenTelemetry (OTel) para hacer un seguimiento de las ejecuciones de Codex (solicitudes a la API, SSE/eventos, prompts y aprobaciones/resultados de herramientas). Está deshabilitada de forma predeterminada; habilítala 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 eventos, pero no envía nada. Los exportadores agrupan los datos en lotes de forma asíncrona y envían los datos pendientes al cerrar. 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 los campos específicos de cada evento (consulta Referencia de configuración).

Qué se emite

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

• codex.conversation_starts (modelo, configuración de razonamiento, 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 transmisión, éxito/fallo, duración y conteos de tokens en response.completed)
• codex.websocket_request y codex.websocket_event (duración de la solicitud y tipo/éxito/error por mensaje)
• codex.user_prompt (longitud; el contenido se oculta a menos que se habilite explícitamente su registro)
• 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 de OTel emitidas

Cuando el flujo de métricas de OTel está habilitado, Codex emite contadores e histogramas de duración para la actividad de la API, las transmisiones y las herramientas.

Cada métrica que se muestra a continuación 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 relacionadas 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 sobre el uso y el estado de funcionamiento. Esto ayuda a detectar cuándo Codex no funciona correctamente y muestra qué funciones y opciones de configuración se usan, para que el equipo de Codex pueda concentrarse 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 para IDE en una computadora, establece la opción de analítica 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 indicados arriba. 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; aquí también se incluyen las métricas de funciones específicas que se emiten fuera de ese archivo. Si una métrica incluye el campo tool, este indica la herramienta interna utilizada (por ejemplo, apply_patch o shell) y no contiene el comando de shell concreto 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; los datos emitidos en las llamadas normales a herramientas también incluyen tool, además de connector_id y connector_name cuando están disponibles. Las llamadas MCP bloqueadas de Codex Apps pueden emitir mcp.call solo con status.

Hilos, tareas y funciones

La métrica shell_snapshot incluye success y, en caso de fallas, 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 fallas de configuración con privilegios elevados incluyen code y message cuando hay detalles disponibles sobre la falla de configuración en Windows, y pueden incluir originator cuando se emiten desde la ruta de ejecución compartida de configuración. La métrica windows_sandbox.legacy_setup_preflight_failed incluye originator cuando se emite desde la ruta de ejecución compartida de configuración, pero las fallas de verificación previa desde el prompt del sandbox alternativo pueden 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 de ChatGPT, Codex CLI y la extensión para IDE en un equipo, actualiza tu configuración:

[feedback]
enabled = false

Cuando la recopilación está desactivada, /feedback muestra un mensaje que lo indica 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 ocultarla:

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 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 canales alternativos que las notificaciones integradas de la TUI no cubran.

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

Ejemplo de notify.py (recortado) que responde 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 la sesión)
• turn-id (identificador del turno)
• cwd (directorio de trabajo)
• input-messages (mensajes del usuario que dieron lugar al turno)
• last-assistant-message (texto del último mensaje del asistente)

Guarda el script en una ubicación del disco y configura notify para que apunte a él.

notify frente a tui.notifications

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

En el modo auto, Codex da preferencia a las notificaciones OSC 9 (una secuencia de escape de terminal que algunas 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, configura 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 con enlaces

Si usas una integración de terminal o editor que lo admita, Codex puede mostrar las citas de archivos como enlaces en los que puedes hacer clic. Configura file_opener para elegir el esquema de URI que usa 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 puedes hacer clic.

Detección de instrucciones del proyecto

Codex lee AGENTS.md (y los archivos relacionados) e incluye una cantidad limitada de instrucciones del proyecto en el primer turno de una sesión. Dos parámetros controlan este comportamiento:

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

Para obtener una guía detallada, consulta Instrucciones personalizadas con AGENTS.md.

Escritorio

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

Agregar manejadores de archivos personalizados

En tu archivo ~/.codex/config.toml a nivel de usuario, agrega entradas en desktop.custom_file_handlers para abrir archivos en editores o lanzadores internos que la aplicación de escritorio de ChatGPT no admite de forma predeterminada. Cada entrada agrega un editor de destino 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 a partir del PATH de la aplicación.

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

# 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 luego reinicia la aplicación de escritorio de ChatGPT.

El ID del manejador es el último segmento 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. Escribe 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 manejador admite estos campos:

El valor de input controla lo que sigue a args:

• path agrega la ruta como último argumento del comando.
• json_argument agrega un objeto JSON con target, path, appPath y location. El valor de location es un objeto con valores de line y column que se cuentan a partir de 1, o null.
• json_stdin escribe el objeto JSON en la entrada estándar en lugar de agregar un argumento. También incluye hostConfig, remoteWorkspaceRoot y remotePath; estos campos tienen el valor 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 manejador personalizado como editor preferido, la elección se guarda de la misma manera que al seleccionar un editor integrado, incluidas las preferencias por proyecto.

Opciones de la TUI

Al ejecutar codex sin un subcomando, se inicia la interfaz de usuario interactiva de la 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 limítalas a tipos específicos)
• tui.notification_method: elige auto, osc9 o bel para las notificaciones de la terminal
• tui.notification_condition: elige unfocused o always para determinar cuándo se emiten 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 (establece el valor en never para conservar el historial de desplazamiento de la terminal)
• tui.show_tooltips: muestra u oculta los consejos de introducción en la pantalla de bienvenida

El valor predeterminado de tui.notification_method es auto. En el modo auto, Codex da preferencia a las notificaciones OSC 9 (una secuencia de escape de terminal que algunas terminales interpretan como una notificación de escritorio) cuando la terminal parece admitirlas; de lo contrario, recurre a BEL (\x07).

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