Requisitos de compatibilidade do gateway

Os gateways do Codex têm de preservar o comportamento da Responses API aqui descrito: endpoints, transmissão em fluxo, continuação, chamadas de ferramentas, autenticação, encaminhamento e erros úteis.

Pedidos e endpoints

Configure um fornecedor de gateway com wire_api = "responses". Para um URL base como https://gateway.example.com/v1, o gateway tem de aceitar POST /v1/responses e preservar os campos de pedido e resposta utilizados pelo cliente. Um endpoint funcional de Chat Completions ou Anthropic Messages não comprova a compatibilidade com Responses.

Os endpoints de estado de funcionamento e de listagem de modelos são auxiliares operacionais opcionais. Não exercitam uma conversa do Codex nem comprovam o suporte de ferramentas.

Transmissão em fluxo

Encaminhe os eventos enviados pelo servidor (SSE) de forma incremental, em vez de acumular toda a resposta em buffer. Preserve os tipos de eventos e os payloads, incluindo o evento terminal response.completed de sucesso. Encaminhe os eventos de erro e de falha para que o cliente possa distinguir uma resposta falhada de uma ligação bloqueada.

Verifique o fluxo completo através dos balanceadores de carga e dos proxies inversos, bem como do gateway. Uma resposta de texto sem um fluxo concluído é insuficiente.

Continuação da conversa

Preserve os dados de entrada da conversa reenviados nas interações subsequentes. O gateway tem de aceitar as mensagens anteriores, as chamadas de ferramentas e os resultados de ferramentas necessários para a interação seguinte.

Se ativar o transporte WebSocket ou incremental, verifique também o respetivo comportamento de previous_response_id. Um percurso HTTP Responses sem estado pode utilizar dados de entrada reenviados sem exigir esse mecanismo de continuação.

Ferramentas

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

Um pedido de texto bem-sucedido não verifica este ciclo. Teste os modelos reais e as funcionalidades do cliente que pretende ativar. O facto de um gateway aceitar um campo de pedido não comprova que o modelo a montante implementa a capacidade correspondente.

Autenticação e cabeçalhos

Suporte o mecanismo de autenticação do cliente selecionado para a implementação: env_key ou tokens bearer obtidos através de comandos, ou env_http_headers para credenciais enviadas num cabeçalho personalizado. Utilize variáveis de ambiente para valores secretos de cabeçalhos; não os escreva diretamente na configuração. Consulte a referência de fornecedores personalizados para conhecer a configuração e o contrato do utilitário de credenciais.

Autentique os programadores separadamente da identidade do fornecedor a montante do gateway. Mantenha as chaves de administrador e as credenciais a montante no gateway. Preserve os cabeçalhos de que dependem o encaminhamento e a atribuição e teste a expiração, a renovação e a revogação de credenciais.

Encaminhamento e metadados de modelos

Cada nome de modelo utilizado pelo Codex tem de ser encaminhado para o modelo pretendido a montante. Verifique a rota nos registos do gateway, em vez de confiar na descrição que o modelo faz de si próprio.

Utilize um nome reconhecido pela versão implementada do Codex ou forneça um catálogo correspondente para um alias personalizado. Reveja também a disponibilidade dos modelos e os metadados de migração: qualquer modelo de substituição tem de ser encaminhado através do gateway. Para um alias pertencente à organização sem migração, defina upgrade da respetiva entrada no catálogo como null. Os metadados do catálogo orientam o comportamento do cliente; não acrescentam capacidades a um modelo nem criam rotas no gateway. Verifique os limites de contexto, as opções de raciocínio e as ferramentas face ao modelo e ao fornecedor efetivos a montante. Uma ligação genérica a um gateway não recebe automaticamente os ajustes de metadados efetuados pelas integrações de fornecedores incluídas no Codex.

Nomes de modelos reconhecidos

Utilize o nome exato do modelo reconhecido pela versão implementada do Codex como alias do gateway e como model do Codex. Confirme que o fornecedor a montante suporta o modelo e que a sua organização o aprova.

Verifique codex --version e selecione a tag rust-v<version> correspondente no catálogo de modelos do Codex. Para uma compilação personalizada, utilize o respetivo commit do código-fonte; para implementações da aplicação de ambiente de trabalho, faça corresponder a versão da CLI incluída. Verifique os valores slug das entradas para encontrar os nomes que essa versão reconhece. Se o gateway alterar as capacidades do modelo, forneça metadados de catálogo que reflitam essas diferenças, mesmo quando o nome é reconhecido.

Erros

Preserve distinções úteis entre erros de autenticação do cliente, rotas de modelos desconhecidas, limites de pedidos e falhas a montante. Não reduza todas as falhas a uma resposta genérica 500. Devolva informação suficiente para diagnosticar a camada com falha sem expor tokens, credenciais do fornecedor ou conteúdo sensível dos pedidos.

Limites de dados e ferramentas

O tráfego dos modelos segue este percurso:

Codex client -> LLM gateway -> model provider

O cliente autentica-se no gateway com uma credencial de programador. O gateway utiliza a sua credencial do fornecedor a montante para aceder ao modelo. Os prompts, os excertos de código-fonte, os argumentos de ferramentas e os resultados de ferramentas incluídos nos pedidos ao modelo podem passar pelo gateway. Defina os controlos de registo, retenção, ocultação de dados sensíveis, acesso e exportação em conformidade.

O gateway de modelos não encaminha todas as ligações efetuadas pelo Codex. Os comandos locais são executados no ambiente de execução do cliente. Os MCP servers, os serviços de plugins, as interações com o navegador e as aplicações, e outros serviços ativados podem ter percursos de rede e credenciais separados. A configuração do fornecedor de modelos não concede essas permissões nem substitui os respetivos controlos de rede. Consulte Aprovações e segurança do agente e MCP para conhecer esses limites.

Lista de verificação de compatibilidade

Registe evidências para cada combinação implementada de cliente, gateway e modelo:

• Campos de pedido e resposta de Responses.
• Entrega incremental de SSE e conclusão terminal bem-sucedida.
• Interações subsequentes com dados de entrada reenviados.
• previous_response_id quando o transporte selecionado o utiliza.
• Chamadas de funções, resultados correspondentes e uma resposta final.
• Encaminhamento correto de modelos e metadados correspondentes.
• Atribuição, renovação e revogação por utilizador.
• Erros úteis de autenticação, encaminhamento, limites de pedidos e falhas a montante.
• Diagnósticos com dados sensíveis ocultados e a política de registo pretendida.

Utilize o procedimento de teste de disponibilização para recolher estas evidências antes de distribuir a configuração.