Requisitos de compatibilidad de la puerta de enlace

Estos requisitos se aplican cuando Codex se conecta a través de una puerta de enlace con credenciales de API o del proveedor. Si la puerta de enlace reenvía solicitudes del Espacio de trabajo de ChatGPT, consulta Iniciar sesión con ChatGPT a través de una puerta de enlace.

Para este tipo de conexión, la puerta de enlace debe conservar el comportamiento de la API Responses que se describe aquí, incluidos los puntos de acceso, la transmisión incremental, la continuación de las conversaciones, las llamadas a herramientas, la autenticación, el enrutamiento y los mensajes de error que permiten diagnosticar problemas.

Solicitudes y puntos de acceso

Configura un proveedor de puerta de enlace con wire_api = "responses". Si la URL base es, por ejemplo, https://gateway.example.com/v1, la puerta de enlace debe aceptar POST /v1/responses y conservar los campos de solicitud y respuesta que usa el cliente. Que un punto de acceso de Chat Completions o Anthropic Messages funcione no demuestra que la puerta de enlace sea compatible con Responses.

Los puntos de acceso para consultar el estado del servicio y la lista de modelos son opcionales y facilitan la operación. Consultarlos no pone a prueba una conversación de Codex ni demuestra que se puedan usar herramientas.

Transmisión incremental

Reenvía los eventos enviados por el servidor (SSE) a medida que llegan, sin esperar a que se acumule toda la respuesta. Conserva los tipos de evento y los datos que contienen, incluido el evento final response.completed, que indica que la respuesta se completó correctamente. Reenvía los eventos de error y de fallo para que el cliente pueda distinguir entre una respuesta fallida y una conexión que dejó de transmitir datos.

Verifica la transmisión completa tanto a través de la puerta de enlace como de los balanceadores de carga y los proxies inversos. Recibir una respuesta de texto no basta si la transmisión no se completa.

Continuación de la conversación

Conserva los datos de entrada de la conversación que se vuelven a enviar en los turnos posteriores. La puerta de enlace debe aceptar los mensajes, las llamadas a herramientas y los resultados de herramientas de turnos anteriores que se necesitan para el siguiente turno.

Si habilitas WebSocket o el transporte incremental, verifica también cómo se maneja previous_response_id. Una conexión HTTP sin estado a la API Responses puede usar los datos de entrada reenviados sin necesidad de ese mecanismo de continuación.

Herramientas

Conserva los elementos de llamada a funciones y los elementos function_call_output correspondientes, incluidos los identificadores que vinculan cada llamada con su resultado. El ciclo debe funcionar de principio a fin: Codex recibe una llamada, ejecuta la herramienta, envía el resultado y recibe una respuesta final.

Una solicitud de texto exitosa no verifica este ciclo. Prueba los modelos y las funciones del cliente que planeas habilitar. Que la puerta de enlace acepte un campo de solicitud no demuestra que el modelo del proveedor implemente la capacidad correspondiente.

Autenticación y encabezados

Asegúrate de que la puerta de enlace admita el mecanismo de autenticación del cliente elegido para el despliegue: env_key o tokens de portador obtenidos mediante un comando, o bien env_http_headers para las credenciales que se envían en un encabezado personalizado. Usa variables de entorno para los valores secretos de los encabezados. No escribas esos valores directamente en la configuración. Consulta la referencia sobre proveedores personalizados para conocer la configuración y el contrato que debe cumplir el asistente de credenciales.

Autentica a los desarrolladores por separado de la identidad que usa la puerta de enlace ante el proveedor. Mantén las claves de administrador y las credenciales de acceso al proveedor en la puerta de enlace. Conserva los encabezados de los que dependen el enrutamiento y la atribución, y prueba el vencimiento, la renovación y la revocación de las credenciales.

Enrutamiento de modelos y metadatos

Cada nombre de modelo que se presenta a Codex debe dirigir las solicitudes al modelo previsto del proveedor. Verifica la ruta en los registros de la puerta de enlace en lugar de confiar en la descripción que el modelo da de sí mismo.

Usa un nombre que reconozca la versión de Codex desplegada o proporciona un catálogo que corresponda al alias personalizado. Revisa también la disponibilidad de los modelos y los metadatos de migración. Las solicitudes a cualquier modelo de reemplazo deben pasar por la puerta de enlace. Si el alias pertenece a la organización y no tiene una migración asociada, establece el campo upgrade de su entrada de catálogo en null. El cliente usa los metadatos del catálogo para determinar cómo se comporta. Estos metadatos no agregan capacidades al modelo ni crean rutas en la puerta de enlace. Comprueba los límites de contexto, las opciones de razonamiento y las herramientas con el modelo y el proveedor que realmente usas. Una conexión genérica a través de una puerta de enlace no recibe automáticamente los ajustes de metadatos que aplican las integraciones de proveedores incorporadas en Codex.

Nombres de modelos reconocidos

Usa el nombre exacto del modelo que reconoce la versión de Codex desplegada tanto para el alias de la puerta de enlace como para el valor de model en Codex. Confirma que el proveedor admite el modelo y que tu organización aprueba su uso.

Comprueba la versión con codex --version y selecciona la etiqueta rust-v<version> correspondiente en el catálogo de modelos de Codex. Si usas una compilación personalizada, consulta el commit a partir del cual se compiló. Para despliegues de escritorio, usa la versión de la CLI incluida. Revisa los valores de slug en las entradas para encontrar los nombres que reconoce esa versión. Si la puerta de enlace cambia las capacidades del modelo, proporciona metadatos de catálogo que reflejen esas diferencias, incluso si Codex reconoce el nombre.

Errores

Conserva la información que permite distinguir los errores de autenticación del cliente, las rutas de modelo desconocidas, los límites de solicitudes y los fallos del proveedor. No devuelvas una respuesta 500 genérica para todos los fallos. Devuelve información suficiente para identificar la capa donde se produjo el fallo sin exponer tokens, credenciales del proveedor ni contenido sensible de las solicitudes.

Alcance de la puerta de enlace para datos y herramientas

El tráfico de los modelos sigue esta ruta:

Codex client -> LLM gateway -> model provider

El cliente se autentica ante la puerta de enlace con una credencial de desarrollador. La puerta de enlace usa su credencial de acceso al proveedor para acceder al modelo. Los prompts, los fragmentos de código fuente, los argumentos de herramientas y sus resultados pueden pasar por la puerta de enlace si se incluyen en las solicitudes al modelo. Tenlo en cuenta al configurar los controles de registro, retención, ocultación de datos sensibles, acceso y exportación.

La puerta de enlace de modelos no enruta todas las conexiones de Codex. Los comandos locales se ejecutan en el entorno de ejecución del cliente. Los servidores MCP, los servicios de complementos, las interacciones con navegadores y aplicaciones, y otros servicios habilitados pueden usar rutas de red y credenciales independientes. La configuración del proveedor de modelos no otorga esos permisos ni sustituye los controles de red de esos servicios. Para conocer esos límites, consulta Aprobaciones y seguridad de los agentes y MCP.

Lista de verificación de compatibilidad

Para cada combinación de cliente, puerta de enlace y modelo que despliegues, documenta los resultados de estas comprobaciones:

• Campos de solicitud y respuesta de la API Responses.
• Entrega incremental de eventos SSE y recepción del evento final que indica que la transmisión se completó correctamente.
• Turnos posteriores con reenvío de los datos de entrada.
• previous_response_id cuando lo usa el transporte seleccionado.
• Llamadas a funciones, resultados correspondientes y respuesta final.
• Enrutamiento al modelo correcto y metadatos correspondientes.
• Atribución por usuario, renovación y revocación de credenciales.
• Mensajes de error que permiten diagnosticar problemas de autenticación o enrutamiento, identificar límites de solicitudes alcanzados y detectar fallos del proveedor.
• Datos sensibles ocultos en los diagnósticos y aplicación de la política de registro prevista.

Usa el procedimiento de prueba del despliegue para recopilar estas evidencias antes de distribuir la configuración.