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.
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
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
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
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
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
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:
| Archivo | Función | ¿Sensible? |
|---|---|---|
| config.toml | Configuración principal local; todas las personalizaciones van aquí | no |
| auth.json | Credenciales basadas en archivo (si no se usa el llavero del sistema) | Sí, se recomienda permiso 600 |
| history.jsonl | Historial 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
# 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 ignoradas | Motivo |
|---|---|
| openai_base_url、chatgpt_base_url | Evita redirigir credenciales / cambiar metadatos del host |
| apps_mcp_product_sku | Afecta la identificación del producto Codex Apps |
| model_provider、model_providers | Evita reemplazar credenciales / identidad del proveedor |
| notify | Evita ejecutar comandos locales arbitrarios en la máquina |
| profile、profiles | No se puede seleccionar un perfil de configuración a nivel de proyecto |
| experimental_realtime_ws_base_url、otel | Telemetrí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:
| Formato | Ubicación | Caso de uso ideal |
|---|---|---|
| hooks.jsonArchivo | Mismo directorio que config.toml | Amigable con la cadena de herramientas JSON, fácil de reutilizar |
| En línea[[hooks.*]]tabla | Dentro de config.toml | Toda 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
# 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
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
# 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
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
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
# Proveedor local predeterminado; opciones: ollama o lmstudio
oss_provider = "ollama"
Ejemplo de uso:
Ejemplo
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
[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
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
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
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
| Escenario | approval_policy | sandbox_mode | Descripción |
|---|---|---|---|
| Desarrollo local diario | on-request | workspace-write | Preguntar antes de cada llamada a herramienta; lo más seguro |
| Automatización de CI | never | workspace-write | Sin intervención humana; probar en sandbox |
| Entorno de plena confianza | never | danger-full-access | Desactivar el sandbox; usar solo en entornos aislados |
| Escenarios de auditoría estricta | untrusted | workspace-write | Todas 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
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
[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
[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
[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
exporter = { otlp-http = {
endpoint = "https://otel.example.com/v1/logs",
protocol = "binary",
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
Elegir exportador gRPC
Ejemplo
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:
| Evento | Significado |
|---|---|
| codex.conversation_starts | Modelo, configuración de razonamiento, políticas de sandbox/aprobación |
| codex.api_request | Intentos de solicitudes API, estado, duración, errores |
| codex.sse_event | Eventos de flujo SSE, conteo de tokens (en response.completed) |
| codex.websocket_request、codex.websocket_event | Solicitudes y mensajes WebSocket |
| codex.user_prompt | Longitud del prompt del usuario; el contenido se suprime (redact) por defecto |
| codex.tool_decision | Decisiones de llamada a herramientas: aprobado/rechazado, con origen en la configuración o en el usuario |
| codex.tool_result | Duració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
[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
hide_agent_reasoning = true
Por el contrario, cuando necesites ver el razonamiento original del modelo:
Ejemplo
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
notify = ["python3", "/path/to/notify.py"]
El script recibe un parámetro JSON; los campos comunes son:
| Campo | Significado |
|---|---|
| type | Actualmente soloagent-turn-complete |
| thread-id | ID de sesión |
| turn-id | ID de turno |
| cwd | Directorio de trabajo |
| input-messages | Lista de mensajes del usuario |
| last-assistant-message | Último mensaje del asistente |
Un ejemplo sencillo de script que llama a terminal-notifier:
Ejemplo
#!/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
| Mecanismo | Casos de uso adecuados | Configuración clave |
|---|---|---|
| notify | webhooks, notificaciones de escritorio, hooks de CI | Programa externo |
| tui.notifications | Notificaciones integradas de TUI | Admite filtrar por tipo de evento |
| tui.notification_method | Método de notificación en la terminal | auto / osc9 / bel |
| tui.notification_condition | Condiciones de activación | unfocused / 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
[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
[history]
persistence = "none"
Limitar el tamaño del archivo (cuando se supera, se descartan las entradas más antiguas y se comprime):
Ejemplo
[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
# 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ón | Función | Valor típico |
|---|---|---|
| project_doc_max_bytes | Cuántos bytes como máximo se leen de cada AGENTS.md | Aproximadamente 32 KiB por defecto |
| project_doc_fallback_filenames | Nombre de archivo alternativo cuando falta AGENTS.md | ComoCLAUDE.md |
Opciones de la interfaz de terminal (TUI)
EjecutarcodexSin subcomando entrará en la TUI interactiva.[tui]Teclas comunes en la tabla:
| Tecla | Función | Valores opcionales |
|---|---|---|
| tui.notifications | Activar/desactivar notificaciones de TUI, se puede filtrar por tipo de evento | Booleano / arreglo de tipos de evento |
| tui.notification_method | Método de notificación de la terminal | auto、osc9、bel |
| tui.notification_condition | Condición de activación | unfocused、always |
| tui.animations | Animaciones ASCII y efecto shimmer | true / false |
| tui.alternate_screen | Si usar la pantalla alternativa (configurarlo en never conserva el historial de desplazamiento) | auto、always、never |
| tui.show_tooltips | Si la página de bienvenida muestra consejos para principiantes | true / 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":
| Requisito | Ubicació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 OpenAI | openai_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 escritorio | notify = ["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