Exigences de compatibilité des passerelles

Ces exigences s’appliquent lorsque Codex se connecte via une passerelle avec des identifiants d’API ou de fournisseur. Pour les passerelles qui transmettent les requêtes d’un espace de travail ChatGPT, consultez Se connecter avec ChatGPT via une passerelle.

Dans ce cas, la passerelle doit respecter le fonctionnement de l’API Responses décrit ci-dessous, qu’il s’agisse des points de terminaison, de la transmission en continu, de la poursuite des conversations, des appels d’outils, de l’authentification, du routage ou des informations renvoyées en cas d’erreur.

Requêtes et points de terminaison

Configurez le fournisseur correspondant à la passerelle avec wire_api = "responses". Pour une URL de base telle que https://gateway.example.com/v1, la passerelle doit accepter POST /v1/responses et conserver les champs de requête et de réponse utilisés par le client. Le bon fonctionnement d’un point de terminaison Chat Completions ou Anthropic Messages ne suffit pas à établir la compatibilité avec l’API Responses.

Les points de terminaison qui indiquent l’état du service ou renvoient la liste des modèles sont facultatifs et facilitent l’exploitation. Ils ne permettent ni de tester une conversation Codex ni de confirmer la prise en charge des outils.

Transmission en continu

Transmettez les événements envoyés par le serveur (SSE) au fil de leur réception, sans mettre en mémoire tampon l’intégralité de la réponse. Conservez le type et le contenu de chaque événement, y compris ceux de l’événement final response.completed qui signale que la réponse s’est terminée avec succès. Transmettez les événements d’erreur et d’échec pour que le client puisse distinguer l’échec d’une réponse d’une connexion bloquée.

Vérifiez que le flux complet traverse les équilibreurs de charge et les proxys inverses, ainsi que la passerelle. La réception d’une réponse textuelle ne suffit pas si le flux ne s’est pas terminé.

Poursuite d’une conversation

Conservez les données d’entrée de la conversation que le client renvoie au fil des échanges. La passerelle doit accepter les messages, les appels d’outils et les résultats d’outils des échanges précédents dont le client a besoin pour poursuivre la conversation.

Si vous activez WebSocket ou un transport incrémental, vérifiez également comment ce transport gère previous_response_id. Avec HTTP, une connexion sans état à l’API Responses peut réutiliser les données d’entrée renvoyées par le client sans recourir à ce mécanisme de poursuite de la conversation.

Outils

Conservez les éléments d’appel de fonction et les éléments function_call_output correspondants, ainsi que les identifiants qui relient chaque appel à son résultat. Vérifiez le fonctionnement du cycle complet : Codex reçoit un appel, exécute l’outil, transmet son résultat et reçoit une réponse finale.

Une requête textuelle réussie ne valide pas ce cycle. Testez les modèles et les fonctionnalités du client que vous prévoyez d’activer. Même si la passerelle accepte un champ de requête, le modèle en amont ne prend pas nécessairement en charge la fonctionnalité correspondante.

Authentification et en-têtes

La passerelle doit prendre en charge le mécanisme d’authentification du client choisi pour le déploiement : env_key, des tokens de type Bearer obtenus à l’aide d’une commande, ou env_http_headers pour les identifiants transmis dans un en-tête personnalisé. Utilisez des variables d’environnement pour les valeurs secrètes des en-têtes. Ne les inscrivez pas en dur dans la configuration. Consultez la référence des fournisseurs personnalisés pour connaître les paramètres de configuration et l’interface que doit respecter l’utilitaire de gestion des identifiants.

Authentifiez chaque développeur indépendamment de l’identité que la passerelle utilise auprès du fournisseur en amont. Conservez les clés d’administration et les identifiants du fournisseur en amont sur la passerelle. Préservez les en-têtes qui servent au routage et à l’attribution des requêtes, puis testez l’expiration, le renouvellement et la révocation des identifiants.

Routage des modèles et métadonnées

Pour chaque nom de modèle exposé à Codex, la passerelle doit acheminer les requêtes vers le modèle en amont prévu. Vérifiez la destination dans les journaux de la passerelle sans vous fier à la façon dont le modèle se décrit.

Utilisez un nom reconnu par la version de Codex déployée ou fournissez un catalogue correspondant à l’alias personnalisé. Vérifiez également la disponibilité des modèles et les métadonnées de migration : les requêtes destinées à un modèle de remplacement doivent passer par la passerelle. Pour un alias propre à votre organisation et sans migration prévue, définissez le champ upgrade de son entrée de catalogue sur null. Le client s’appuie sur les métadonnées du catalogue pour adapter son comportement. Ces métadonnées n’ajoutent aucune fonctionnalité au modèle et ne créent aucune route dans la passerelle. Vérifiez les limites de contexte, les options de raisonnement et les outils auprès du fournisseur et pour le modèle effectivement utilisé en amont. Les ajustements de métadonnées qu’appliquent les intégrations de fournisseurs intégrées à Codex ne s’appliquent pas automatiquement à une connexion via une passerelle générique.

Noms de modèles reconnus

Utilisez le nom exact du modèle reconnu par votre version de Codex comme alias dans la passerelle et comme valeur du paramètre model dans Codex. Vérifiez que le fournisseur en amont prend en charge ce modèle et que votre organisation en approuve l’utilisation.

Vérifiez la version avec codex --version, puis sélectionnez le tag rust-v<version> correspondant dans le catalogue des modèles de Codex. Pour une compilation personnalisée, utilisez le commit du code source correspondant. Pour un déploiement de l’application de bureau, utilisez la version de la CLI fournie avec l’application. Consultez le champ slug de chaque entrée pour connaître les noms reconnus par cette version. Si la passerelle modifie les fonctionnalités du modèle, fournissez des métadonnées de catalogue qui reflètent ces différences, même si Codex reconnaît son nom.

Erreurs

Veillez à ce que le client puisse distinguer les erreurs d’authentification du client, les routes de modèle inconnues, les dépassements de limites de débit et les défaillances en amont. Ne renvoyez pas une réponse 500 générique pour tous les échecs. Fournissez assez d’informations pour identifier le composant en cause sans exposer de tokens, d’identifiants de fournisseur ni de contenu sensible des requêtes.

Circulation des données et périmètre des outils

Le trafic destiné au modèle suit ce chemin :

Codex client -> LLM gateway -> model provider

Le client s’authentifie auprès de la passerelle avec un identifiant de développeur. La passerelle accède au modèle avec ses propres identifiants auprès du fournisseur en amont. Les prompts, les extraits de code source, les arguments des outils et leurs résultats peuvent transiter par la passerelle lorsqu’ils figurent dans les requêtes destinées au modèle. Configurez en conséquence la journalisation, la conservation et le masquage des données, ainsi que les contrôles d’accès et d’exportation.

La passerelle de modèles n’achemine pas toutes les connexions établies par Codex. Les commandes locales s’exécutent dans l’environnement d’exécution du client. Les serveurs MCP, les services des plugins, les interactions avec le navigateur et les applications, ainsi que les autres services activés peuvent utiliser des chemins réseau et des identifiants distincts. La configuration du fournisseur de modèles n’accorde pas les autorisations d’accès à ces services et ne remplace pas leurs contrôles réseau. Pour connaître le périmètre de ces contrôles, consultez Approbations et sécurité des agents et MCP.

Liste de vérification pour la qualification

Pour chaque combinaison de client, de passerelle et de modèle déployée, consignez les résultats des vérifications suivantes :

• Conservation des champs de requête et de réponse de l’API Responses.
• Transmission progressive des événements SSE et réception de l’événement final de succès.
• Poursuite de la conversation avec les données d’entrée renvoyées par le client.
• Prise en charge de previous_response_id lorsque le transport choisi l’utilise.
• Appels de fonction, résultats correspondants et réception d’une réponse finale.
• Routage vers le modèle prévu et concordance des métadonnées.
• Attribution des requêtes à chaque utilisateur, renouvellement et révocation de ses identifiants.
• Messages d’erreur permettant de diagnostiquer les problèmes d’authentification, de routage, de limite de débit et de traitement en amont.
• Masquage des données sensibles dans les diagnostics et application de la politique de journalisation prévue.

Suivez la procédure de test du déploiement pour recueillir ces éléments avant de distribuer la configuration.