Despliega una puerta de enlace
Distribuye y verifica una conexión de Codex a una puerta de enlace para tu organización
Como administrador de la puerta de enlace, configura las rutas de los modelos y autoriza a un usuario piloto. Prueba la conexión en cada cliente compatible antes de distribuir la configuración a los desarrolladores. Usa OAuth nativo de la puerta de enlace, API keys o asistentes de credenciales para la autenticación de la puerta de enlace. Para combinar la autenticación de la puerta de enlace con el inicio de sesión en el espacio de trabajo de ChatGPT, consulta Iniciar sesión con ChatGPT a través de una puerta de enlace.
Requisitos previos
Antes de desplegar Codex para los desarrolladores, confirma que dispones de:
- Una puerta de enlace que sirva HTTPS en la URL base exacta que vas a distribuir.
- Una credencial del proveedor de destino almacenada en la puerta de enlace.
- Alias de modelos aprobados para Codex que se correspondan con los modelos de destino previstos.
- Un método de autenticación probado: OAuth nativo de la puerta de enlace, API keys de la puerta de enlace con ámbito limitado o un asistente de credenciales.
- Para OAuth, un cliente público registrado, usuarios de prueba aprobados y compatibilidad de la puerta de enlace con la validación de tokens de acceso de OAuth.
- Para API keys o asistentes, un mecanismo de entrega de secretos o un asistente probado.
- Un medio para distribuir la configuración, los asistentes necesarios y los archivos de catálogo.
Requisitos de la pasarela
Antes de conectar Codex, verifica que el producto de pasarela conserve estos comportamientos obligatorios:
- Aceptar solicitudes de Codex a la Responses API en
POST /v1/responses. - Transmitir eventos SSE sin almacenarlos en búfer y finalizar con
response.completed. - Conservar la continuación de la conversación con entradas reenviadas.
- Conservar
previous_response_idsolo cuando WebSocket o el transporte incremental estén habilitados. - Conservar las llamadas a funciones y sus elementos
function_call_outputcorrespondientes. - Dirigir cada alias de modelo para Codex al modelo de origen previsto.
- Autenticar a los usuarios por separado y devolver errores útiles sin ocultar la causa.
Un endpoint de estado, /v1/models, una respuesta de Chat Completions o una única respuesta de texto sin formato no bastan para validar la pasarela. Consulta Requisitos de compatibilidad de las pasarelas para conocer el contrato detallado.
Implementar la pasarela
Para pasar de una pasarela desplegada a una experiencia de desarrollo verificada, completa estos cinco pasos en orden:
- Elige los nombres de los modelos y verifica las rutas.
- Elige la autenticación.
- Prueba Codex a través de la puerta de enlace.
- Distribuye la configuración.
- Verifica desde el equipo de un desarrollador.
Elegir los nombres y las rutas de los modelos
Establece model de Codex en el nombre del modelo de la pasarela. Configura la pasarela para dirigir ese nombre al modelo de origen aprobado.
| Nombre del modelo en la pasarela | Configuración de Codex |
|---|---|
| Un nombre de modelo integrado incluido en tu versión de Codex | Establece model en config.toml exactamente en este nombre. |
Un alias personalizado, como company-coding-model |
Proporciona un catálogo remoto o local que contenga el alias y los metadatos del modelo correspondiente. |
Usar un catálogo de modelos para nombres personalizados
Para un catálogo local, comienza con el ejemplo de models.json.
Proporciona un catálogo de modelos cuando tu pasarela usa un nombre de modelo que Codex no reconozca. El catálogo proporciona las instrucciones, las opciones de razonamiento, los límites de contexto y las capacidades de las herramientas que Codex usa para ese nombre. Sin una entrada coincidente, una solicitud puede llegar al modelo de origen previsto mientras Codex usa una configuración genérica.
Aloja un catálogo remoto con model_providers.<id>.model_catalog_url para actualizar los metadatos de los modelos de forma centralizada, o distribuye un archivo local con model_catalog_json. Utiliza un catálogo local cuando OAuth nativo de la puerta de enlace sea la única credencial; OAuth por sí solo no habilita la detección de catálogos remotos. Consulta la referencia de configuración para conocer ambas opciones.
Obtén de tu proveedor de nube o de puerta de enlace un endpoint o archivo de catálogo compatible con tu versión de Codex. Asegúrate de que incluya cada alias aprobado y los metadatos de su modelo. Para implementar el catálogo, consulta Implementación de catálogos de modelos para puertas de enlace y nubes.
Servir un catálogo remoto
Usa el endpoint HTTPS del catálogo que te proporcione tu proveedor.
Distribuye la URL completa del endpoint en la tabla config.toml del proveedor seleccionado:
model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"Haz que CODEX_GATEWAY_API_KEY esté disponible para el proceso de Codex. Establece base_url
por separado para dirigir la inferencia a través de la pasarela. Si lo omites, Codex usa el
endpoint predeterminado de OpenAI para el modo de autenticación actual.
La detección requiere autenticación con API key, mediante comandos o mediante el backend de Codex. OAuth nativo de la puerta de enlace o los encabezados personalizados por sí solos no la activan.
Coordina las actualizaciones del catálogo con tu proveedor cuando cambien tus modelos aprobados. Reinicia el cliente después de cambiar su configuración.
Elimina cualquier configuración model_catalog_json efectiva, incluidas las que se apliquen mediante
requirements.toml. Tiene prioridad sobre la URL remota e impide descargar el catálogo.
Distribuir un catálogo local
Usa model_catalog_json para cargar al inicio el archivo proporcionado por el proveedor. Un catálogo personalizado local
sustituye al catálogo incluido.
Establece el alias de la pasarela, slug del catálogo y model de Codex en company-coding-model. Añade estos ajustes antes de la primera tabla TOML en la configuración de Codex que distribuyas, utilizando la ruta absoluta real del archivo:
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"Reinicia la CLI o la aplicación de escritorio después de cambiar el catálogo, porque Codex lo carga al iniciarse.
Verificar las rutas de los modelos
Para cada modelo, verifica la ruta con una solicitud real de Responses y los registros
de la pasarela. Una respuesta de /v1/models puede ayudar a descubrir nombres, pero no demuestra que un
modelo admita el comportamiento requerido de solicitudes y herramientas.
El enrutamiento de modelos y la autorización de herramientas son partes independientes de la implementación. Configura las conexiones MCP, la distribución de plugins y sus políticas por separado.
Elige la autenticación
OAuth nativo de la puerta de enlace
- Registra un cliente público de OAuth que admita el código de autorización con PKCE y aprueba a los usuarios o grupos que puedan iniciar sesión.
- Configura la puerta de enlace para validar el token de acceso emitido en la cookie o el encabezado personalizado seleccionados. Aplica los modelos aprobados, los límites de solicitudes y los presupuestos a la identidad de cada usuario.
- Sigue OAuth nativo de la puerta de enlace para recopilar las URL de autorización y de tokens, el ID del cliente público, los ámbitos, el recurso opcional, la configuración de entrega de tokens y cualquier puerto de redirección fijo. Registra el URI de redirección de bucle local correspondiente con tu proveedor de identidad.
- Prueba el inicio de sesión en el navegador, la renovación de tokens y la revocación del acceso con un usuario de prueba en la CLI o la aplicación de escritorio que vayas a implementar. Confirma que el navegador pueda acceder a la URL de retorno, también para los usuarios remotos de la CLI.
Los usuarios inician sesión individualmente. Distribuyes la configuración de OAuth, no un secreto de cliente, una API key de la puerta de enlace ni un ejecutable de asistente. Mantén las credenciales del proveedor de destino en la puerta de enlace.
API keys o asistentes de credenciales
- Emite una credencial de pasarela con alcance limitado por desarrollador para poder atribuir el uso y revocar el acceso individualmente.
- Establece los modelos aprobados, los límites de frecuencia, el presupuesto, el vencimiento y el período de renovación de cada credencial.
- Entrega las credenciales mediante tu gestor de secretos o un asistente de credenciales instalado. Mantén las credenciales del proveedor de origen y del administrador de la pasarela fuera de los equipos de los desarrolladores.
- Si utilizas un asistente, sigue el contrato de autenticación mediante comandos y prueba la obtención y la renovación de tokens antes de distribuirlo.
- Explica a los desarrolladores cómo renovar sus credenciales y a quién contactar para obtener ayuda.
Probar Codex a través de la pasarela
Antes de distribuir nada, sigue Configurar el proveedor para configurar un usuario de prueba aislado con el bloque del proveedor y el método de autenticación que vayas a distribuir.
Si la puerta de enlace sirve el catálogo de modelos, confirma que devuelve una matriz models compatible con Codex. Para la inferencia de OpenAI con la credencial del usuario, confirma que la puerta de enlace reenvía los encabezados de ChatGPT necesarios al backend de Codex.
Registra la versión del cliente, el sistema operativo, el ID del proveedor, el alias del modelo y el método de autenticación de tu prueba piloto. Ejecuta las siguientes comprobaciones desde cada interfaz de CLI o de escritorio que tengas previsto admitir. Si ofreces tanto autenticación exclusiva de la puerta de enlace como autenticación de la puerta de enlace junto con el inicio de sesión en ChatGPT, prueba cada combinación por separado.
| Comprobación | Acción | Evidencia de éxito |
|---|---|---|
| Configuración efectiva | Inspecciona las capas de configuración y confirma el proveedor, el modelo y los requisitos previstos. | La prueba piloto usa los ajustes distribuidos. Los valores predeterminados del usuario o del perfil no seleccionan una ruta diferente. |
| Conexión | Sigue Verificar la conexión. | El proveedor y el alias esperados están activos, la solicitud de prueba se completa correctamente y los registros de la puerta de enlace identifican al usuario de prueba. |
| Transmisión en streaming | Solicita una respuesta breve de varios párrafos. | El texto llega de forma incremental y el transporte activo emite response.completed. Prueba HTTP por separado para verificar que la puerta de enlace reenvía los eventos SSE sin almacenarlos en búfer. |
| Ciclo de herramientas locales | En una carpeta desechable con permisos de solo lectura, pide a Codex que enumere los archivos del nivel superior y los resuma. | Codex realiza una llamada a una herramienta local, devuelve el resultado y genera una respuesta final sin realizar cambios. |
| Seguimiento | Haz una pregunta de seguimiento en el mismo hilo. | La respuesta usa el turno anterior; la puerta de enlace acepta la entrada reenviada. Si WebSocket o el transporte incremental están habilitados, también conserva previous_response_id. |
| Errores y atribución | Repite la prueba con un alias de prueba deliberadamente no válido o una credencial de prueba caducada. | El cliente recibe un error útil de enrutamiento o autenticación, y las solicitudes válidas siguen atribuidas al usuario de prueba. |
Si la aprobación automática está habilitada, usa una carpeta de prueba desechable para activar una acción de herramienta que requiera revisión según la política prevista. Confirma que la puerta de enlace gestiona la solicitud de revisión y que el cliente aplica la decisión de aprobación. Una llamada a una herramienta de solo lectura que no requiere aprobación no prueba este flujo. Registra cualquier flujo de trabajo no compatible antes de ampliar la prueba piloto.
Si la implementación cambia el proveedor para los usuarios existentes, prueba una conversación nueva y otra creada antes del cambio en cada cliente compatible. Registra si los usuarios pueden ver, continuar o ramificar la conversación existente, y proporciónales un procedimiento de recuperación para cualquier flujo de trabajo bloqueado. No des por hecho que cambiar el proveedor predeterminado migra el historial de conversaciones.
Una vez superadas estas comprobaciones, prepara la entrega a los desarrolladores.
Distribuir la configuración
Para que todos los equipos utilicen la misma ruta de conexión, distribuye la URL base de la puerta de enlace, el ID del proveedor, el alias del modelo aprobado y la configuración de autenticación.
Qué distribuir
Para OAuth nativo de la puerta de enlace, distribuye las tablas del proveedor y de
[model_providers.<id>.gateway_oauth] de la guía de
conexión, con los
valores de registro recopilados anteriormente. Conserva requires_openai_auth = false y omite
env_key, experimental_bearer_token y la tabla auth de autenticación mediante comandos cuando
OAuth sea la única credencial de la puerta de enlace.
Para un asistente de credenciales, distribuye el siguiente bloque de config.toml a través de la
capa de configuración que hayas elegido. Utiliza un modelo reconocido por tu versión de Codex o
proporciona el catálogo correspondiente descrito anteriormente. Instala el programa de obtención de tokens en la
ruta de comando configurada:
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"
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000Para una clave de prueba estática de corta duración, elimina el bloque de autenticación, coloca env_key = "CODEX_GATEWAY_API_KEY" dentro de [model_providers.enterprise-gateway] y establece esa variable fuera de TOML. No combines env_key con la autenticación mediante comandos.
Distribuir valores predeterminados y requisitos
Si tus usuarios no inician sesión en Codex con ChatGPT, puede distribuir los ajustes del equipo desde tu propio servidor. Codex obtiene esos ajustes independientemente de cómo enrute las solicitudes al modelo.
Usa Precedencia de la configuración para elegir dónde distribuir los valores predeterminados. Para los ajustes obligatorios y las cargas de configuración MDM de macOS, consulta Configuración administrada.
Para los valores predeterminados de todo el equipo en macOS o Linux, usa /etc/codex/config.toml. En
Windows, coloca config.toml en %ProgramData%\OpenAI\Codex\. Los usuarios y
los perfiles pueden sobrescribir estos valores predeterminados. Las referencias enlazadas describen los requisitos
compatibles y las ubicaciones de sus archivos.
Distribuye por separado los ejecutables auxiliares y los archivos de catálogo locales a los que se haga referencia.
Para aplicar obligatoriamente una URL de catálogo remoto, incluye la definición completa del proveedor en
requirements.toml bajo [model_providers.<id>]. Una definición de proveedor
obligatoria reemplaza la tabla del proveedor correspondiente de la configuración ordinaria;
incluye su base_url, la configuración de autenticación y otros campos obligatorios.
Usa el requisito model_provider cuando también necesites aplicar obligatoriamente la selección del
proveedor.
model_catalog_json apunta a un archivo JSON local. Si lo impones mediante
requirements.toml, el requisito fija la ruta; no distribuye el
archivo. Coloca el catálogo en esa ruta absoluta antes de que se inicie Codex.
Escribe rutas absolutas de Windows ya resueltas en TOML. Codex no expande
%ProgramData% dentro de model_catalog_json ni en los valores de command de autenticación del proveedor. Por
ejemplo, usa estas rutas solo si tu despliegue colocó los archivos allí:
model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'
[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]Una CLI dentro de WSL lee rutas de Linux y el CODEX_HOME de Linux; no hereda automáticamente
la configuración nativa de Windows.
Distribuir los encabezados de enrutamiento
Si tu puerta de enlace enruta las solicitudes según la configuración o la herramienta, añade los encabezados que espera al proveedor en tu archivo requirements.toml administrado. El siguiente ejemplo proporciona un ID de configuración de enrutamiento e identifica a Codex como cliente:
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'Usa env_http_headers para los valores de encabezado proporcionados por el entorno del cliente. Envía una solicitud de prueba y confirma la ruta seleccionada en los registros de la puerta de enlace. Consulta Proveedores de modelos personalizados para conocer las opciones de encabezado.
Entregar los valores de configuración a los desarrolladores
Proporciona a los desarrolladores un único procedimiento de configuración que coincida con la prueba piloto realizada. Incluye la siguiente información incluso si distribuyes la configuración de forma centralizada:
| Elemento de la entrega | Información que debe proporcionar |
|---|---|
| Cliente aprobado | El cliente, la versión, el sistema operativo y las instrucciones de instalación o actualización usados en la prueba piloto. |
| Distribución de la configuración | Si los ajustes ya están administrados o requieren configuración local; identifica cualquier archivo de catálogo o herramienta auxiliar instalado por separado. |
| Conexión esperada | El ID del proveedor, el alias del modelo y la URL de la puerta de enlace, incluida su ruta de API. Explica qué valores pueden cambiar los usuarios. |
| Pasos para iniciar sesión | Si los usuarios deben iniciar sesión en un espacio de trabajo de ChatGPT, autenticarse en la puerta de enlace o hacer ambas cosas. Indica el espacio de trabajo requerido y el método de autenticación de la puerta de enlace. |
| Credenciales y catálogos | Los valores de registro de OAuth, la variable de entorno de la credencial o la configuración de la herramienta auxiliar instalada, además de cualquier URL de catálogo o ruta local resuelta. Entrega los secretos mediante tu mecanismo aprobado de distribución de secretos. |
| Verificación y soporte | La prueba de conexión, el resultado esperado, el responsable de la puerta de enlace y la información que debe incluirse al notificar un fallo. |
Para los equipos administrados, remite a los desarrolladores a Comprobar si existe una configuración. Para la configuración manual, remítelos a Configurar el proveedor.
Incluye las instrucciones que haya probado para las conversaciones existentes si esta implementación cambia el proveedor. Mantén la configuración anterior que funcionaba a disposición del responsable de la implementación por si la prueba piloto revela algún problema.
La configuración manual no es un canal para imponer ajustes. El .codex/config.toml local del proyecto no puede sobrescribir claves sensibles del proveedor o del enrutamiento de autenticación.
Verificar desde el equipo de un desarrollador
Para confirmar que los ajustes distribuidos llegaron al equipo de un desarrollador:
- Confirma que el cliente aprobado y los archivos de herramientas auxiliares o catálogos necesarios estén instalados. Reinicia Codex y completa los inicios de sesión indicados en la documentación de entrega.
- Confirma el proveedor y el modelo esperados. En la CLI, usa
/status. Usa/debug-configpara inspeccionar las capas de configuración cuando los ajustes efectivos difieran de los indicados en la documentación de entrega. - Ejecuta la prueba breve de Conectarse a una puerta de enlace.
- Haz una pregunta de seguimiento para confirmar la continuación y, después, busque en los registros de la puerta de enlace la solicitud de ese desarrollador.
Amplía el acceso una vez que la prueba piloto se complete correctamente en los clientes y las combinaciones de autenticación que admites. Conserva la configuración probada y los resultados junto con las instrucciones de implementación para poder repetir las comprobaciones después de actualizar el cliente, la puerta de enlace o las políticas.
Solucionar fallos de implementación
Utiliza el problema para identificar la capa de configuración, credenciales o pasarela que necesita atención:
| Problema | Solución |
|---|---|
| El proveedor esperado no aparece tras reiniciar. | Inspecciona la capa de configuración que tiene prioridad. La configuración del usuario o del perfil puede anular los valores predeterminados del sistema. |
| La autenticación falla para todos los usuarios. | Comprueba la autenticación de la puerta de enlace y la credencial del proveedor de destino; identifica qué servicio rechazó la solicitud. |
| La autenticación falla para un usuario. | Comprueba el acceso de ese usuario al proveedor de identidad, su credencial de la puerta de enlace o su programa de obtención de tokens. |
| La transmisión se bloquea. | Inspecciona el almacenamiento en búfer de la puerta de enlace y el reenvío del evento final response.completed. |
| Falta un modelo o utiliza capacidades genéricas. | Para un alias personalizado, confirma que coincidan el alias de la puerta de enlace, model de Codex y slug del catálogo. Comprueba la ruta del catálogo y su compatibilidad con la versión de Codex instalada; después, reinicia Codex. |
| Falla una ruta de Windows. | Utiliza rutas absolutas resueltas. En TOML, utiliza cadenas entre comillas simples para las rutas de Windows con barras invertidas simples. |
Reutilizar un despliegue de pasarela existente
Si tu organización ya utiliza Claude Code a través de una pasarela, es posible
que puedas reutilizar el producto de pasarela, la ruta de red, el registro y el acceso a Bedrock. Añade una
ruta de Responses para Codex, una credencial, alias de modelos y config.toml, y
conserva la configuración existente que funciona. Los ajustes del cliente Claude y el
contrato de /v1/messages no configuran Codex.
| Implementación de Claude existente | Migración a Codex |
|---|---|
| Producto de puerta de enlace, DNS, TLS, redes privadas, registros, ocultación de datos sensibles y supervisión | Mantén estos servicios. Añade una ruta para Codex que cumpla los requisitos de compatibilidad de la puerta de enlace. |
| Cuenta de Bedrock, credencial del proveedor, límite de IAM, perfiles de inferencia y rotación de credenciales | Consérvalos solo cuando autoricen los modelos de destino a los que apuntan los nuevos alias de Codex. La credencial del proveedor permanece en la puerta de enlace. |
Ruta /v1/messages de Claude, estructura de InvokeModel de Bedrock, encabezados de Anthropic y reintentos o errores específicos de Claude |
No los reutilices como prueba de compatibilidad. Codex necesita POST /v1/responses, transmisión de Responses, continuación, llamadas a herramientas y errores útiles. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY o apiKeyHelper |
Codex no admite apiKeyHelper. Configura OAuth nativo de la puerta de enlace, una clave con ámbito limitado mediante env_key o un programa de obtención de tokens de Codex mediante comandos. |
Nombres de modelos de Claude, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides y asignaciones de perfiles de Bedrock |
Pide al equipo de la puerta de enlace que elija los nombres de los modelos y configura los alias personalizados necesarios. Utiliza el nombre del modelo y cualquier JSON del catálogo de modelos que te proporcionen. |
settings.json de Claude, managed-settings.json, bloques JSON env, plist o cargas útiles del registro |
Mantén el mismo canal de MDM o de administración de la configuración, pero distribuye config.toml de Codex y los valores admitidos de requirements.toml en su lugar. |
Para migrar de forma segura, completa estos pasos en orden:
- Haz un inventario de la ruta actual de Claude: URL de la puerta de enlace, origen de las credenciales, encabezados necesarios, alias de modelos, asignaciones de perfiles de Bedrock y canal de distribución administrado.
- Añade una ruta de Responses paralela para Codex y alias de modelos de Codex.
- Elige entre OAuth nativo de la puerta de enlace, una API key o una herramienta auxiliar de credenciales y autoriza a un usuario de prueba. Para una credencial estática, proporciona la credencial mediante
env_key; para una herramienta auxiliar, implementa y prueba el contrato del resolvedor de Codex basado en comandos. - Configura el proveedor para ese desarrollador con el método de autenticación que seleccionó en el paso 3. Para una implementación administrada, adapta la carga útil a las rutas y la precedencia de Codex descritas en Implementar una puerta de enlace.
- Ejecuta la comprobación breve de conexión en la CLI o la interfaz de escritorio que realmente usa el desarrollador y, después, ejecute todas las comprobaciones de streaming, continuación, llamadas a herramientas, errores, registros y enrutamiento de alias de Probar Codex a través de la puerta de enlace.
- Una vez superada la prueba piloto, distribuye la configuración al resto de los desarrolladores.
Referencia del catálogo de modelos
Empezar con un archivo models.json local
Primero, configura y selecciona el proveedor de tu puerta de enlace en el equipo donde ejecuta Codex.
Guarda este catálogo como models.json en el equipo que ejecuta Codex. Sustituye
gateway-model por el ID de modelo exacto que acepta tu puerta de enlace. El nombre para mostrar
es la etiqueta que ven los usuarios en el selector de modelos.
{
"models": [
{
"slug": "gateway-model",
"display_name": "Gateway model",
"base_instructions": "Help the user with their coding tasks.",
"supported_reasoning_levels": [],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": true,
"priority": 0,
"support_verbosity": false,
"truncation_policy": { "mode": "tokens", "limit": 10000 },
"experimental_supported_tools": []
}
]
}Para ver un ejemplo más amplio, consulta el catálogo de modelos de Codex.
Establece model_catalog_json en config.toml con la ruta absoluta del archivo.
Reinicia Codex, selecciona Gateway model y envíe una solicitud. Comprueba que la
puerta de enlace haya recibido el ID de modelo que estableció en slug.
Para un alias de un modelo incluido, copia su entrada completa del catálogo para tu versión de Codex
y cambia sus valores de slug y display_name. Si el alias no tiene un destino de migración, establece upgrade en null. Esto conserva la ventana de contexto,
las opciones de razonamiento y los ajustes de herramientas del modelo.
Servir un catálogo a los clientes
Esta página está dirigida a los desarrolladores que implementan el formato Codex Models, que define el catálogo de modelos y permite el funcionamiento del selector de modelos. Si desarrollas un proveedor de inferencia, como una puerta de enlace o un servicio en la nube, usa esta especificación para que la aplicación de escritorio de Codex y la CLI descubran sus modelos y usen sus instrucciones y ajustes de capacidades.
Si administras una empresa y deseas controlar el catálogo de modelos, consulta las
instrucciones de configuración de model_catalog_url.
Para admitir este formato, implementa un endpoint de catálogo autenticado. Obtén los valores predeterminados actuales de tu proveedor de origen para la versión de Codex que realiza la solicitud, aplica sus modificaciones y devuelve el catálogo resultante.
client_version Implementa el endpoint del catálogo
El endpoint predeterminado del catálogo es /models bajo el base_url del proveedor.
Por ejemplo, con base_url = "https://gateway.example.com/v1", Codex solicita:
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>El descubrimiento predeterminado admite la autenticación mediante comandos y la autenticación del backend de Codex,
como la de ChatGPT. Para un proveedor personalizado que use autenticación mediante API key
sin autenticación mediante comandos, configura model_providers.<id>.model_catalog_url
explícitamente para habilitar el descubrimiento remoto. Una API key por sí sola no activa el descubrimiento
en la ruta predeterminada.
Usa model_catalog_url para elegir una URL completa del catálogo, como
https://gateway.example.com/codex/models. También puedes apuntar al endpoint predeterminado
/v1/models. Codex usa esta URL directamente sin añadir /models.
Para el descubrimiento mediante API key, mantén features.api_key_model_discovery habilitado; está activado
de forma predeterminada. Los encabezados personalizados por sí solos no habilitan el descubrimiento.
Codex envía la autenticación del proveedor seleccionado y los encabezados configurados, y
añade client_version y cualquier query_params del proveedor. Aloja el catálogo en un
servicio autorizado para recibir esas credenciales.
Autentica al solicitante, obtén los valores predeterminados de origen correspondientes, aplica sus
modificaciones y devuelve directamente el JSON completo de ModelsResponse. Asigna a cada
entrada un slug único y no vacío. Para un model_catalog_url explícito, Codex rechaza
las redirecciones y las respuestas de más de 1 MiB. Sigue aplicando los controles de acceso a los modelos en
las solicitudes de inferencia.
Elimina cualquier ajusta model_catalog_json que esté en vigor en los clientes que usen el endpoint:
el archivo local tiene prioridad e impide la obtención remota.
Adáptate al esquema del cliente
Lee el parámetro de consulta client_version de la solicitud del catálogo. Codex envía su
versión de CLI como major.minor.patch, sin ningún sufijo de versión preliminar. Para los clientes de escritorio,
se trata de la versión de CLI incluida.
Usa la etiqueta rust-v<version> correspondiente del repositorio público de Codex, o el
commit exacto del código fuente para una compilación personalizada. Estos enlaces usan rust-v0.162.1; selecciona
la revisión que corresponda a su cliente:
- Consulta los tipos de respuesta
ModelsResponseyModelInfopara conocer el esquema. - Examina el
models.jsonincluido para ver un ejemplo completo. Contiene datos del catálogo, no un documento JSON Schema.
El archivo incluido es una instantánea de una versión. Obtén los valores predeterminados actuales antes de generar tu catálogo.
Obtén los valores predeterminados actuales del proveedor de origen
Los proveedores de nube que ofrecen modelos de OpenAI obtienen los valores predeterminados de OpenAI. Las puertas de enlace leen el catálogo de tu proveedor de nube o de origen para conservar los ajustes del modelo desplegado y la disponibilidad por cuenta y región. Pasa la versión de Codex que realiza la solicitud en cada paso y autentícate por separado en cada endpoint.
Para obtener los valores predeterminados directamente de OpenAI, llama al endpoint de modelos de Codex con el
mismo client_version. Por ejemplo, con una API key de OpenAI:
curl --fail --silent --show-error \
'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
-H "Authorization: Bearer $OPENAI_API_KEY"Para una integración con ChatGPT, usa el token de acceso a ChatGPT del solicitante y
el encabezado ChatGPT-Account-ID cuando corresponda. Usa credenciales autorizadas para el
endpoint de origen; la API key de tu puerta de enlace no sirve para autenticarse en OpenAI.
Analiza la respuesta completa, incluida su matriz models de nivel superior. Este endpoint
devuelve metadatos de Codex, como instrucciones, valores predeterminados de razonamiento, ajustes de herramientas,
límites de contexto y niveles de servicio. El endpoint público /v1/models no
proporciona este catálogo.
Actualiza estos valores predeterminados incluso cuando la versión de Codex no haya cambiado. Mantén las solicitudes limitadas a la identidad de origen prevista y respeta los controles de caché de las respuestas: los catálogos pueden depender del acceso del solicitante. Mantén sus modificaciones por separado para poder volver a aplicarlas a los valores predeterminados actualizados.
Aplique las modificaciones del proveedor
Cambia los valores de los campos conservando la estructura de respuesta de la versión:
- Filtra los modelos para incluir solo los que el solicitante pueda usar. Asocia cada
sluga una ruta de inferencia compatible y ajustadisplay_name,descriptionopriority. Para un alias sin migración de modelo, estableceupgradeennull. - Establece las opciones de razonamiento, los límites de contexto, las modalidades de entrada y los niveles de servicio en
valores que admitan tu modelo y tu ruta. Mantén los valores predeterminados entre las opciones
compatibles. Para una ruta sin niveles de servicio, vacía
service_tiersyadditional_speed_tiers, y establecedefault_service_tierennull. - Conserva las instrucciones y los ajustes de herramientas del proveedor de origen a menos que haya probado una alternativa. Los metadatos no añaden capacidades al modelo ni conceden acceso a la inferencia.
Para un alias de modelo de la puerta de enlace, consulta cómo proporcionar metadatos del modelo. Prueba el catálogo resultante con cada versión de Codex compatible.
Usa los tipos públicos de Rust
Usa crates de la misma etiqueta o commit público de Git que el esquema del cliente:
- Usa
codex-protocolparacodex_protocol::openai_models::{ModelsResponse, ModelInfo}. Analiza conserde_json::from_slice::<ModelsResponse>(), editacatalog.modelsy serializa toda la estructura contenedora conserde_json::to_vec(). La estructura contenedora gestiona los campos de compatibilidad de las instrucciones del modelo. - Usa
codex-models-manager::bundled_models_response()para cargar el catálogo estático incluido en esa revisión como unModelsResponse. No obtiene los valores predeterminados actuales del proveedor de origen.