Requisitos de compatibilidad de las pasarelas

Las pasarelas de Codex deben conservar el comportamiento de la Responses API descrito aquí: endpoints, transmisión, continuación, llamadas a herramientas, autenticación, enrutamiento y errores útiles.

Solicitudes y endpoints

Configura un proveedor de pasarela con wire_api = "responses". Para una URL base como https://gateway.example.com/v1, la pasarela debe aceptar POST /v1/responses y conservar los campos de solicitud y respuesta que utiliza el cliente. Un endpoint funcional de Chat Completions o Anthropic Messages no demuestra compatibilidad con Responses.

Los endpoints de estado y de lista de modelos son ayudas operativas opcionales. No ponen a prueba una conversación de Codex ni demuestran la compatibilidad con herramientas.

Transmisión

Reenvía los eventos enviados por el servidor (SSE) de forma incremental en lugar de almacenar toda la respuesta en búfer. Conserva los tipos de eventos y sus cargas útiles, incluido el evento final de éxito response.completed. Reenvía los eventos de error y fallo para que el cliente pueda distinguir una respuesta fallida de una conexión detenida.

Verifica la transmisión completa a través de los balanceadores de carga y los proxies inversos, además de la pasarela. Una respuesta de texto sin una transmisión completada es insuficiente.

Continuación de la conversación

Conserva las entradas de conversación reenviadas entre turnos de seguimiento. La pasarela debe aceptar los mensajes anteriores, las llamadas a herramientas y los resultados de herramientas necesarios para el siguiente turno.

Si habilitas WebSocket o el transporte incremental, verifica también su comportamiento de previous_response_id. Una ruta HTTP de Responses sin estado puede utilizar entradas reenviadas sin necesitar ese mecanismo de continuación.

Herramientas

Conserva los elementos de llamada a funciones y sus elementos function_call_output correspondientes, incluidos los identificadores que asocian las llamadas con los resultados. El ciclo completo debe funcionar: Codex recibe una llamada, ejecuta la herramienta, envía su 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 una pasarela acepte un campo de solicitud no demuestra que su modelo de origen implemente la capacidad correspondiente.

Autenticación y encabezados

Admite el mecanismo de autenticación del cliente seleccionado para el despliegue: env_key o tokens de portador obtenidos mediante comandos, o env_http_headers para las credenciales enviadas en un encabezado personalizado. Usa variables de entorno para los valores secretos de los encabezados; no los escribas directamente en la configuración. Consulta la referencia de proveedores personalizados para conocer la configuración y el contrato del asistente de credenciales.

Autentica a los desarrolladores por separado de la identidad del proveedor de origen de la pasarela. Mantén las claves de administrador y las credenciales de origen en la pasarela. 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 credenciales.

Enrutamiento de modelos y metadatos

Cada nombre de modelo para Codex debe dirigir al modelo de origen previsto. Verifica la ruta en los registros de la pasarela en lugar de confiar en la descripción que el modelo hace de sí mismo.

Usa un nombre reconocido por la versión desplegada de Codex o proporciona un catálogo correspondiente para un alias personalizado. Revisa también la disponibilidad de los modelos y los metadatos de migración: cualquier modelo de reemplazo debe pasar por la pasarela. Para un alias propiedad de la organización sin migración, establece upgrade de su entrada de catálogo en null. Los metadatos del catálogo orientan el comportamiento del cliente; no añaden capacidades a un modelo ni crean rutas en la pasarela. Verifica los límites de contexto, las opciones de razonamiento y las herramientas con respecto al modelo de origen y al proveedor reales. Una conexión genérica a una pasarela no recibe automáticamente los ajustes de metadatos que realizan las integraciones de proveedores incorporadas en Codex.

Nombres de modelos reconocidos

Usa el nombre exacto del modelo reconocido por tu versión desplegada de Codex como alias de la pasarela y como model de Codex. Confirma que el proveedor de origen admita el modelo y que tu organización lo apruebe.

Comprueba codex --version y selecciona la etiqueta rust-v<version> correspondiente en el catálogo de modelos de Codex. Para una compilación personalizada, usa su commit de origen; para los despliegues de escritorio, utiliza la versión de la CLI incluida. Comprueba los valores de slug de las entradas para encontrar los nombres que reconoce esa versión. Si la pasarela cambia las capacidades del modelo, proporciona metadatos del catálogo que reflejen esas diferencias, incluso cuando el nombre sea reconocido.

Errores

Conserva distinciones útiles entre los errores de autenticación del cliente, las rutas de modelos desconocidas, los límites de frecuencia y los fallos de origen. No conviertas todos los fallos en una respuesta genérica de 500. Devuelve información suficiente para diagnosticar la capa que falla sin exponer tokens, credenciales del proveedor ni contenido sensible de las solicitudes.

Límites de datos y herramientas

El tráfico de modelos sigue esta ruta:

Codex client -> LLM gateway -> model provider

El cliente se autentica en la pasarela con una credencial de desarrollador. La pasarela utiliza su credencial del proveedor de origen para acceder al modelo. Los prompts, los fragmentos de código fuente, los argumentos de herramientas y los resultados de herramientas incluidos en las solicitudes al modelo pueden pasar por la pasarela. Establece los controles de registro, retención, ocultación de datos sensibles, acceso y exportación en consecuencia.

La pasarela de modelos no dirige todas las conexiones que realiza Codex. Los comandos locales se ejecutan en el entorno de ejecución del cliente. Los MCP servers, los servicios de plugins, las interacciones con navegadores y aplicaciones, y otros servicios habilitados pueden tener rutas de red y credenciales independientes. La configuración del proveedor de modelos no concede esos permisos ni reemplaza sus controles de red. Consulta Aprobaciones y seguridad del agente y MCP para conocer esos límites.

Lista de verificación de compatibilidad

Registra evidencia para cada combinación desplegada de cliente, pasarela y modelo:

• Campos de solicitud y respuesta de Responses.
• Entrega incremental de SSE y finalización exitosa.
• Turnos de seguimiento con entradas reenviadas.
• previous_response_id cuando el transporte seleccionado lo utilice.
• Llamadas a funciones, resultados correspondientes y una respuesta final.
• Enrutamiento correcto de modelos y metadatos coincidentes.
• Atribución, renovación y revocación por usuario.
• Errores útiles de autenticación, enrutamiento, límites de frecuencia y origen.
• Diagnósticos con datos sensibles ocultos y la política de registro prevista.

Usa el procedimiento de prueba de implementación para recopilar esta evidencia antes de distribuir la configuración.