Custom Provider en Codex: API Key, Base URL y config.toml

Una clave API, una Base URL y un nombre de modelo no forman una configuración universal de Codex. Los tres valores tienen que describir la misma ruta. Si la clave pertenece a OpenAI, la URL a un gateway independiente y Codex conserva otra sesión autenticada, un 401 no te dirá qué contrato ha fallado.

Antes de editar TOML, elige uno de estos casos:

• OpenAI Platform emite la clave y factura el trabajo local: inicia sesión en Codex con la OpenAI API key.
• Conservas el provider openai integrado, pero necesitas un proxy, router o endpoint regional compatible: usa openai_base_url.
• Otro servicio controla credenciales, modelos, saldo y soporte: crea un [model_providers.<id>] propio.
• Un endpoint local bajo tu control no requiere autenticación: usa un provider sin env_key ni requires_openai_auth.

Esta guía se contrastó el 1 de septiembre de 2026 con Advanced Configuration y Authentication de OpenAI. El schema de Codex cambia; comprueba la documentación actual antes de adoptar un fragmento antiguo.

Crea la ficha de la ruta

Anota cinco decisiones antes del primer intento.

Si una fila pertenece a otro servicio, no continúes. “Compatible con OpenAI” puede describir una forma de request, pero no demuestra por sí solo la autenticación, Responses, los eventos de streaming, tool calls ni acceso a un modelo concreto.

Login con una OpenAI API key

OpenAI documenta el login de ChatGPT y el login con API key como métodos distintos para el trabajo local de Codex. En CLI puedes pasar la clave por stdin para no escribirla como argumento:

bash
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

Esta ruta pertenece a OpenAI Platform. El consumo sigue la organización y el project de API y se factura con precios de API, no con el uso incluido del plan ChatGPT. Codex cloud sigue requiriendo login con ChatGPT, de modo que una API key no sustituye todas las funciones cloud.

El credential cache puede vivir en ~/.codex/auth.json o en el almacén de credenciales del sistema. Si se usa el archivo, trátalo como una contraseña: no lo subas a Git ni lo pegues en issues, chats o tickets. Consulta codex login status en lugar de compartir su contenido.

Si todavía estás decidiendo qué cuenta debe pagar, usa primero Codex API key frente a suscripción.

Cambiar solo la Base URL del provider OpenAI integrado

Cuando sigues usando el provider OpenAI y su autenticación, pero la ruta pasa por un proxy o endpoint admitido, la opción más pequeña es:

toml
# ~/.codex/config.toml
openai_base_url = "https://proxy.example.com/v1"

No crees [model_providers.openai]. openai, ollama y lmstudio son IDs reservados de providers integrados y un custom block no puede sustituirlos con el mismo nombre.

openai_base_url tampoco certifica cualquier gateway. Si el gateway emite su propio token, usa saldo independiente, redefine los modelos o asume soporte, estás ante otro provider. Separarlo evita mezclar el estado de login de OpenAI con una credencial de tercero.

Configurar un provider con su propia clave

El routing del provider pertenece al archivo de usuario ~/.codex/config.toml:

toml
model = "EXACT_PROVIDER_MODEL_ID"
model_provider = "company_gateway"

[model_providers.company_gateway]
name = "Company gateway"
base_url = "https://gateway.example.com/v1"
env_key = "COMPANY_GATEWAY_API_KEY"
wire_api = "responses"

Guarda el secreto en el entorno que inicia Codex:

bash
export COMPANY_GATEWAY_API_KEY="replace-with-provider-key"

El valor de env_key es el nombre de la variable, no la clave. Si exportas la variable en un terminal y abres el IDE o la app de escritorio desde otro entorno, el proceso puede no recibirla. Comprueba solo su presencia:

bash
if [ -n "${COMPANY_GATEWAY_API_KEY:-}" ]; then
  echo "provider key is available"
else
  echo "provider key is missing"
fi

No existe una regla universal que obligue a añadir /v1. Usa la raíz y el model ID exactos que documente ese provider para la misma cuenta.

Elige una sola fuente de autenticación

La documentación de alternative model providers separa tres contratos:

1. requires_openai_auth = true usa la autenticación OpenAI e ignora env_key. Sirve cuando un LLM proxy acepta explícitamente OpenAI auth.
2. env_key = "PROVIDER_VARIABLE" lee la clave propia del provider desde una variable de entorno.
3. Si omites ambos, Codex supone que el endpoint no necesita auth; limítalo a un servicio local controlado que realmente funcione así.

Advanced Configuration también admite un comando [model_providers.<id>.auth] para obtener bearer tokens de corta duración. No lo combines con env_key, requires_openai_auth ni el bearer token experimental. Varias fuentes de credenciales no crean un fallback fiable: vuelven ambiguo el siguiente 401.

Por qué el project config ignora estas claves

Un repositorio de confianza puede cargar .codex/config.toml, pero no puede redirigir provider y auth de la máquina. OpenAI enumera en su documentación de project config varias claves que Codex ignora en esa capa:

• openai_base_url
• model_provider
• model_providers

Muévelas a ~/.codex/config.toml. No es un parse error, sino una frontera de seguridad que impide que un repositorio envíe silenciosamente tu contexto y tus credenciales a otro endpoint.

Si el archivo de usuario tampoco parece surtir efecto, revisa el comando real de inicio, overrides de CLI con --config y el profile seleccionado. La precedencia elige entre valores permitidos; no convierte en válida una clave restringida al proyecto.

Verifica la petición real, no solo /v1/models

Que el bloque se analice correctamente no es una prueba end-to-end. Un 200 en /v1/models solo valida ese endpoint; aún faltan la ruta Responses, auth, streaming y tools.

1. Haz copia del user config y reduce el bloque nuevo al mínimo.
2. Confirma que provider ID, Base URL, model ID, wire API y emisor de credencial describen un solo servicio.
3. Inicia Codex desde el mismo entorno donde existe la variable.
4. Envía una tarea breve sin código ni datos personales, por ejemplo pedir exactamente ROUTE_OK.
5. Tras el texto, prueba por separado streaming, tool calls, contexto largo o web search si forman parte del trabajo real.

Una respuesta de texto no demuestra “compatibilidad completa”. Cuando la petición ya llega al provider correcto, seguir cambiando la precedencia del config no arreglará permisos de cuenta ni capacidades del adapter.

Usa el resultado para encontrar al siguiente owner

Para soporte basta un paquete saneado: versión de Codex, sistema, superficie CLI/IDE/desktop, provider ID, hostname de Base URL, model ID, wire_api, error completo, status, request ID y timestamp. Elimina API key, Authorization header, auth.json, código privado y datos de clientes.

La configuración está terminada cuando puedes nombrar la capa cargada, el emisor de la credencial, la Base URL receptora, el namespace del modelo y el siguiente owner de un fallo. Si una respuesta sigue sin estar clara, vuelve a un provider, una fuente de auth y una petición no sensible. Esa ruta pequeña se puede diagnosticar; una plantilla “universal” compuesta con ejemplos de varios servicios, no.