Conéctate a una puerta de enlace

Conecta Codex a una puerta de enlace de LLM usando la URL de la puerta de enlace, el alias del modelo y la credencial o el resolvedor de tokens que proporcione tu organización.

Comprueba si ya existe una configuración

Antes de añadir nada, comprueba si tu administrador ya configuró Codex.

• Para la CLI, revisa el perfil seleccionado y ejecuta codex doctor. Después del inicio, usa /status para confirmar el modelo y el proveedor activos.
• Para la aplicación de macOS, revisa ~/.codex/config.toml o la configuración administrada que distribuye tu organización.
• Para la aplicación de Windows, revisa %USERPROFILE%\.codex\config.toml o la configuración del sistema que distribuye tu organización.

Si el proveedor de la puerta de enlace y el modelo esperados ya están activos, continúa en Verifica la conexión.

Obtén los datos de conexión de tu puerta de enlace

Instala la CLI de Codex o la aplicación de escritorio aprobada por tu organización. Para configurar Codex por tu cuenta, solicita estos valores al equipo responsable de la puerta de enlace:

• La URL base HTTPS de la puerta de enlace, incluida su ruta de API, como https://gateway.example.com/v1.
• El nombre del modelo y el ID del proveedor que debes usar.
• Tu credencial de puerta de enlace con alcance limitado y su variable de entorno, o un resolvedor de tokens instalado y su configuración.
• Cualquier archivo de catálogo de modelos requerido y su ruta local absoluta.

Configura el proveedor

Abre config.toml en ~/.codex/config.toml en macOS o Linux, o en %USERPROFILE%\.codex\config.toml en Windows.

Integra este ejemplo en tu configuración existente y sustituye la URL y el modelo por los valores proporcionados por tu administrador. No añadas una segunda definición de una clave o tabla existente. Este ejemplo usa gpt-6-sol; úsalo sin un catálogo personalizado solo si tu administrador confirma que tu versión de Codex reconoce el modelo y que sus metadatos incluidos coinciden con la puerta de enlace.

model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"

Si tu administrador proporciona un catálogo de modelos, guárdalo localmente y añade model_catalog_json antes de la primera tabla TOML, usando la ruta absoluta del archivo. Los alias personalizados necesitan metadatos de catálogo coincidentes. Por ejemplo:

model_catalog_json = "/etc/codex/gateway-models.json"

Usa el nombre del modelo y el catálogo que tu administrador proporcione conjuntamente. No añadas una ruta de catálogo a menos que el archivo exista en esa ubicación.

enterprise-gateway es un ID de proveedor de ejemplo. Usa el mismo ID en model_provider, [model_providers.<id>] y [model_providers.<id>.auth]. Este ejemplo desactiva la búsqueda web para la prueba de conexión inicial; tu administrador debe verificar la compatibilidad de esta función antes de habilitarla.

Haz que tu credencial de puerta de enlace esté disponible como CODEX_GATEWAY_API_KEY en el entorno del proceso que inicia Codex, usando el mecanismo de distribución de secretos de tu organización. No incluyas la credencial en TOML ni en un repositorio. Una variable establecida en una terminal puede no estar disponible para una aplicación iniciada desde el escritorio.

Usa un encabezado de autenticación personalizado

Si tu puerta de enlace requiere un encabezado como X-API-Key en lugar de un token de portador, sustituye env_key en la tabla del proveedor por:

env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }

Usa el nombre exacto del encabezado que proporcione tu administrador. Codex lee el valor de la variable de entorno indicada; mantén la credencial fuera del archivo de configuración. Consulta la referencia de configuración para obtener información sobre model_providers.<id>.env_http_headers.

Usa un asistente de credenciales de la organización

Si tu administrador proporciona autenticación mediante comandos, usa el asistente instalado por él y su configuración en lugar de env_key. No configures ambos mecanismos. El asistente debe existir en tu máquina; Codex no lo instala. Por ejemplo, sustituye el ajuste de ejemplo env_key por esta tabla, usando la ruta del resolvedor y los argumentos que proporcione tu administrador:

[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

La referencia de autenticación de proveedores personalizados define el comando, los argumentos, el tiempo de espera, el intervalo de actualización y el contrato de salida del token. Pregunta a tu administrador cómo renovar el inicio de sesión si el asistente ya no puede obtener un token.

Usa rutas absolutas resueltas para los ejecutables de los asistentes y los archivos de catálogo.

Configura la CLI

La CLI lee ~/.codex/config.toml de forma predeterminada en macOS o Linux. Después de guardar los ajustes del proveedor, ejecuta codex. Dentro de WSL, usa la configuración y las rutas de Linux salvo que CODEX_HOME apunte a otra ubicación.

Configura la aplicación de macOS

La aplicación de macOS lee el mismo ~/.codex/config.toml. Después de guardar los ajustes del proveedor, reinicia la aplicación. Si usas una variable de entorno para la credencial, asegúrate de que esté disponible para el proceso de la aplicación.

Configura la aplicación de Windows

Coloca los ajustes del proveedor en %USERPROFILE%\.codex\config.toml y luego reinicia la aplicación. Para la autenticación mediante comandos, usa el resolvedor instalado por tu administrador. Por ejemplo, sustituye la tabla de autenticación de Unix por:

[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

En TOML para Windows, las cadenas literales entre comillas simples conservan las barras invertidas. Sustituye también las rutas de catálogo de Unix, por ejemplo por 'C:\ProgramData\OpenAI\Codex\models.json', usando la ruta real que tu administrador haya proporcionado.

Configura los MCP servers y los plugins por separado. Una credencial de puerta de enlace de modelos no autoriza el acceso a tus herramientas ni a los sistemas conectados.

Verifica la conexión

Reinicia el cliente después de cambiar la configuración. En la CLI, inicia codex y usa /status para revisar el modelo y el proveedor activos. En la aplicación de escritorio, comprueba el modelo seleccionado y la configuración.

Envía este prompt en una tarea nueva:

Reply with exactly: gateway-ok

La respuesta esperada es gateway-ok. Una respuesta por sí sola no demuestra qué ruta la procesó: pide a tu administrador que confirme que la puerta de enlace registró tu usuario, el alias del modelo y la ruta prevista hacia el proveedor de origen. No identifiques el modelo preguntándole su nombre.

Esto verifica una conexión inicial. Los administradores también deben completar las comprobaciones de implementación para el streaming, las herramientas y los turnos posteriores.

Soluciona problemas de conexión

Al solicitar ayuda, incluye el mensaje de error después de eliminar los tokens y los prompts confidenciales.

Usa una implementación de puerta de enlace existente

Si tu organización ya usa una puerta de enlace con otra herramienta de programación, es posible que puedas reutilizar su ruta de red, sus registros y el acceso a proveedores. Trabaja con el equipo responsable de la puerta de enlace para configurar y probar una conexión de Codex:

1. Identifica la URL de la puerta de enlace existente, el mecanismo de credenciales, los encabezados requeridos, las rutas de modelos y el método de distribución de la configuración.
2. Pide al equipo responsable de la puerta de enlace que confirme que esta admite el comportamiento de la API que requiere Codex y que configure una ruta de modelo de Codex.
3. Obtén una credencial de puerta de enlace con alcance limitado o un asistente de credenciales, el nombre del modelo y cualquier catálogo de modelos requerido del equipo responsable de la puerta de enlace.
4. Configura Codex con esos valores.
5. Verifica la conexión en la CLI o en la aplicación de escritorio que planees usar. Pide al equipo responsable de la puerta de enlace que complete las comprobaciones de streaming, herramientas y turnos posteriores.
6. Una vez superada la prueba piloto, sigue Implementa Codex mediante una puerta de enlace para distribuir la configuración a otros desarrolladores.

Para consultar la lista de comprobación de migración para administradores y la correspondencia de configuración, consulta Reutiliza una implementación de puerta de enlace existente.

Documentación relacionada

• CLI de Codex
• MCP servers
• Plugins