Configuración de Codex CLI

Codex CLI se personaliza mediante archivos de configuración. Esta sección presenta la estructura del archivo de configuración, las distintas opciones de configuración y cómo ajustarlas según tus necesidades.

Ubicación del archivo de configuración

El archivo de configuración de Codex se encuentra en el directorio principal del usuario en~/.codex/config.toml：

~/.codex/config.toml

Si el archivo no existe, debes crearlo manualmente. Codex creará un archivo de configuración predeterminado al iniciarse por primera vez.

Después de modificar la configuración, debes reiniciar Codex para que los cambios surtan efecto.

Estructura del archivo de configuración

Un archivo de configuración completo puede incluir las siguientes secciones:

Codex CLI 配置结构图
Figura: Estructura de configuración de Codex CLI

Ejemplo completo de configuración

# ~/.codex/config.toml

# Configuración básica
[model]
default = "o4-mini" # Modelo utilizado por defecto

# Configuración de TUI
[tui]
alternate_screen = "auto" # Modo de pantalla alternativa: auto/always/never

# Configuración de habilidades
[skills]
enabled = true

# Interruptores de funciones
[features]
js_repl = false # Si habilitar JavaScript REPL

# Configuración del servidor MCP
[mcp_servers]

# Configuración de notificaciones
[notify]
enabled = false

Configuración del modelo

Codex admite varios modelos; puedes elegir según las necesidades de la tarea:

Elemento de configuraciónTipoDescripción
model.defaultstringModelo utilizado por defecto
model.reasoning_effortstringIntensidad de razonamiento: low/medium/high

Modelos disponibles

Los modelos disponibles en Codex CLI incluyen:

  • o4-mini- Rápido y eficiente, adecuado para tareas simples
  • o4-mini-high- Versión de alto razonamiento de o4-mini
  • o3- Potente capacidad de razonamiento
  • o3-pro- Versión profesional de o3

Los distintos modelos tienen diferentes velocidades y precios; elegir el modelo adecuado puede optimizar la experiencia de uso y los costos.

Configuración de TUI

Configuraciones relacionadas con la interfaz de usuario de terminal:

Elemento de configuraciónTipoDescripciónValor predeterminado
tui.alternate_screenstringModo de pantalla alternativa: auto/always/neverauto
tui.widthnumberAncho de terminal0 (automático)
tui.heightnumberAlto de terminal0 (automático)

Explicación del modo de pantalla alternativa

  • auto- Detección automática; se desactiva automáticamente en multiplexores de terminal como Zellij
  • always- Usar siempre la pantalla alternativa (experiencia predeterminada)
  • never- No usar nunca la pantalla alternativa (conserva el historial de desplazamiento)

Anulación en tiempo de ejecución

Puedes anular esta configuración en tiempo de ejecución mediante argumentos de línea de comandos:

Anulación de configuración mediante línea de comandos

# Deshabilitar el modo de pantalla alternativa
codex --no-alt-screen

Configuración de habilidades

Las habilidades (Skills) son el mecanismo de extensión de Codex que te permite personalizar flujos de trabajo:

Elemento de configuraciónTipoDescripción
skills.enabledbooleanSi habilitar el sistema de habilidades
skills.directorystringDirectorio de archivos de habilidades

Directorio de habilidades personalizado

Configurar el directorio de habilidades

[skills]
enabled = true
directory = "~/my-codex-skills"

Configuración del servidor MCP

Los servidores MCP (Model Context Protocol) permiten que Codex se integre con herramientas y servicios externos:

Configurar el servidor MCP

[mcp_servers.docs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]

# Configuración de permisos de herramientas
[mcp_servers.docs.tools.search]
approval_mode = "approve"

Permisos de herramientas MCP

Puedes establecer permisos individualmente para las herramientas de cada servidor MCP:

  • approve- Aprobación automática, sin preguntar
  • deny- Rechazo automático
  • ask- Preguntar antes de cada ejecución (predeterminado)

Ten cuidado al configurar servidores MCP; asegúrate de habilitar solo las herramientas en las que confías.

Interruptores de funciones

Habilitar o deshabilitar funciones específicas de Codex:

Elemento de configuraciónTipoDescripción
features.js_replbooleanHabilitar JavaScript REPL
features.js_repl_tools_onlybooleanLimitar solo a la herramienta js_repl

Configuración de JavaScript REPL

Habilitar JavaScript REPL

[features]
js_repl = true

También puedes especificar la ruta de Node.js:

Especificar la ruta de Node.js

js_repl_node_path = "/usr/local/bin/node"

Configuración de notificaciones

Codex puede enviar notificaciones cuando se completa una tarea:

Elemento de configuraciónTipoDescripción
notify.enabledbooleanHabilitar notificaciones

Configurar hooks de notificación

Puedes configurar scripts de notificación personalizados mediante variables de entorno:

CODEX_NOTIFY_HOOK=/path/to/your/notify-script.sh

Base de datos de estado SQLite

Codex utiliza SQLite para almacenar el estado interno:

Variable de entornoDescripciónValor predeterminado
CODEX_SQLITE_HOMEDirectorio de la base de datos SQLiteIgual que CODEX_HOME

Configurar el directorio de SQLite

export CODEX_SQLITE_HOME=/path/to/sqlite
codex

Configuración de registros (logs)

Codex utiliza env_logger de Rust; puedes configurar el nivel de registro:

Configurar la salida de registros

# Ver registros
tail -f ~/.codex/log/codex-tui.log

# Establecer el nivel de registro
RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info codex
Nivel de registroDescripción
errorMostrar solo errores
warnMostrar advertencias y errores
infoMostrar información general, advertencias y errores
debugMostrar información de depuración
traceMostrar información de seguimiento detallada

De forma predeterminada, el nivel de registro en modo TUI es info, y en modo no interactivo (exec) el nivel predeterminado es error.

Configuración del modo de planificación

Configurar el comportamiento de Codex en el modo de planificación:

Configurar el modo de planificación

# Establecer la intensidad de razonamiento predeterminada del modo de planificación
# Valores posibles: low/medium/high/none
plan_mode_reasoning_effort = "medium"

Ejemplos comunes de configuración

Configuración básica

Configuración mínima

# Usar la configuración predeterminada
# Codex ya proporciona valores predeterminados razonables

Configuración de alto rendimiento

Configuración de optimización de rendimiento

[model]
default = "o4-mini"

[tui]
alternate_screen = "always"

[features]
js_repl = true

Configuración para desarrolladores

Configuración para desarrolladores

[model]
default = "o4-mini"
reasoning_effort = "high"

[tui]
alternate_screen = "never"

[skills]
enabled = true
directory = "~/codex-skills"
Otras extensiones