Exigences de compatibilité des passerelles

Les passerelles Codex doivent préserver le comportement de l’API Responses décrit ici : points de terminaison, diffusion en continu, continuité des échanges, appels d’outils, authentification, routage et erreurs utiles.

Requêtes et points de terminaison

Configurez un fournisseur de 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 préserver les champs de requête et de réponse utilisés par le client. Un point de terminaison Chat Completions ou Anthropic Messages fonctionnel ne garantit pas la compatibilité avec Responses.

Les points de terminaison de contrôle d’état et de liste des modèles sont des aides opérationnelles facultatives. Ils ne testent pas une conversation Codex et ne prouvent pas la prise en charge des outils.

Diffusion en continu

Transmettez les événements envoyés par le serveur (SSE) progressivement au lieu de mettre en mémoire tampon l’intégralité de la réponse. Préservez les types d’événements et leurs charges utiles, y compris l’événement final de réussite response.completed. Transmettez les événements d’erreur et d’échec pour que le client puisse distinguer une réponse en échec d’une connexion bloquée.

Vérifiez le flux complet à travers les équilibreurs de charge et les proxys inverses, ainsi que la passerelle. Une réponse textuelle sans flux terminé est insuffisante.

Continuité de la conversation

Préservez les entrées de conversation rejouées lors des échanges de suivi. La passerelle doit accepter les messages précédents, les appels d’outils et les résultats d’outils nécessaires à l’échange suivant.

Si vous activez WebSocket ou le transport incrémental, vérifiez également son comportement previous_response_id. Un chemin Responses HTTP sans état peut utiliser les entrées rejouées sans nécessiter ce mécanisme de continuité.

Outils

Préservez les éléments d’appel de fonction et leurs éléments function_call_output correspondants, y compris les identifiants qui associent les appels aux résultats. La boucle complète doit fonctionner : Codex reçoit un appel, exécute l’outil, soumet son résultat et reçoit une réponse finale.

Une requête textuelle réussie ne valide pas cette boucle. Testez les modèles et les fonctionnalités du client que vous prévoyez réellement d’activer. Le fait qu’une passerelle accepte un champ de requête ne prouve pas que son modèle en amont implémente la capacité correspondante.

Authentification et en-têtes

Prenez en charge le mécanisme d’authentification du client choisi pour le déploiement : env_key ou des jetons bearer obtenus par 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 la configuration et le contrat de l’utilitaire de gestion des identifiants.

Authentifiez les développeurs séparément de l’identité utilisée par la passerelle auprès du fournisseur en amont. Conservez les clés d’administration et les identifiants en amont sur la passerelle. Préservez les en-têtes dont dépendent votre routage et votre attribution, et testez l’expiration, le renouvellement et la révocation des identifiants.

Routage et métadonnées des modèles

Chaque nom de modèle exposé à Codex doit être acheminé vers le modèle en amont prévu. Vérifiez la route dans les journaux de la passerelle plutôt que de vous fier à la description que le modèle donne de lui-même.

Utilisez un nom reconnu par la version déployée de Codex, ou fournissez un catalogue correspondant à un alias personnalisé. Examinez également la disponibilité des modèles et les métadonnées de migration : tout modèle de remplacement doit passer par la passerelle. Pour un alias propre à l’organisation sans migration, définissez upgrade dans son entrée de catalogue sur null. Les métadonnées du catalogue guident le comportement du client ; elles n’ajoutent pas de capacités à un modèle et ne créent pas de routes sur la passerelle. Vérifiez les limites de contexte, les options de raisonnement et les outils par rapport au modèle et au fournisseur réellement utilisés en amont. Une connexion générique à une passerelle ne reçoit pas automatiquement les ajustements de métadonnées apportés par les intégrations de fournisseurs intégrées à Codex.

Noms de modèles reconnus

Utilisez le nom exact du modèle reconnu par votre version déployée de Codex comme alias de passerelle et comme valeur de model dans Codex. Confirmez que le fournisseur en amont prend en charge le modèle et que votre organisation l’approuve.

Vérifiez codex --version et sélectionnez le tag rust-v<version> correspondant dans le catalogue de modèles Codex. Pour une compilation personnalisée, utilisez son commit source ; pour les déploiements de l’application de bureau, faites correspondre la version de la CLI intégrée. Vérifiez les valeurs slug des entrées pour trouver les noms que cette version reconnaît. Si la passerelle modifie les capacités du modèle, fournissez des métadonnées de catalogue qui reflètent ces différences, même si le nom est reconnu.

Erreurs

Préservez les distinctions utiles entre les erreurs d’authentification du client, les routes de modèles inconnues, les limites de débit et les défaillances en amont. Ne réduisez pas tous les échecs à une réponse générique 500. Renvoyez suffisamment d’informations pour diagnostiquer la couche défaillante sans exposer les jetons, les identifiants du fournisseur ni le contenu sensible des requêtes.

Périmètres des données et des outils

Le trafic des modèles 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 utilise son identifiant du fournisseur en amont pour accéder au modèle. Les prompts, les extraits de code source, les arguments des outils et les résultats d’outils inclus dans les requêtes au modèle peuvent passer par la passerelle. Définissez les contrôles de journalisation, de conservation, de masquage des données sensibles, d’accès et d’exportation en conséquence.

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 MCP servers, les services de plugins, les interactions avec le navigateur et les applications, ainsi que les autres services activés, peuvent avoir des chemins réseau et des identifiants distincts. La configuration du fournisseur de modèles n’accorde pas ces autorisations et ne remplace pas leurs contrôles réseau. Consultez Approbations de l’agent et sécurité et MCP pour connaître ces périmètres.

Liste de contrôle de qualification

Consignez les preuves pour chaque combinaison déployée de client, de passerelle et de modèle :

• Champs de requête et de réponse de Responses.
• Transmission progressive des événements SSE et terminaison réussie du flux.
• Échanges de suivi avec entrées rejouées.
• previous_response_id lorsque le transport sélectionné l’utilise.
• Appels de fonctions, résultats correspondants et réponse finale.
• Routage correct des modèles et métadonnées correspondantes.
• Attribution par utilisateur, renouvellement et révocation.
• Erreurs utiles d’authentification, de routage, de limite de débit et de défaillance en amont.
• Diagnostics expurgés des données sensibles et politique de journalisation prévue.

Utilisez la procédure de test du déploiement pour recueillir ces preuves avant de distribuer la configuration.