Conecta Codex a la puerta de enlace de modelos de tu organización con la configuración del proveedor y el método de autenticación que te indique el equipo responsable de la puerta de enlace. La puerta de enlace dirige las solicitudes de modelos a tu backend, por ejemplo, Amazon Bedrock.
Para implementar la puerta de enlace en toda tu organización, consulta Implementar una puerta de enlace. Para conocer el comportamiento que debe admitir la API, consulta Compatibilidad de la puerta de enlace. Para conectarte directamente a Bedrock sin una puerta de enlace, consulta Amazon Bedrock.
Comprobar si ya existe una configuración
Instala la versión del cliente de Codex que probó tu administrador. Si tu organización administra la configuración, abre ese cliente y sigue los pasos de inicio de sesión que te indicó tu administrador. En ese caso, puedes omitir los ejemplos de configuración del proveedor que aparecen más adelante.
- En la CLI, revisa el perfil seleccionado y ejecuta
codex doctor. Después de iniciar la CLI, usa/statuspara confirmar qué modelo y proveedor están activos. - Para la app de macOS, revisa
~/.codex/config.tomlo la configuración administrada que distribuye tu organización. - Para la app de Windows, revisa
%USERPROFILE%\.codex\config.tomlo la configuración del sistema que distribuye tu organización.
Si el proveedor de la puerta de enlace y el modelo que esperas usar ya están activos, completa los pasos de inicio de sesión que te haya indicado tu administrador y continúa con Verificar la conexión. Evita agregar una segunda configuración del proveedor en un equipo administrado. Si la configuración difiere de la que te indicó tu administrador, pregúntale qué capa de configuración debe proporcionar esos valores antes de editar los archivos locales.
Obtener los datos de conexión de la puerta de enlace
Para la configuración manual, confirma si necesitas iniciar sesión en el Espacio de trabajo de ChatGPT, autenticarte en la puerta de enlace o hacer ambas cosas.
Para configurar Codex por tu cuenta, pídele al equipo de la puerta de enlace estos datos:
- La URL base HTTPS de la puerta de enlace, incluida la ruta de la API, por ejemplo,
https://gateway.example.com/v1. - El nombre del modelo y el ID del proveedor que debes usar.
- El método de autenticación: OAuth nativo de la puerta de enlace, una clave de API de alcance limitado y su variable de entorno, o un asistente de credenciales instalado.
- Para OAuth, la URL de autorización, la URL para obtener tokens, el ID del cliente público y los alcances que se requieran. Si la puerta de enlace usa una cookie o un encabezado personalizado, pide también su nombre.
- Si se requiere un catálogo de modelos, su URL o el archivo del catálogo con su ruta local absoluta.
Configurar el proveedor
Abre config.toml en ~/.codex/config.toml si usas macOS o Linux, o en %USERPROFILE%\.codex\config.toml si usas Windows.
Incorpora este ejemplo a tu configuración y reemplaza la URL y el modelo por los valores que te dio tu administrador. Evita definir dos veces una misma clave o tabla. El 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 los metadatos incluidos para ese modelo coinciden con los de la puerta de enlace.
Coloca model, model_provider, model_catalog_json y web_search antes de la primera tabla TOML. Las claves que aparecen después del encabezado de una tabla pertenecen a esa tabla, por lo que Codex no las lee como opciones de nivel superior.
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"
requires_openai_auth = falseLuego agrega la configuración de autenticación que te indique el equipo de la puerta de enlace.
enterprise-gateway es un ejemplo de ID de proveedor. Usa el mismo ID en model_provider y en las tablas de proveedor y autenticación correspondientes. En este ejemplo, la búsqueda web está desactivada para la prueba de conexión inicial. Antes de activarla, tu administrador debe verificar que la puerta de enlace admita esa función.
Configurar el catálogo de modelos
Confirma con el equipo de la puerta de enlace cómo obtiene Codex las capacidades y las instrucciones del modelo que seleccionaste:
- Nombre integrado: si la puerta de enlace acepta el nombre exacto del modelo incluido en tu versión de Codex y dirige las solicitudes al modelo correspondiente, asigna ese nombre a
model. Codex ya tiene sus metadatos. - Punto de acceso del catálogo: si la puerta de enlace proporciona metadatos compatibles con Codex, usa la URL completa del catálogo. Puede ser un punto de acceso
/v1/modelsque implemente la respuesta de catálogo de Codex. Una respuesta que solo enumere los ID de los modelos no basta para usar alias personalizados. - Archivo de catálogo: si tu puerta de enlace usa alias personalizados y tu administrador distribuye un archivo, sigue el ejemplo de archivo models.json local. Usa un archivo local cuando OAuth nativo de la puerta de enlace sea tu única credencial y necesites metadatos personalizados.
Si te autenticas con una clave de API o un asistente y tu administrador te da la URL de un catálogo, agrégala a la tabla [model_providers.enterprise-gateway] que ya existe:
model_catalog_url = "https://gateway.example.com/codex/models.json"Elimina cualquier valor de model_catalog_json que esté en uso, ya que tiene prioridad sobre la URL. Los administradores pueden consultar los requisitos del punto de acceso en Configurar un catálogo remoto.
Si tu administrador te da un archivo local de catálogo de modelos, guárdalo y agrega model_catalog_json antes de la primera tabla TOML con la ruta absoluta del archivo. Los alias personalizados requieren metadatos de catálogo que coincidan con ellos. Por ejemplo:
model_catalog_json = "/etc/codex/gateway-models.json"Usa el nombre del modelo junto con el catálogo que tu administrador te proporcionó para ese modelo. Agrega la ruta del catálogo solo si el archivo existe en esa ubicación.
Elegir un método de autenticación
Usa OAuth nativo de la puerta de enlace para iniciar sesión en el navegador, una clave de API si tienes una credencial de alcance limitado o un asistente de credenciales si tu organización te proporciona un comando.
Usar OAuth nativo de la puerta de enlace
OAuth de la puerta de enlace funciona de manera independiente del inicio de sesión con ChatGPT. Úsalo cuando tu puerta de enlace acepte tokens de acceso emitidos por el proveedor de identidad de tu organización, como Microsoft Entra ID. Codex gestiona el inicio de sesión en el navegador y el almacenamiento cifrado de las credenciales. También renueva el token de acceso cuando el servidor de autorización emite un token de actualización.
Si solo te autenticas en la puerta de enlace, la CLI de Codex, a partir de la versión 0.166.0, envía de forma predeterminada el token de acceso en Authorization: Bearer <gateway access token>. Elimina cualquier entrada Authorization de http_headers o env_http_headers de este proveedor.
El equipo de la puerta de enlace debe registrar un cliente OAuth público que admita el flujo de código de autorización con PKCE. Agrega esta tabla a la configuración del proveedor en config.toml y reemplaza las URL y el ID del cliente por los valores que te indique el equipo:
[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127Agrega scopes y, si es necesario, resource a esta tabla con los valores que requieran tu proveedor de identidad y tu puerta de enlace. Si tu proveedor exige alcances específicos para emitir tokens de actualización, solicítalos. De forma predeterminada, Codex usa un puerto de loopback disponible. Si tu proveedor de identidad requiere un URI de redirección fijo, configura redirect_port y, para este ejemplo, registra http://127.0.0.1:43127/callback.
Si tu puerta de enlace espera una cookie o un encabezado personalizado, configura el campo opcional delivery en la tabla de OAuth. Elige el método que valida tu puerta de enlace:
delivery = { kind = "cookie", name = "auth-openid" }delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }Si tu implementación también requiere iniciar sesión con ChatGPT, usa una cookie o un encabezado independiente para la puerta de enlace, como en los ejemplos anteriores. Consulta Habilitar el inicio de sesión con ChatGPT.
Si la puerta de enlace solo acepta una clave de API estática, primero debe incorporar compatibilidad con el token OAuth y su método de entrega para que puedas usar este flujo. La puerta de enlace sigue gestionando sus propias credenciales de acceso a los servicios de destino, como las credenciales de AWS que usa para Bedrock.
Si OAuth es tu única credencial, conserva requires_openai_auth = false y elimina las opciones env_key, experimental_bearer_token o auth que usabas para la credencial de la puerta de enlace. Si necesitas metadatos de modelo personalizados, usa un catálogo de modelos local. OAuth por sí solo no habilita la detección de catálogos remotos.
Reinicia la app de escritorio y sigue las indicaciones de inicio de sesión de la puerta de enlace para abrir el navegador. En la CLI, ejecuta codex y sigue las indicaciones para iniciar sesión en el navegador cuando Codex acceda por primera vez a la puerta de enlace. Completa el inicio de sesión y la MFA de tu organización. Luego vuelve al cliente. Si la autorización vence o Codex no puede renovarla, vuelve a iniciar sesión cuando se te indique.
OAuth nativo de la puerta de enlace requiere un navegador y una dirección de retorno accesible en la interfaz de loopback. No ofrece un método alternativo con código de dispositivo. Si ejecutas la CLI a través de SSH, configura redirect_port = 43127 en la tabla de OAuth y registra el URI de redirección correspondiente que se indicó antes. Antes de iniciar Codex, reenvía ese puerto desde el equipo donde usas el navegador:
ssh -L 43127:127.0.0.1:43127 user@remoteEn esa sesión SSH, ejecuta codex y abre la URL de inicio de sesión de la puerta de enlace en tu navegador local. Si ejecutas la CLI en un contenedor, el navegador también debe poder acceder a la dirección de retorno. Si no puedes hacer que esa dirección sea accesible, usa una clave de API o un asistente de credenciales.
Usar una clave de API
Usa esta opción cuando la puerta de enlace espere una clave de API en el encabezado Authorization.
Agrega la siguiente opción dentro de la tabla [model_providers.enterprise-gateway] que ya existe:
env_key = "CODEX_GATEWAY_API_KEY"Usa el mecanismo de distribución de secretos de tu organización para que la credencial de la puerta de enlace esté disponible como CODEX_GATEWAY_API_KEY en el entorno del proceso que inicia Codex. No guardes la credencial en TOML ni en un repositorio. Es posible que una variable definida en una terminal no esté disponible para una app que se inicia desde el escritorio.
Usar 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, reemplaza env_key en la tabla del proveedor por lo siguiente:
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }Usa el nombre exacto del encabezado que te indique tu administrador. Codex lee el valor de la variable de entorno especificada. No guardes la credencial en el archivo de configuración. Consulta la referencia de configuración para obtener más información sobre model_providers.<id>.env_http_headers.
Si usas el inicio de sesión con ChatGPT, envía la clave de la puerta de enlace en el encabezado personalizado para que Codex pueda enviar la credencial de OpenAI del usuario en Authorization.
Si el encabezado personalizado es tu único mecanismo de autenticación, usa model_catalog_json, ya que no se ejecutará la detección de catálogos remotos.
Usar un asistente de credenciales de la organización
Si tu administrador proporciona autenticación mediante un comando, usa el asistente instalado y la configuración que te indique en lugar de env_key. No configures ambos mecanismos. El asistente debe estar instalado en tu equipo. Codex no lo instala. Por ejemplo, agrega esta tabla sin env_key y usa la ruta del ejecutable y los argumentos que te indique tu administrador:
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000La referencia de autenticación para proveedores personalizados define el comando, los argumentos, el tiempo de espera, el intervalo de actualización y los requisitos que debe cumplir la salida del comando para entregar el token. Si el asistente ya no puede obtener un token, pregúntale a tu administrador cómo renovar tu sesión.
Si usas el inicio de sesión con ChatGPT, ejecuta el asistente antes de iniciar Codex y envía su salida en un encabezado personalizado de la puerta de enlace en lugar de configurar la tabla auth. Cuando la clave venza, obtén una nueva y vuelve a iniciar Codex.
Usa rutas absolutas ya resueltas para los ejecutables del asistente y los archivos de catálogo.
Habilitar el inicio de sesión con ChatGPT (recomendado)
Si tu organización usa un Espacio de trabajo de ChatGPT, los usuarios que inician sesión pueden acceder a las funciones para las que reúnen los requisitos, como los complementos de OpenAI. Se aplican los controles de tu Espacio de trabajo y tu puerta de enlace sigue gestionando las solicitudes al modelo. Compara la disponibilidad de las funciones.
Si configuras Codex de forma manual, actualiza la tabla [model_providers.enterprise-gateway] existente antes de iniciar sesión:
- Establece
requires_openai_auth = truey manténbase_urlapuntando a tu puerta de enlace. Elimina del proveedor cualquier configuración deenv_key,experimental_bearer_tokenyauthpara que Codex use tu credencial de OpenAI para la autenticación principal. - Envía la credencial de la puerta de enlace por separado. Si usas OAuth nativo de la puerta de enlace, configura
gateway_oauth.deliverypara que use la cookie o el encabezado personalizado que acepta tu puerta de enlace. Si usas una clave de API o un asistente de credenciales, utiliza un encabezado de autenticación personalizado. ReservaAuthorizationpara la credencial de OpenAI.
Inicia sesión en el Espacio de trabajo de ChatGPT que te indicó tu administrador. Si se te solicita, inicia sesión también en la puerta de enlace. Luego verifica la conexión.
Los administradores pueden distribuir la configuración administrada del proveedor y verificar el reenvío de credenciales.
Gestionar las credenciales en la puerta de enlace
La puerta de enlace recibe dos credenciales en cada solicitud al modelo. Por ejemplo, cuando Codex envía el token OAuth de la puerta de enlace en una cookie, la solicitud tiene esta forma:
POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>Valida la credencial de la puerta de enlace y elimina de la solicitud la cookie o el encabezado personalizado que la contiene. Oculta las credenciales y los datos sensibles de las solicitudes en los registros. Elige qué credencial enviar al proveedor:
- Reenvía la credencial del usuario para la inferencia directa con OpenAI (recomendado). Así OpenAI puede atribuir el uso a ese usuario y aplicar su configuración de inferencia. Para esta ruta, la puerta de enlace debe actuar como proxy de
/modelsy/responseshaciahttps://chatgpt.com/backend-api/codexy reenviar sin cambiosAuthorizationy cualquier encabezadoChatGPT-Account-ID. - Permite que la puerta de enlace se autentique ante el proveedor de inferencia. Usa las credenciales configuradas en la puerta de enlace para ese proveedor. Excluye el token de OpenAI del usuario y cualquier encabezado
ChatGPT-Account-IDde la solicitud al proveedor.
Estos diagramas muestran la ruta recomendada para la inferencia con OpenAI.
Cómo funciona una clave de la puerta de enlace con el inicio de sesión con ChatGPT
Cómo funciona OAuth de la puerta de enlace con el inicio de sesión con ChatGPT
Agregar encabezados de enrutamiento (opcional)
Usa la configuración de enrutamiento que te indique tu administrador. Los operadores de la puerta de enlace pueden distribuir esta configuración y consultar la ruta seleccionada en los registros de la puerta de enlace.
Solo las solicitudes al proveedor de modelos usan esta ruta de la puerta de enlace. Las sesiones de voz usan una ruta distinta. El inicio de sesión en el Espacio de trabajo, los servidores MCP y los complementos también pueden usar otras rutas de red.
Iniciar el cliente
Si usas el inicio de sesión con ChatGPT, inicia el cliente e ingresa al Espacio de trabajo que proporciona la configuración administrada. Si usas OAuth nativo de la puerta de enlace, completa también el inicio de sesión en la puerta de enlace de tu organización cuando se te indique. Luego verifica la conexión.
Si configuraste el proveedor de forma local, sigue las instrucciones para tu cliente.
Configurar la CLI
De forma predeterminada, la CLI lee ~/.codex/config.toml en macOS o Linux. Después de guardar la configuración del proveedor, ejecuta codex. En WSL, usa la configuración y las rutas de Linux, salvo que CODEX_HOME apunte a otra ubicación.
Configurar la app de macOS
La app de macOS lee el mismo archivo ~/.codex/config.toml. Después de guardar la configuración del proveedor, reinicia la app. Si usas una variable de entorno para la credencial, comprueba que el proceso de la app tenga acceso a ella.
Configurar la app de Windows
Agrega la configuración del proveedor a %USERPROFILE%\.codex\config.toml y reinicia la app. Para la autenticación mediante un comando, usa el ejecutable que instaló tu administrador. Por ejemplo, reemplaza la tabla de autenticación de Unix por la siguiente:
[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 = 300000En los archivos TOML de Windows, las cadenas literales entre comillas simples conservan las barras invertidas. Reemplaza también las rutas de catálogo de Unix por la ruta real que te dio tu administrador, por ejemplo, 'C:\ProgramData\OpenAI\Codex\models.json'.
Configura los servidores MCP y los complementos por separado. La credencial de la puerta de enlace de modelos no autoriza el acceso a tus herramientas ni a los sistemas conectados.
Verificar la conexión
Usa el ID del proveedor y el alias del modelo que te indicó tu administrador. El ID del proveedor identifica la conexión configurada. El alias del modelo identifica el modelo al que se dirigen las solicitudes a través de esa conexión. El inicio de sesión con ChatGPT y la autenticación en la puerta de enlace controlan el acceso. Es posible que se requieran ambos.
Reinicia el cliente después de cambiar la configuración. En la CLI, ejecuta codex y usa /status para revisar qué modelo y proveedor están activos. En la app de escritorio, comprueba el modelo seleccionado y la configuración.
Envía este prompt en una tarea nueva:
Responde exactamente con: gateway-okLa respuesta esperada es gateway-ok. Por sí sola, la respuesta no demuestra qué ruta procesó la solicitud. Pídele a tu administrador que confirme que la puerta de enlace registró tu usuario, el alias del modelo y la ruta prevista hacia el proveedor. No intentes identificar el modelo preguntándole su nombre.
Solucionar problemas de conexión
| Síntoma | Qué revisar |
|---|---|
| El proveedor esperado no está activo. | Revisa el perfil seleccionado y el orden de prioridad de la configuración. Confirma que las claves de nivel superior estén fuera de las tablas de proveedores. |
| Falla el inicio de sesión con OAuth o la entrega del token. | Revisa el registro del cliente público, el URI de redirección, los alcances y la cookie o el encabezado que configuraste. Confirma que la puerta de enlace acepte el token de acceso emitido. |
| Falla la autenticación con la clave de API o con el asistente. | Comprueba que el proceso del cliente tenga acceso a la variable que contiene la credencial o que el asistente instalado pueda obtener un token vigente. Pídele al administrador que determine si el fallo ocurre al autenticarse en la puerta de enlace o ante el proveedor de destino. |
| No se encuentra el modelo. | Confirma el nombre del modelo que te proporcionaron y pídele al administrador que revise la ruta de ese modelo. |
| El modelo usa capacidades inesperadas. | Pídele al administrador que compruebe que los metadatos del catálogo correspondan al modelo al que apunta el alias. |
| La transmisión se detiene o fallan los turnos posteriores. | Pídele al responsable de la puerta de enlace que revise el uso del búfer del proxy, el evento final response.completed y la compatibilidad de la puerta de enlace. |
| No funciona la ruta del catálogo o del asistente. | Confirma que el archivo exista en la ruta absoluta configurada dentro del entorno donde se ejecuta Codex. |
Cuando solicites ayuda, indica la versión del cliente, el sistema operativo, el proveedor y el alias del modelo que esperabas usar, el método de autenticación y el paso que falló. Incluye el mensaje de error y la hora de la solicitud para que el responsable de la puerta de enlace pueda localizarla. Elimina los tokens, las cookies, los encabezados de autorización y los prompts que contengan información sensible. No envíes archivos de credenciales ni volcados de configuración que contengan secretos.
Usar una puerta de enlace ya implementada
Pídele al equipo de la puerta de enlace la configuración del proveedor para Codex y el alias del modelo aprobado. Si el equipo aún necesita habilitar una ruta para Codex, comparte la lista de verificación de la migración para administradores.