Cómo configurar Codex config.toml: API personalizada, proxy y errores comunes

Codex guarda su configuración en un único archivo, config.toml: qué modelo usar, a qué API llamar y cuánto puede hacer el agente sin preguntar. El formato cambió varias veces en 2026, y muchas guías de principios de año muestran ajustes que ahora impiden que Codex se inicie.

Esta guía primero te ofrece una configuración funcional y, después, explica las partes que más suele cambiar la gente: perfiles, ajustes del proyecto, el entorno aislado y un proxy. Al final encontrarás una lista de los errores que probablemente veas y lo que significa cada uno. Verificado con la documentación de OpenAI y probado en Codex CLI 0.162.1 el 19 de octubre de 2026. Los ejemplos usan AIHubMix como proveedor; cualquier pasarela compatible con la API OpenAI Responses funciona igual.

En resumen

• El archivo es ~/.codex/config.toml o, en Windows, C:\Users\<you>\.codex\config.toml.
• Un proveedor personalizado necesita base_url, wire_api = "responses" y env_key. La clave de API va en una variable de entorno.
• Ahora los perfiles son archivos independientes, ~/.codex/<name>.config.toml, que se seleccionan con --profile <name>.
• El archivo .codex/config.toml de un repositorio solo funciona en proyectos de confianza y no puede cambiar el proveedor.
• Reinicia Codex después de cada edición; solo lee el archivo al iniciarse.

Dónde se encuentra config.toml

La configuración principal está en ~/.codex/config.toml. Tanto la CLI como la extensión del IDE la leen. Si el archivo aún no existe, créalo.

Hay otros dos lugares que pueden añadir ajustes:

• Archivos de perfil, ~/.codex/<name>.config.toml, que solo se usan cuando inicias Codex con --profile <name>.
• Archivos del proyecto, .codex/config.toml dentro de un repositorio, para compartir los ajustes que quiera un equipo.

Si ejecutas Codex en WSL2 en Windows, leerá el directorio personal de Linux (/home/<you>/.codex/config.toml), no el de Windows. Si está definida CODEX_HOME, Codex usará esa carpeta en lugar de ~/.codex.

Una configuración mínima funcional

Este archivo completo ~/.codex/config.toml envía las solicitudes de Codex a AIHubMix:

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

• model es el ID del modelo al que llamar, y model_reasoning_effort es su nivel de razonamiento predeterminado.
• model_provider debe coincidir con el nombre de [model_providers.<name>]. No uses openai, ollama ni lmstudio; esos nombres están reservados para los proveedores integrados de Codex.
• base_url es la dirección de la API del proveedor. wire_api = "responses" es el único valor que Codex acepta ahora.
• env_key es el nombre de una variable de entorno, no la clave en sí.

Luego, define esa variable con una clave de la consola de AIHubMix:

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

Abre una terminal nueva, inicia codex y pregúntale cualquier cosa. Si responde, el proveedor funciona. No importa si has iniciado sesión en Codex: la clave de codex login nunca se envía a un proveedor personalizado.

Perfiles: un archivo por configuración

Un perfil contiene solo los ajustes que difieren de tu configuración principal, como un razonamiento más profundo y un entorno aislado de solo lectura para revisar código. Cada perfil tiene su propio archivo junto a config.toml, con las claves en el nivel superior:

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

Esto cambió en Codex 0.134.0. Las guías anteriores incluían perfiles dentro de config.toml como tablas [profiles.review] y seleccionaban uno con profile = "review". Ahora Codex se niega a iniciarse si se usa ese selector. Si queda una tabla [profiles.review] por sí sola, se ignora sin avisar, así que sus ajustes dejan de funcionar sin que te des cuenta. Para migrar, mueve las claves de cada tabla a ~/.codex/<name>.config.toml y luego elimina la tabla y la línea profile = .... Encontrarás más detalles en la guía de configuración avanzada de OpenAI.

Configuración del proyecto: .codex/config.toml

Un archivo .codex/config.toml en un repositorio permite que un equipo comparta un modelo, un nivel de razonamiento o un modo de entorno aislado predeterminados. Codex solo lo lee en proyectos marcados como de confianza en tu propio ~/.codex/config.toml:

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Un archivo de proyecto no puede cambiar el destino de las solicitudes. Codex ignora allí model_provider, model_providers, openai_base_url, profile, notify y algunas otras claves, y muestra una advertencia cuando lo hace. Mantén el proveedor en ~/.codex/config.toml. El proyecto aún puede seleccionar el modelo; la solicitud se enviará a tu propio proveedor.

Qué ajuste prevalece

Cuando se define la misma clave en más de un lugar, los conceptos básicos de configuración de OpenAI indican este orden, de mayor a menor prioridad:

1. Opciones de línea de comandos, incluidas las anulaciones -c
2. El .codex/config.toml del proyecto
3. El perfil seleccionado con --profile
4. Tu ~/.codex/config.toml
5. La configuración del sistema, /etc/codex/config.toml
6. Los valores predeterminados integrados de Codex

Ten en cuenta que el archivo del proyecto tiene prioridad sobre el perfil. Si un ajuste del perfil parece no surtir efecto, comprueba si el .codex/config.toml del repositorio define la misma clave.

Para cambiar un ajuste solo durante una ejecución, usa -c:

codex -c model_reasoning_effort=high

Entorno aislado y aprobaciones

Dos claves controlan lo que Codex hace por su cuenta. sandbox_mode define a qué puede acceder con sus comandos, y approval_policy determina cuándo se detiene para preguntarte.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

Los dos ajustes son independientes: never evita las preguntas, pero no flexibiliza el entorno aislado. Con workspace-write, los comandos no pueden acceder a la red hasta que configures network_access = true.

Detrás de un proxy

Codex no tiene un ajuste de proxy en config.toml. Usa las variables de entorno estándar:

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

La documentación de OpenAI no las menciona, así que se probaron en Codex 0.162.1: las solicitudes, incluidas las dirigidas a un proveedor personalizado, pasaron por HTTPS_PROXY (o ALL_PROXY), mientras que se accedió directamente a los hosts incluidos en NO_PROXY. No se admiten archivos PAC, así que introduce directamente la dirección del proxy. Si el proxy de tu empresa usa su propio certificado raíz, indica su ubicación en CODEX_CA_CERTIFICATE, como se describe en la referencia de variables de entorno.

Más modelos en /model

El selector /model solo muestra los modelos de OpenAI. Para elegir desde allí modelos de GLM, Claude, Gemini o DeepSeek, añade un catálogo de modelos: un archivo JSON cuyo nombre se indica mediante la clave de nivel superior model_catalog_json. Coloca esa clave antes de la primera línea [table]; de lo contrario, TOML la considera parte de esa tabla y Codex la ignora.

El catálogo sustituye la lista integrada y cada entrada necesita una larga serie de campos, así que es mejor generarlo que escribirlo a mano. La guía de AIHubMix para Codex CLI incluye un script que crea uno a partir de los 30 modelos principales de AIHubMix. Es posible que la aplicación de escritorio siga ocultando los modelos personalizados en su selector (openai/codex#19694), así que cambia de modelo desde la terminal.

Errores comunes y su significado

Estos son los mensajes que mostró Codex 0.162.1 para cada error.

legacy profile = "..." config is no longer supported
Tu config.toml todavía tiene la línea antigua profile = "...". Mueve el perfil a su propio archivo como se explica arriba. Si ejecutas --profile x mientras existe una tabla antigua [profiles.x], aparece un error similar: --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
Codex ya no admite la API Chat Completions. Cámbialo a wire_api = "responses". Un proveedor que solo ofrezca Chat Completions no funcionará sin un proxy de traducción.

model_providers contains reserved built-in provider IDs
Has llamado al proveedor openai, ollama o lmstudio. Cambia el nombre de la tabla y de model_provider por otro.

approval_policy = "untrusted" is no longer supported
Elimina la línea o usa on-request.

Missing environment variable: AIHUBMIX_API_KEY
La variable indicada en env_key no está definida en la terminal desde la que se inició Codex. Abre una terminal nueva o ejecuta source ~/.zshrc y vuelve a iniciar Codex.

401 Unauthorized after a few "Reconnecting..." lines
La solicitud se envió sin una clave. Comprueba que la tabla del proveedor incluya env_key. El inicio de sesión guardado en auth.json no sirve para proveedores personalizados.

Model metadata for ... not found. Defaulting to fallback metadata
Codex no tiene ajustes integrados para ese modelo, lo cual es normal en modelos que no son de OpenAI. Las solicitudes siguen funcionando. Añade un catálogo de modelos si quieres tener los ajustes adecuados y ver el modelo en /model.

Ignored unsupported project-local config keys
El archivo .codex/config.toml de un repositorio define una clave que solo funciona en tu propia configuración, normalmente model_provider. Muévela a ~/.codex/config.toml.

missing field base_instructions
A una entrada de tu catálogo de modelos le falta un campo obligatorio, así que Codex rechaza el archivo completo. Vuelve a generar el catálogo con el script en lugar de editarlo a mano.

Cuando un ajuste no surte efecto

• Reinicia Codex después de editar.
• Asegúrate de que las claves de nivel superior aparezcan antes de la primera línea [table].
• Comprueba el .codex/config.toml del repositorio; prevalece sobre tu perfil.
• Busca si queda alguna tabla [profiles.x].
• Ejecuta codex doctor, que comprueba la instalación, la configuración y el inicio de sesión.

Si quieres usar modelos de OpenAI, Anthropic, Google, Zhipu, DeepSeek y otros en Codex con una sola clave, AIHubMix los ofrece a través de la API Responses en https://aihubmix.com/v1. Empieza con la configuración mínima de arriba y añade un catálogo de modelos cuando quieras cambiar de modelo desde /model.

Preguntas frecuentes

¿Dónde está el archivo config.toml de Codex?
En ~/.codex/config.toml en macOS y Linux, y en C:\Users<you>.codex\config.toml en Windows. Si CODEX_HOME está definido, el archivo estará en esa carpeta.

¿Tengo que reiniciar Codex después de cambiar config.toml?
Sí. Codex lee el archivo al iniciarse, así que cierra y vuelve a abrir la sesión de terminal o la aplicación.

¿Por qué Codex dice «la configuración de perfiles heredada ya no es compatible»?
Codex 0.134.0 dejó de admitir los perfiles definidos dentro de config.toml. Mueve cada perfil a ~/.codex/name.config.toml, elimina las líneas antiguas e inicia Codex con --profile name.

¿Puedo seguir usando wire_api = "chat"?
No. Codex solo acepta wire_api = "responses". Un proveedor que solo admita Chat Completions necesita un proxy que traduzca a la API Responses.

¿Por qué mi proveedor personalizado devuelve 401 si ya inicié sesión en Codex?
La clave de inicio de sesión de auth.json no se envía a los proveedores personalizados. Añade env_key a la tabla del proveedor y configura esa variable en tu terminal.

¿Codex usa HTTPS_PROXY?
Sí. En una prueba con Codex 0.162.1, las solicitudes pasaron por HTTPS_PROXY y omitieron los hosts incluidos en NO_PROXY. No se admiten archivos PAC.

¿Por qué se ignora model_provider en el archivo .codex/config.toml de mi proyecto?
Los archivos del proyecto no pueden cambiar el destino de las solicitudes, así que un repositorio no puede redirigir tu tráfico. Añade el proveedor a ~/.codex/config.toml; el archivo del proyecto aún puede definir el modelo.

Fuentes

• Conceptos básicos de configuración, OpenAI
• Configuración avanzada, OpenAI
• Referencia de configuración, OpenAI
• Guía de integración de Codex CLI, AIHubMix
• Configuración de proxy de Codex CLI: SOCKS, HTTP y redes corporativas, Daniel Vaughan