Conéctate a una puerta de enlace

Configura una puerta de enlace de modelos y autentícate con OAuth nativo de la puerta de enlace, una API key o un asistente de credenciales.

Conecta Codex a la puerta de enlace de modelos de tu organización usando la configuración del proveedor y el método de autenticación que te proporcione el equipo responsable de la puerta de enlace. La puerta de enlace dirige las solicitudes de modelos a tu backend, como Amazon Bedrock.

Comprueba si ya existe una configuración

Instala el cliente de Codex y la versión que haya probado tu administrador. Si tu organización gestiona la configuración, abre ese cliente y completa los pasos de inicio de sesión de las instrucciones que te hayan proporcionado. Puedes omitir los ejemplos de configuración del proveedor que aparecen a continuación.

  • 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, completa los pasos de inicio de sesión que te haya proporcionado tu administrador y, después, continúa con Verificar la conexión. Evita añadir una segunda configuración de proveedor a un equipo gestionado. Si los ajustes difieren de las instrucciones de tu administrador, pregunta qué capa de configuración debe proporcionarlos antes de editar archivos locales.

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

Para la configuración manual, confirma si necesitas iniciar sesión en el espacio de trabajo de ChatGPT, autenticarse en la puerta de enlace o ambas cosas.

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 se deben usar.
  • El método de autenticación: OAuth nativo de la puerta de enlace, una API key con un ámbito limitado y su variable de entorno, o un asistente de credenciales instalado.
  • Para OAuth, la URL de autorización, la URL del token, el ID de cliente público y los ámbitos necesarios. Para las puertas de enlace que usen una cookie o una cabecera personalizada, su nombre.
  • Cualquier URL de catálogo de modelos necesaria, o un archivo de catálogo 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"
requires_openai_auth = false

Luego añade la configuración de autenticación que te proporcione el equipo responsable de la puerta de enlace.

enterprise-gateway es un ID de proveedor de ejemplo. Usa el mismo ID en model_provider y en tus tablas de proveedor y autenticación. Este ejemplo desactiva la búsqueda web para la prueba de conexión inicial; tu administrador debe verificar la compatibilidad con la función antes de activarla.

Configura tu catálogo de modelos

Confirma con el equipo responsable de la puerta de enlace cómo obtiene Codex las capacidades y las instrucciones del modelo seleccionado:

  • Nombre integrado: Si la puerta de enlace acepta el nombre exacto del modelo incluido en tu versión de Codex y lo dirige al modelo correspondiente, establece model en ese nombre. Codex ya dispone de sus metadatos.
  • Endpoint de catálogo: Si la puerta de enlace proporciona metadatos compatibles con Codex, use la URL completa de su catálogo. Puede ser un endpoint /v1/models que implemente la respuesta de catálogo de Codex. Una respuesta que solo enumere los ID de modelos no es suficiente para los alias personalizados.
  • Archivo de catálogo: Si tu puerta de enlace usa alias personalizados y tu administrador distribuye un archivo, use el ejemplo de models.json local. Usa un archivo local cuando OAuth nativo de la puerta de enlace sea tu única credencial y necesite metadatos personalizados.

Para la autenticación con API key o asistente, si tu administrador proporciona una URL de catálogo, añádela a la tabla existente [model_providers.enterprise-gateway]:

model_catalog_url = "https://gateway.example.com/codex/models.json"

Elimina cualquier configuración model_catalog_json efectiva, ya que tiene prioridad sobre la URL. Los administradores pueden consultar los requisitos del endpoint en configuración del catálogo remoto.

Si tu administrador proporciona un archivo de catálogo de modelos local, guárdalo y añade model_catalog_json antes de la primera tabla TOML con la ruta absoluta del archivo. Los alias personalizados necesitan metadatos de catálogo que coincidan. 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.

Elige un método de autenticación

Usa OAuth nativo de la puerta de enlace para iniciar sesión en el navegador, una API key para una credencial con alcance limitado o un asistente de credenciales si tu organización proporciona un comando.

{/* prettier-ignore */}

Usa OAuth nativo de la puerta de enlace

OAuth de la puerta de enlace funciona independientemente del inicio de sesión en 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 se encarga del inicio de sesión en el navegador, del almacenamiento cifrado de credenciales y de la renovación de tokens cuando el servidor de autorización emite un token de actualización.

Para la autenticación exclusiva de la puerta de enlace, Codex CLI 0.166.0 y versiones posteriores envían el token de acceso en Authorization: Bearer <gateway access token> de forma predeterminada. Elimina cualquier entrada Authorization de http_headers o env_http_headers de este proveedor.

El equipo de tu puerta de enlace debe registrar un cliente OAuth público que admita el flujo de código de autorización con PKCE. Añade esta tabla a la configuración del proveedor en config.toml y sustituye las URL y el ID de cliente por sus valores correspondientes:

[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 = 43127

Añade scopes y, si es necesario, resource a esta tabla con los valores que requieran tu proveedor de identidad y tu puerta de enlace. Solicita los alcances necesarios para los tokens de actualización si tu proveedor los requiere. Codex usa un puerto de bucle local disponible de forma predeterminada. Si tu proveedor de identidad requiere una URI de redirección fija, establece redirect_port y registra http://127.0.0.1:43127/callback para este ejemplo.

Si tu puerta de enlace espera una cookie o un encabezado personalizado, configura el campo opcional delivery en la tabla OAuth. Elige el método que valide 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 en ChatGPT, usa la cookie o un encabezado independiente para la puerta de enlace como los mostrados arriba. Consulta Habilitar el inicio de sesión en ChatGPT.

Una puerta de enlace que solo acepte una API key estática debe añadir compatibilidad con el token OAuth y su método de entrega antes de que pueda utilizar este flujo. La puerta de enlace sigue administrando sus propias credenciales para los servicios de destino, como sus credenciales de AWS para Bedrock.

Cuando OAuth sea tu única credencial, mantén requires_openai_auth = false y elimine las opciones anteriores env_key, experimental_bearer_token o auth utilizadas para la credencial de la puerta de enlace. Usa un catálogo de modelos local si necesitas metadatos de modelos personalizados; OAuth por sí solo no habilita el descubrimiento de catálogos remotos.

Reinicia la aplicación de escritorio y sigue la indicación de inicio de sesión en la puerta de enlace para abrir el navegador. En la CLI, inicia codex y sigue el proceso de inicio de 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 y luego vuelve al cliente. Si la autorización caduca o Codex no puede renovarla, vuelve a iniciar sesión cuando se te solicita.

OAuth nativo de la puerta de enlace requiere un navegador y una dirección de retorno de bucle local accesible. No ofrece una alternativa con código de dispositivo. Si la CLI se ejecuta por SSH, establece redirect_port = 43127 en la tabla OAuth y registra la URI de redirección correspondiente descrita anteriormente. Desde el equipo donde está tu navegador, reenvía ese puerto antes de iniciar Codex:

ssh -L 43127:127.0.0.1:43127 user@remote

En esa sesión SSH, inicia codex y abre la URL de inicio de sesión de la puerta de enlace en tu navegador local. Una CLI dentro de un contenedor también necesita una dirección de retorno accesible desde el navegador. Si no puedes hacer que la dirección de retorno sea accesible, usa una API key o un asistente de credenciales en su lugar.

Habilita el inicio de sesión con ChatGPT (recomendado)

Si tu organización usa un espacio de trabajo de ChatGPT, iniciar sesión permite a los usuarios acceder a las funciones que les correspondan, como los plugins propios de OpenAI. Se aplican los controles de tu espacio de trabajo y tu pasarela sigue gestionando las solicitudes a los modelos. Compara la disponibilidad de las funciones.

Para la configuración manual, actualiza la tabla [model_providers.enterprise-gateway] existente antes de iniciar sesión:

  1. Establece requires_openai_auth = true y mantén base_url apuntando a tu puerta de enlace. Elimina cualquier opción env_key, experimental_bearer_token y auth del proveedor para que Codex utilice tu credencial de OpenAI para la autenticación principal.
  2. Envía la credencial de la puerta de enlace por separado. Para OAuth nativo de la puerta de enlace, configura gateway_oauth.delivery para utilizar la cookie o el encabezado personalizado que acepte tu puerta de enlace. Para una API key o un asistente de credenciales, usa un encabezado de autenticación personalizado. Reserva Authorization para la credencial de OpenAI.

Inicia sesión en el espacio de trabajo de ChatGPT que haya indicado tu administrador. Completa el inicio de sesión en la puerta de enlace si se te solicita y, a continuación, verifica su conexión.

Los administradores pueden distribuir la configuración administrada del proveedor y verificar el reenvío de credenciales.

Gestiona las credenciales en la pasarela

La pasarela recibe dos credenciales en cada solicitud a un modelo. Por ejemplo, cuando Codex envía el token OAuth de la pasarela en una cookie:

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 pasarela y elimina su cookie o encabezado personalizado. Oculta las credenciales y los datos sensibles de las solicitudes en los registros. Elige qué credencial usar para comunicarse con el servicio de destino:

  • Reenvía la credencial del usuario para la inferencia directa de OpenAI (recomendado). Esto permite a OpenAI atribuir el uso y aplicar la configuración de inferencia de ese usuario. Para esta ruta, la pasarela debe actuar como proxy de /models y /responses hacia https://chatgpt.com/backend-api/codex y reenviar Authorization y cualquier encabezado ChatGPT-Account-ID sin modificaciones.
  • Deja que la pasarela se autentique ante el proveedor de inferencia. Usa las credenciales configuradas en la pasarela para ese proveedor. Excluye el token de OpenAI del usuario y cualquier encabezado ChatGPT-Account-ID de la solicitud al servicio de destino.

Estos diagramas muestran la ruta recomendada para la inferencia de OpenAI.

Cómo funciona una clave de pasarela con el inicio de sesión con ChatGPT
Reutiliza el comando de credenciales mediante una herramienta auxiliar de inicio. La misma clave de la pasarela pasa de Authorization a X-Gateway-Key, mientras que el inicio de sesión con ChatGPT proporciona Authorization.
La pasarela valida y elimina X-Gateway-Key y, a continuación, reenvía Authorization de ChatGPT y cualquier ID de cuenta sin modificaciones al backend de Codex.
Cómo funciona OAuth de la pasarela con el inicio de sesión con ChatGPT
Sustituye la autenticación de la pasarela mediante API key por OAuth nativo de la pasarela junto con el inicio de sesión con ChatGPT.
La pasarela consume su cookie OAuth y reenvía la credencial de ChatGPT al backend de Codex.

Añade encabezados de enrutamiento (opcional)

Usa la configuración de enrutamiento proporcionada por tu administrador. Los operadores de la puerta de enlace pueden distribuir esta configuración y comprobar la ruta seleccionada en los registros de la puerta de enlace.

Solo las solicitudes al proveedor de modelos usan esta ruta de la pasarela. Las sesiones de voz usan una ruta independiente. El inicio de sesión en el espacio de trabajo, los MCP servers y los plugins también pueden usar otras rutas de red.

Inicia el cliente

Con el inicio de sesión con ChatGPT, inicia el cliente e inicia sesión en el espacio de trabajo que proporciona la configuración administrada. Si usas OAuth nativo de la pasarela, completa también el inicio de sesión en la pasarela de tu organización cuando se te solicita. Después, verifica la conexión.

Para un proveedor configurado localmente, sigue las instrucciones de tu cliente.

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

Usa el ID del proveedor y el alias del modelo que te haya proporcionado tu administrador. El proveedor identifica la conexión configurada; el alias del modelo identifica un modelo al que se accede a través de esa conexión. El inicio de sesión en ChatGPT y la autenticación de la puerta de enlace controlan el acceso y pueden ser necesarios ambos.

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 confirma 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.

Soluciona problemas de conexión

Síntoma Qué comprobar
El proveedor esperado no está activo. Comprueba el perfil seleccionado y la precedencia de la configuración. Confirma que las claves de nivel superior no estén dentro de una tabla de proveedor.
Falla el inicio de sesión con OAuth o la entrega del token. Comprueba el registro del cliente público, el URI de redirección, los ámbitos y la cookie o el encabezado configurados. Confirma que la puerta de enlace acepte el token de acceso emitido.
Falla la autenticación con API key o con el asistente de credenciales. Comprueba que la variable de credenciales llegue al proceso del cliente o que el asistente instalado pueda obtener un token vigente. Pide al administrador que distinga la autenticación de la puerta de enlace de la autenticación del proveedor de destino.
No se encuentra el modelo. Confirma el nombre del modelo proporcionado y pide al administrador que compruebe su ruta.
El modelo utiliza capacidades inesperadas. Pide al administrador que compruebe que los metadatos del catálogo correspondan al modelo al que apunta el alias.
La transmisión se bloquea o fallan los turnos de seguimiento. Pide al responsable de la puerta de enlace que compruebe el almacenamiento en búfer del proxy, el evento final response.completed y la compatibilidad de la puerta de enlace.
Falla la ruta de un catálogo o asistente de credenciales. Confirma que el archivo exista en la ruta absoluta configurada en el entorno donde se ejecuta Codex.

Cuando solicites ayuda, incluya la versión del cliente, el sistema operativo, el proveedor y el alias del modelo esperados, 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 sensibles. No envíes archivos de credenciales ni un volcado de configuración que contenga secretos.

Usa una implementación de puerta de enlace existente

Solicita al equipo de tu puerta de enlace la configuración del proveedor de Codex y el alias del modelo aprobado. Si el equipo todavía necesita habilitar una ruta de Codex, comparte la lista de verificación de migración para administradores.

Documentación relacionada