Codex Configuración avanzada

Codex CLILa capa de configuración avanzada nos permite controlar con precisión los proveedores de modelos, los permisos del sandbox, los hooks, los datos de telemetría y el comportamiento del terminal.

Si es la primera vez que usas Codex, lee primeroConfig basics(Conceptos básicos de configuración)para tener una visión general; este artículo asume que ya conoces~/.codex/config.tomlla existencia y función.


Panorama de niveles de configuración

La configuración de Codex se compone de múltiples capas superpuestas; entender esto es la base de todos los usos avanzados posteriores.

De abajo hacia arriba: capa del sistema → capa de usuario (~/.codex/config.toml) → capa de Profile → capa de proyecto (.codex/config.toml) → parámetros de línea de comandos CLI.

La capa superior sobrescribe la configuración del mismo nombre de la capa inferior; la configuración del proyecto más cercana al directorio de trabajo actual tiene la prioridad más alta.

Título Niveles de configuración de Codex (capa inferior → capa superior, se sobrescriben sucesivamente) Capa 5: CLI ① Parámetros de línea de comandos CLI (prioridad más alta) --model、--config、--profile Capa 4: Nivel de proyecto ② .codex/config.toml a nivel de proyecto Directorio .codex/ dentro del repositorio (requiere que el proyecto sea confiable) Capa 3: Profile ③ Configuración con nombre de Profile (--profile) ~/.codex/<name>.config.toml Capa 2: Nivel de usuario ④ ~/.codex/config.toml a nivel de usuario Configuración predeterminada personal en el directorio CODEX_HOME Capa 1: Nivel de sistema ⑤ Configuración compartida a nivel de sistema / equipo Reglas compartidas de Team Config y archivos a nivel de sistema Nota del lado derecho Anulación para una sola ejecución Obligatorio a nivel de proyecto Cambio de escenario Predeterminado personal Línea base del equipo Nota inferior Regla de fusión: la misma clave se sobrescribe de atrás hacia adelante; la sintaxis de puntos puede ubicar campos anidados. Ejemplo: --config mcp_servers.context7.enabled=false desactiva un solo servicio MCP

La forma más segura de determinar la configuración actualmente activa escodex --helpusando los registros, o explícitamente concodex exec "show my current config"deja que el modelo te ayude a interpretarlo.


Capa de configuración con nombre: Profiles

Profilees el método recomendado por Codex para "cambios por escenario": guarda un conjunto de configuraciones como un archivo TOML y se carga según sea necesario mediante--profile.

Los archivos Profile se encuentran en~/.codex/<name>.config.toml, donde<name>solo puede contener letras, números, guiones y guiones bajos.

Crear y usar un Profile

Supongamos que sueles hacer revisiones de código profundas y deseas usar una capacidad de razonamiento más potente:

Ejemplo

# Ruta del archivo: ~/.codex/deep-review.config.toml
model = "gpt-5.5"                  # Usar un modelo con capacidad de razonamiento más potente
model_reasoning_effort = "xhigh"   # Llevar la intensidad de razonamiento al máximo
approval_policy = "on-request"    # Solicitar aprobación en cada llamada de herramienta
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"  # Opcional: directorio de modelos personalizados

Iniciar Codex con el Profile:

Ejemplo

# Iniciar TUI interactivo
codex --profile deep-review

# O usarlo en modo exec no interactivo
codex exec --profile deep-review "review this change"

Semántica de fusión de Profile

El archivo Profile no es una configuración completa; es una capa de anulación incremental sobre el nivel de usuario~/.codex/config.toml.

Esto significa que en el Profile solo necesitas escribir los campos "diferentes de la configuración predeterminada"; el resto de campos se heredan automáticamente de la configuración de usuario.

Si tanto el nivel de usuario como el Profile configuranmodel_catalog_json,el valor del Profile tiene prioridad.。

Desde Codex 0.134.0,--profileya no se leeconfig.tomlen[profiles.<name>]la tabla, y ya no se admiten los selectores de nivel superiorprofile = "name". Todos los ajustes históricos de Profile deben migrarse a un~/.codex/<name>.config.tomlindependiente.

Migrar desde la configuración anterior a Profile

Si tuconfig.tomlanterior era así:

Ejemplo

# Escritura anterior (obsoleta)
profile = "deep-review"

[profiles.deep-review]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

Debe dividirse en dos archivos:

# 文件路径:~/.codex/config.toml(保留非 profile 部分)
# 注意:删除了 profile = "deep-review" 选择器
# 文件路径:~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

Una vez completada la migración, el uso original decodex --profile deep-reviewen la línea de comandos se mantiene igual.


Anulación de una sola vez en la línea de comandos

A veces solo quieres cambiar temporalmente uno o dos campos para ejecutar una tarea, sin ensuciar el archivo de configuración. En este caso puedes usar anulaciones de CLI:

Priorizar el uso de indicadores dedicados

Si el producto proporciona un parámetro dedicado (por ejemplo,--model),prioriza el indicador dedicado), es lo más legible:

Ejemplo

# Cambiar modelo con el indicador dedicado
codex --model gpt-5.4

Usar --config para anular cualquier clave

Para campos sin indicador dedicado, usa-co--configpara anular. El valor está en formato TOML, no JSON.

Ejemplo

# Los valores de cadena deben usar comillas dobles para anidar comillas
codex --config model='"gpt-5.4"'

# Los valores booleanos se escriben directamente
codex --config sandbox_workspace_write.network_access=true

# Los arrays usan la sintaxis de arrays de TOML
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Algunas reglas con trampas fáciles de evitar:

  • Usa la sintaxis de puntos para localizar campos anidados, por ejemplomcp_servers.context7.enabled=false
  • --configel valor se analizará como TOML; las cadenas con espacios deben ir entre comillas
  • Cuando falla el análisis, Codex trata todo el valor como una cadena

La forma más rápida de comprobar si una anulación tiene efecto es seguir el comando con una pregunta simple: "what model are you using?", para que Codex informe activamente de la configuración actual.


Ubicación de archivos de configuración y estado

Codex guarda todo el estado local enCODEX_HOMEel directorio, que por defecto es~/.codex。

Archivos comunes y su significado:

ArchivoFunción¿Sensible?
config.tomlConfiguración principal local; todas las personalizaciones van aquíno
auth.jsonCredenciales basadas en archivo (si no se usa el llavero del sistema)Sí, se recomienda permiso 600
history.jsonlHistorial de sesiones (se puede desactivar)Puede contener contenido sensible
logs/、caches/Registros de ejecución y cachéPuede contener fragmentos del cuerpo de la solicitud

¿Solo quieres cambiar la URL base de OpenAI?

Muchos usuarios usan proxies de LLM, enrutadores o proyectos de residencia de datos; solo necesitan modificaropenaila URL base del proveedor integrado.

En ese caso, configura directamenteopenai_base_urly no crees uno nuevo[model_providers.openai], porque los ID integrados no se pueden sobrescribir:

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
# Apunta la URL base del proveedor integrado de openai al proxy
openai_base_url = "https://us.api.openai.com/v1"

Configuración a nivel de proyecto .codex/config.toml

La configuración a nivel de proyecto se coloca en la raíz del repositorio.codex/config.tomly se usa para compartir valores predeterminados en equipo.

Codex busca hacia arriba desde el directorio de trabajo,y el archivo más cercano al directorio de trabajo actual tiene la prioridad más alta.。

Límites de la configuración a nivel de proyecto

Por razones de seguridad,solo cuando el proyecto está marcado como "confiable"se carga la capa .codex/ a nivel de proyecto (incluyendo config.toml, hooks locales y rules locales).

En proyectos no confiables, las claves sensibles de la siguiente tabla se ignoran y se imprime una advertencia de inicio:

Claves ignoradasMotivo
openai_base_url、chatgpt_base_urlEvita redirigir credenciales / cambiar metadatos del host
apps_mcp_product_skuAfecta la identificación del producto Codex Apps
model_provider、model_providersEvita reemplazar credenciales / identidad del proveedor
notifyEvita ejecutar comandos locales arbitrarios en la máquina
profile、profilesNo se puede seleccionar un perfil de configuración a nivel de proyecto
experimental_realtime_ws_base_url、otelTelemetría y canales en tiempo real

Estas claves deben colocarse en el nivel de usuario~/.codex/config.toml.

Las rutas relativas (comomodel_instructions_file) se resuelven en relación con el directorio.codex/donde se encuentra el archivo.

Si el proyecto no es confiable y configurasmodel_provider = "proxy", al iniciar Codex imprimirá una advertencia y usará el proveedor predeterminado; esto es un diseño de seguridad, no un error.


Hooks de ciclo de vida

Los hooks te permiten insertar scripts personalizados en puntos clave como llamadas de herramientas, inicios de turno, etc. Son ideales para auditoría, filtrado de palabras sensibles, revisión de commits, etc.

La configuración de hooks admite dos formatos, y la estructura de eventos es exactamente la misma:

FormatoUbicaciónCaso de uso ideal
hooks.jsonArchivoMismo directorio que config.tomlAmigable con la cadena de herramientas JSON, fácil de reutilizar
En línea[[hooks.*]]tablaDentro de config.tomlToda la configuración se gestiona de forma centralizada

Las cuatro ubicaciones de carga más comunes:

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

Los hooks a nivel de proyecto solo se cargan cuando el proyecto es confiable; los hooks a nivel de usuario siempre se cargan de forma independiente.

Ejemplo de Hook TOML en línea

A continuación se muestra un hook de verificación previa que se ejecuta antes de la llamada a la herramienta Bash:

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
# Coincide con todas las llamadas a la herramienta Bash
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
# Ejecuta el script de verificación previa dentro del repositorio (ruta relativa al directorio donde se encuentra .codex/)
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30                                 # Tiempo de espera en segundos; si se agota, se considera rechazado
statusMessage = "Checking Bash command"      # Aviso en la barra de estado

Si en la misma capa existe tanto la forma de archivohooks.jsoncomo una tabla en línea[hooks], Codex cargará ambas e imprimirá una advertencia.Se recomienda elegir solo un formato por capapara evitar duplicar los costos de mantenimiento.


Proveedores de modelos personalizados

Cuando necesites que Codex se conecte a endpoints no oficiales de OpenAI, como proxies de LLM, Ollama, Mistral, Azure, etc.,model_providerses el punto de entrada.

Los ID de proveedores integrados (openai、ollama、lmstudio)no se pueden reutilizar); de lo contrario, habrá conflictos.

Definición básica

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
model = "gpt-5.4"           # El nombre del modelo lo determina el proveedor seleccionado
model_provider = "proxy"    # Apunta al [model_providers.proxy] de abajo

[model_providers.proxy]
name = "OpenAI using LLM proxy"  # Nombre para mostrar
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"       # Lee la clave desde una variable de entorno

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

Agregar cabeceras HTTP

Algunos proxies requieren cabeceras adicionales (como identificación de inquilino, interruptores de funciones):

Ejemplo

[model_providers.example]
# Cabecera estática: se incluye en cada solicitud
http_headers = { "X-Example-Header" = "example-value" }
# Cabecera dinámica: el valor se lee desde una variable de entorno
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Autenticación basada en comandos (Command-backed Auth)

Cuando el token de portador del proveedor debe obtenerse dinámicamente desde un gestor de credenciales externo, usa[model_providers.<id>.auth]:

Ejemplo

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"   # Usa el protocolo de la API de Responses

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000            # Tiempo de espera de una sola obtención
refresh_interval_ms = 300000 # Ciclo de actualización activa (5 minutos)

Restricciones de ejecución del comando auth:

  • No recibe [stdin]stdin; debe enviar el token a [stdout]stdout
  • Codex recorta automáticamente los espacios en blanco al inicio y al final; un token vacío se considera un error
  • Configurarrefresh_interval_ms = 0indica que solo se actualiza después de un fallo de autenticación
  • No se puede usar junto con env_key, experimental_bearer_token o requires_openai_auth

Proveedor integrado de Amazon Bedrock

Codex incluyeamazon-bedrockun proveedor integrado, al que se puede hacer referencia directamente mediantemodel_providerel ID:

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"      # Perfil de AWS; si no se completa, se usa la cadena de credenciales estándar
region = "eu-central-1"  # Región de Bedrock

El proveedor integrado de Bedrock solo admite la anulación de profile y region bajo el bloque.awsanidado; para otras personalizaciones, sigue el flujo estándar demodel_providers.<id>.


Modo local OSS

Codex admite conectarse a modelos "open source" locales (como Ollama, LM Studio) mediante--ossla opción de inicio.

Si solo pasas--osssin especificar un proveedor, Codex leeráoss_providerpara elegir el predeterminado:

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
# Proveedor local predeterminado; opciones: ollama o lmstudio
oss_provider = "ollama"

Ejemplo de uso:

Ejemplo

# Usa el oss_provider predeterminado (ollama)
codex --oss

# Especifica explícitamente que esta sesión use lmstudio
codex --oss --oss-provider lmstudio

Proveedor de Azure y ajuste fino

Ejemplo de conexión a Azure OpenAI que muestra parámetros a nivel de solicitud y estrategias de reintento:

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"          # Lee la clave desde una variable de entorno
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"                    # Usa el protocolo de la API de Responses
request_max_retries = 4                   # Número de reintentos para solicitudes normales
stream_max_retries = 10                   # Número de reintentos para solicitudes de streaming
stream_idle_timeout_ms = 300000           # Tiempo de espera de inactividad del streaming (5 minutos)

Si necesitas modificar la URL base del proveedoropenaiintegrado, usaopenai_base_urly no crees uno nuevo[model_providers.openai]。


Proyecto de residencia de datos de ChatGPT

Los proyectos de ChatGPT con la "residencia de datos" (Data Residency) habilitada necesitan usar una URL base con prefijo regional:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
model_provider = "openaidr"

[model_providers.openaidr]
name = "OpenAI Data Residency"
# Reemplaza "us" por el prefijo que exige la documentación de Data Residency (p. ej., eu, jp, etc.)
base_url = "https://us.api.openai.com/v1"

No todos los modelos admiten Data Residency; antes de elegir, consulta la lista de "eligible models" en la documentación de Data Residency de OpenAI.


Razonamiento del modelo, nivel de detalle y contexto

El conjunto de cuatro ajustes más común para controlar el comportamiento del modelo:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
model_reasoning_summary = "none"          # Desactivar el resumen de razonamiento
model_verbosity = "low"                   # Acortar la longitud de las respuestas
model_supports_reasoning_summaries = true # Forzar al modelo a generar razonamiento
model_context_window = 128000             # Anular el tamaño de la ventana de contexto

Dondemodel_verbositySolo tiene efecto en los providers que usan la API Responses; el provider de Chat Completions ignora esta configuración.


Políticas de aprobación y modo sandbox

approval_policyControla cuándo Codex se detiene para pedir confirmación humana,sandbox_modey controla a qué archivos y redes puede acceder.

Las dos dimensiones se combinan de forma independiente; a continuación se muestra una configuración típica:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
approval_policy = "untrusted"   # Otras opciones: on-request, never, o { granular = { ... } }
approvals_reviewer = "user"     # "auto_review" usa revisión automática
sandbox_mode = "workspace-write"
allow_login_shell = false       # Desactivar el login shell (endurecimiento)

# Ejemplo de política de aprobación granular (por categoría de prompt)
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,   # las solicitudes de permisos usan fail-closed directamente
#   skill_approval = false         # los scripts de skill usan fail-closed directamente
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Permitir escritura en $TMPDIR
exclude_slash_tmp = false       # Permitir escritura en /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]   # Directorios de escritura adicionales
network_access = false          # Red externa denegada por defecto

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

Referencia rápida de combinaciones comunes

Escenarioapproval_policysandbox_modeDescripción
Desarrollo local diarioon-requestworkspace-writePreguntar antes de cada llamada a herramienta; lo más seguro
Automatización de CIneverworkspace-writeSin intervención humana; probar en sandbox
Entorno de plena confianzaneverdanger-full-accessDesactivar el sandbox; usar solo en entornos aislados
Escenarios de auditoría estrictauntrustedworkspace-writeTodas las operaciones de escritura requieren confirmación secundaria

Desactivar el sandbox (usar con precaución)

Cuando tu entorno ya tiene aislamiento a nivel de procesos, puedes desactivar el sandbox de Codex:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
sandbox_mode = "danger-full-access"

Enworkspace-writeEn el modo, algunos entornos harán que.git/y.codex/se mantenga en solo lectura. Esto significagit commitLos comandos como este aún requieren aprobación cuando se ejecutan fuera del sandbox. Para confirmar directamente dentro del sandbox, utilizarulesuna autorización explícita.


Política de variables de entorno del shell

shell_environment_policyControla qué variables de entorno se transfieren cuando Codex inicia subprocesos.Objetivo predeterminadoes "menos fuga de secretos + conservar las rutas necesarias para la tarea".

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
[shell_environment_policy]
inherit = "none"                            # Inicio limpio (recomendado)
set = { PATH = "/usr/bin", MY_FLAG = "1" } # Establecer variables explícitamente
ignore_default_excludes = false             # Conservar el filtrado predeterminado de KEY/SECRET/TOKEN
exclude = ["AWS_*", "AZURE_*"]              # Excluir además las variables que coinciden con globs
include_only = ["PATH", "HOME"]             # Transmitir solo la lista blanca (anula exclude)

Sintaxis de patrón: glob que no distingue mayúsculas de minúsculas,*coincide con cualquier carácter,?coincide con un solo carácter,[A-Z]es una clase de caracteres.

ignore_default_excludes = falseSe conservan los filtros integrados KEY/SECRET/TOKEN de Codex; se aplican antes de include/exclude.


Servidores MCP

El servidor MCP (Model Context Protocol) permite a Codex conectarse a conjuntos de herramientas externas.

La configuración completa de MCP se explica en ladocumentación de MCP, no se detalla en este artículo. Patrones comunes:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true

# Usa --config para desactivar temporalmente un servidor MCP
# codex --config mcp_servers.context7.enabled=false

Observabilidad y telemetría (OTel)

Codex admite exportar registros de ejecución a través de OpenTelemetry, desactivado por defecto. Para activarlo:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
[otel]
environment = "staging"   # Por defecto dev
exporter = "none"         # Opcional: otlp-http o otlp-grpc
log_user_prompt = false   # No exportar el contenido de los prompts del usuario (recomendado)

Elegir exportador HTTP

Ejemplo

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

Elegir exportador gRPC

Ejemplo

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

Tipos de eventos exportados

Codex emite eventos estructurados, incluyendo, entre otros:

EventoSignificado
codex.conversation_startsModelo, configuración de razonamiento, políticas de sandbox/aprobación
codex.api_requestIntentos de solicitudes API, estado, duración, errores
codex.sse_eventEventos de flujo SSE, conteo de tokens (en response.completed)
codex.websocket_request、codex.websocket_eventSolicitudes y mensajes WebSocket
codex.user_promptLongitud del prompt del usuario; el contenido se suprime (redact) por defecto
codex.tool_decisionDecisiones de llamada a herramientas: aprobado/rechazado, con origen en la configuración o en el usuario
codex.tool_resultDuración de la ejecución de la herramienta, éxito, fragmentos de salida

Cuandoexporter = "none"Cuando está desactivado, Codex sigue registrando los eventos en memoria pero no los envía.Al estar desactivado, se siguen activando lotes asíncronos por evento, y se hace flush al salir del proceso.

Métricas anónimas (activadas por defecto)

Codex, por defecto, envía periódicamente pequeñas cantidades de datos anónimos de uso y estado para detectar anomalías.No incluye PII。

Para desactivarlo por completo:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
[analytics]
enabled = false

Ocultar y mostrar eventos de razonamiento

En los registros de CI, la salida de razonamiento suele ser "ruidosa"; se puede desactivar globalmente:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
hide_agent_reasoning = true

Por el contrario, cuando necesites ver el razonamiento original del modelo:

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
show_raw_agent_reasoning = true

Actívalo solo cuando confirmes que tu flujo de trabajo permite exponer el razonamiento original. Algunos modelos (comogpt-oss) no emiten razonamiento original por sí mismos, por lo que esta configuración no tiene efecto.


Notificación externa (notify)

Cuando Codex completa un turno, puede activar un script externo para lograr notificaciones de escritorio, webhooks de chat, actualizaciones de estado de CI, etc.

Ejemplo

# Ruta de archivo: ~/.codex/config.toml
notify = ["python3", "/path/to/notify.py"]

El script recibe un parámetro JSON; los campos comunes son:

CampoSignificado
typeActualmente soloagent-turn-complete
thread-idID de sesión
turn-idID de turno
cwdDirectorio de trabajo
input-messagesLista de mensajes del usuario
last-assistant-messageÚltimo mensaje del asistente

Un ejemplo sencillo de script que llama a terminal-notifier:

Ejemplo

# Ruta de archivo: /path/to/notify.py
#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    # Procesar solo eventos de turno completado
    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())

Diferencia entre notify y tui.notifications

MecanismoCasos de uso adecuadosConfiguración clave
notifywebhooks, notificaciones de escritorio, hooks de CIPrograma externo
tui.notificationsNotificaciones integradas de TUIAdmite filtrar por tipo de evento
tui.notification_methodMétodo de notificación en la terminalauto / osc9 / bel
tui.notification_conditionCondiciones de activaciónunfocused / always

autoEn este modo, Codex prioriza la secuencia de escape de terminal OSC 9; algunos terminales la interpretan como notificación de escritorio; si no es compatible, se recurre a BEL (\x07)。


Comentarios e historial

Desactivar la recopilación de comentarios

Por defecto, Codex ofrece en la TUI/feedbackel comando. Para desactivarlo:

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
[feedback]
enabled = false

Después de desactivarlo/feedbackse mostrará un mensaje de desactivación y Codex rechazará enviar comentarios.

Historial (history.jsonl)

Codex escribe de forma predeterminada la transcripción de la sesión local en~/.codex/history.jsonl. Forma de desactivarlo:

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
[history]
persistence = "none"

Limitar el tamaño del archivo (cuando se supera, se descartan las entradas más antiguas y se comprime):

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
[history]
max_bytes = 104857600  # 100 MiB

Citas clicables (Clickable Citations)

Cuando la terminal o el editor lo soporta, Codex puede renderizar las referencias de archivos como enlaces clicables.

Ejemplo

# Ruta del archivo: ~/.codex/config.toml
# Opcional: vscode, cursor, windsurf, vscode-insiders, none
file_opener = "vscode"

Una vez configurado, las referencias/home/ejemplo/project/main.py:42se reescribirán comovscode://file/.../main.py:42, y al hacer clic en VS Code se podrá saltar a ellas.


Descubrimiento de instrucciones del proyecto (AGENTS.md)

Codex leeráAGENTS.md(y archivos relacionados), incorporando automáticamente las normas del proyecto en la "primera ronda" de la sesión.

Dos controles principales:

Clave de configuraciónFunciónValor típico
project_doc_max_bytesCuántos bytes como máximo se leen de cada AGENTS.mdAproximadamente 32 KiB por defecto
project_doc_fallback_filenamesNombre de archivo alternativo cuando falta AGENTS.mdComoCLAUDE.md

Opciones de la interfaz de terminal (TUI)

EjecutarcodexSin subcomando entrará en la TUI interactiva.[tui]Teclas comunes en la tabla:

TeclaFunciónValores opcionales
tui.notificationsActivar/desactivar notificaciones de TUI, se puede filtrar por tipo de eventoBooleano / arreglo de tipos de evento
tui.notification_methodMétodo de notificación de la terminalauto、osc9、bel
tui.notification_conditionCondición de activaciónunfocused、always
tui.animationsAnimaciones ASCII y efecto shimmertrue / false
tui.alternate_screenSi usar la pantalla alternativa (configurarlo en never conserva el historial de desplazamiento)auto、always、never
tui.show_tooltipsSi la página de bienvenida muestra consejos para principiantestrue / false

Tabla de referencia rápida de configuración común

Trata esta sección como una lista de referencia rápida para "consultar cuando lo olvides":

RequisitoUbicación de configuración / comando
Cambiar de modelo--model gpt-5.4omodel = "..."
Configuración por escenario--profile <name> + ~/.codex/<name>.config.toml
Cambiar temporalmente cualquier campo--config key=value(Sintaxis TOML)
Cambiar el endpoint de OpenAIopenai_base_url
Conectar proxy/proveedor propio[model_providers.<id>] + model_provider
Ollama local--oss + oss_provider
Desactivar la sandbox (usar con precaución)sandbox_mode = "danger-full-access"
Desactivar métricas anónimas[analytics] enabled = false
Desactivar historial[history] persistence = "none"
Desactivar comentarios[feedback] enabled = false
Notificaciones de escritorionotify = ["python3", "/path/to/notify.py"]

Preguntas frecuentes

¿El model_provider configurado a nivel de proyecto no tiene efecto?

Por razones de seguridad,model_provider、model_providers、profile、notifyclaves sensibles comose ignorarán en el .codex/config.toml a nivel de proyecto, y se imprimirá una advertencia al iniciar.

Mueve estas claves al nivel de usuario~/.codex/config.tomly listo.

¿Escribiste --config y no hubo cambios?

Verifica tres puntos: si el valor cumple con la sintaxis TOML (los arreglos usan[], las cadenas usan"", la anidación usa puntos); si el shell dividió varios valores con espacios como separadores; si el nombre de la clave está escrito correctamente. Abre~/.codex/logs/los registros más recientes para ver la cadena original que falló al analizarse.

¿Después de iniciar con Profile sigue usando el modelo predeterminado?

La causa más común: el archivo de perfil todavía usa la[profiles.<name>]tabla antigua, o el sufijo del nombre de archivo no es.config.toml. Desde 0.134.0 solo se reconoce~/.codex/<name>.config.tomlla forma.

¿Con el sandbox desactivado, git commit sigue requiriendo aprobación?

Desactivarsandbox_modeno afecta la política de aprobación.git commitComandos como git commit aún pueden, debido aapproval_policy = "on-request"provocar avisos; si deseas "confirmaciones totalmente automáticas", también debes configurar la política de aprobación ennever。

¿Se puede elegir la serie gpt-5 con un modelo personalizado?

Depende de sibase_urlel servicio al que apunta lo soporta. Codex en sí mismo no valida estrictamente el campomodel; lo clave es que tu proveedor pueda reconocerlo y responder.

Otras extensiones