Requisitos de compatibilidade do gateway

Estes requisitos se aplicam ao acesso por um gateway com credenciais da API ou do provedor. Para gateways que encaminham solicitações de espaços de trabalho do ChatGPT, consulte Entrar com o ChatGPT por um gateway.

Nesse tipo de acesso, o gateway deve preservar o comportamento da API Responses descrito aqui. Isso inclui os endpoints, o streaming, a continuidade da conversa, as chamadas de ferramentas, a autenticação, o roteamento e as informações de erro necessárias para o diagnóstico.

Solicitações e endpoints

Configure um provedor de gateway com wire_api = "responses". Para uma URL base como https://gateway.example.com/v1, o gateway deve aceitar POST /v1/responses e preservar os campos de solicitação e resposta que o cliente usa. O funcionamento de um endpoint de Chat Completions ou de Anthropic Messages não comprova a compatibilidade com a API Responses.

Os endpoints de verificação de integridade e de listagem de modelos são recursos operacionais opcionais. Eles não testam uma conversa do Codex nem comprovam o suporte a ferramentas.

Streaming

Encaminhe os eventos enviados pelo servidor (SSE) à medida que chegarem, sem esperar pela resposta inteira. Preserve os tipos de evento e seus dados, inclusive o evento final response.completed, que indica a conclusão bem-sucedida. Encaminhe os eventos de erro e de falha para que o cliente possa distinguir uma falha na resposta de uma conexão que parou de transmitir dados.

Verifique o fluxo completo tanto no gateway quanto nos balanceadores de carga e proxies reversos. Receber uma resposta em texto é insuficiente se o fluxo não for concluído.

Continuidade da conversa

Preserve os dados de entrada da conversa que o cliente reenvia nos turnos seguintes. O gateway deve aceitar as mensagens, as chamadas de ferramentas e os resultados de ferramentas dos turnos anteriores necessários para o próximo turno.

Se você habilitar o WebSocket ou o transporte incremental, verifique também como o transporte lida com previous_response_id. O acesso à API Responses por HTTP sem estado pode usar os dados de entrada reenviados sem exigir esse mecanismo de continuidade.

Ferramentas

Preserve os itens de chamada de função e os itens function_call_output correspondentes, inclusive os identificadores que associam as chamadas aos resultados. O ciclo completo deve funcionar. O Codex recebe uma chamada, executa a ferramenta, envia o resultado e recebe uma resposta final.

Uma solicitação de texto bem-sucedida não valida esse ciclo. Teste os modelos e os recursos do cliente que você pretende habilitar. O fato de o gateway aceitar um campo de solicitação não comprova que o modelo do provedor implementa o recurso correspondente.

Autenticação e cabeçalhos

O gateway deve oferecer suporte ao mecanismo de autenticação do cliente escolhido para a implantação. As opções são env_key, tokens bearer obtidos por meio de um comando ou env_http_headers para credenciais enviadas em um cabeçalho personalizado. Use variáveis de ambiente para os valores secretos dos cabeçalhos. Não grave esses valores diretamente na configuração. Consulte a referência de provedores personalizados para conhecer a configuração e o contrato do auxiliar de credenciais.

Autentique os desenvolvedores separadamente da identidade que o gateway usa para se autenticar no provedor. Mantenha no gateway as chaves de administrador e as credenciais de acesso ao provedor. Preserve os cabeçalhos usados para rotear as solicitações e atribuí-las aos usuários. Teste a expiração, a renovação e a revogação das credenciais.

Roteamento de modelos e metadados

Para cada nome de modelo exposto ao Codex, o gateway deve encaminhar as solicitações ao modelo pretendido no provedor. Confirme a rota nos registros do gateway, sem depender da descrição que o modelo dá de si mesmo.

Use um nome que a versão implantada do Codex reconheça ou forneça um catálogo correspondente ao alias personalizado. Verifique também a disponibilidade dos modelos e os metadados de migração. O acesso a qualquer modelo substituto deve passar pelo gateway. Para um alias da própria organização sem migração, defina o campo upgrade da entrada correspondente no catálogo como null. Os metadados do catálogo orientam o comportamento do cliente. Eles não acrescentam recursos ao modelo nem criam rotas no gateway. Confirme os limites de contexto, as opções de raciocínio e as ferramentas com o modelo e o provedor que o gateway de fato utiliza. Uma conexão genérica com um gateway não recebe automaticamente os ajustes de metadados que as integrações nativas do Codex com provedores aplicam.

Nomes de modelos reconhecidos

Use o nome exato do modelo que a versão implantada do Codex reconhece, tanto para o alias do gateway quanto para o valor de model no Codex. Confirme que o provedor oferece suporte ao modelo e que sua organização aprova o uso dele.

Confira a versão com codex --version e selecione a tag rust-v<version> correspondente no catálogo de modelos do Codex. Para uma compilação personalizada, use o commit a partir do qual ela foi gerada. Para implantações em desktop, use a versão da CLI incluída no aplicativo. Confira os valores de slug nas entradas do catálogo para identificar os nomes que essa versão reconhece. Se o gateway alterar os recursos do modelo, forneça metadados de catálogo que reflitam essas diferenças, mesmo que o Codex reconheça o nome.

Erros

Permita que o cliente diferencie erros de autenticação do cliente, rotas de modelo desconhecidas, limites de taxa e falhas no provedor. Não reduza todas as falhas a uma resposta 500 genérica. Retorne informações suficientes para identificar a camada em que ocorreu a falha, sem expor tokens, credenciais do provedor ou conteúdo sensível da solicitação.

Limites de acesso a dados e ferramentas

O tráfego destinado ao modelo segue este caminho:

Codex client -> LLM gateway -> model provider

O cliente se autentica no gateway com uma credencial de desenvolvedor. O gateway usa sua própria credencial de acesso ao provedor para acessar o modelo. Prompts, trechos de código-fonte, argumentos e resultados de ferramentas incluídos nas solicitações ao modelo podem passar pelo gateway. Leve isso em conta ao definir os controles de registro em logs, retenção, ocultação de dados sensíveis, acesso e exportação.

O gateway de modelos não roteia todas as conexões feitas pelo Codex. Os comandos locais são executados no ambiente de execução do cliente. Servidores MCP, serviços de plugins, interações com navegadores e aplicativos e outros serviços habilitados podem usar caminhos de rede e credenciais próprios. A configuração do provedor de modelos não concede permissões de acesso a esses recursos nem substitui os controles de rede deles. Consulte Aprovações e segurança de agentes e MCP para entender esses limites.

Lista de verificação para qualificação

Para cada combinação de cliente, gateway e modelo implantada, registre evidências dos seguintes itens:

• Campos de solicitação e resposta da API Responses.
• Entrega incremental dos eventos SSE e conclusão bem-sucedida do fluxo com o evento final.
• Continuidade da conversa nos turnos seguintes com o reenvio dos dados de entrada.
• previous_response_id quando o transporte escolhido o utiliza.
• Chamadas de função, resultados correspondentes e resposta final.
• Roteamento correto do modelo e metadados correspondentes.
• Atribuição das solicitações por usuário, renovação e revogação das credenciais.
• Informações que permitam diagnosticar erros de autenticação, roteamento e limite de taxa, além de falhas no provedor.
• Diagnósticos com dados sensíveis ocultados e aplicação da política de logs prevista.

Use o procedimento de teste da implantação para coletar essas evidências antes de distribuir a configuração.