Implemente um gateway
Distribua e verifique uma ligação do Codex a um gateway para a sua organização
Como administrador do gateway, configure as rotas dos modelos e autorize um utilizador piloto. Teste a ligação em cada cliente que suporta antes de distribuir as configurações aos programadores. Utilize OAuth nativo do gateway, API keys ou auxiliares de credenciais para a autenticação no gateway. Para combinar a autenticação no gateway com o início de sessão num espaço de trabalho do ChatGPT, consulte Iniciar sessão com o ChatGPT através de um gateway.
Pré-requisitos
Antes de disponibilizar o Codex aos programadores, confirme que dispõe de:
- Um gateway que disponibilize HTTPS no URL base exato que irá distribuir.
- Uma credencial do fornecedor a montante mantida no gateway.
- Aliases de modelos aprovados para o Codex, mapeados para os modelos a montante pretendidos.
- Um método de autenticação testado: OAuth nativo do gateway, API keys do gateway com âmbito limitado, ou um auxiliar de credenciais.
- Para OAuth, um cliente público registado, utilizadores de teste aprovados e suporte no gateway para validar tokens de acesso OAuth.
- Para API keys ou auxiliares, um mecanismo de entrega de segredos ou um auxiliar testado.
- Uma forma de distribuir a configuração, quaisquer auxiliares necessários e os ficheiros de catálogo.
Requisitos do gateway
Antes de ligar o Codex, verifique se o produto de gateway preserva estes comportamentos obrigatórios:
- Aceitar pedidos do Codex à Responses API em
POST /v1/responses. - Transmitir eventos SSE sem acumulação em buffer e terminar com
response.completed. - Preservar a continuação em interações subsequentes com dados de entrada reenviados.
- Preservar
previous_response_idapenas quando o transporte WebSocket ou incremental estiver ativado. - Preservar chamadas de funções e os itens
function_call_outputcorrespondentes. - Encaminhar cada alias de modelo utilizado pelo Codex para o modelo pretendido a montante.
- Autenticar os utilizadores separadamente e devolver erros úteis sem ocultar a causa.
Um endpoint de estado de funcionamento, /v1/models, uma resposta de Chat Completions ou uma resposta em texto simples não comprova a compatibilidade do gateway. Consulte Requisitos de compatibilidade do gateway para conhecer o contrato detalhado.
Disponibilizar o gateway
Para passar de um gateway implementado a uma experiência de utilização verificada para os programadores, conclua estes cinco pontos de verificação por ordem:
- Escolha os nomes dos modelos e verifique as rotas.
- Escolha a autenticação.
- Teste o Codex através do gateway.
- Distribua a configuração.
- Verifique a partir da máquina de um programador.
Escolher nomes e rotas de modelos
Defina model do Codex com o nome do modelo no gateway. Configure o gateway para encaminhar esse nome para o modelo aprovado a montante.
| Nome do modelo no gateway | Configuração do Codex |
|---|---|
| Um nome de modelo incorporado incluído na sua versão do Codex | Defina model em config.toml com este nome exato. |
Um alias personalizado, como company-coding-model |
Forneça um catálogo remoto ou local que contenha o alias e os metadados do modelo correspondente. |
Utilizar um catálogo de modelos para nomes personalizados
Para um catálogo local, comece pelo exemplo de models.json.
Forneça um catálogo de modelos quando o gateway utilizar um nome de modelo que o Codex não reconheça. O catálogo fornece as instruções, as opções de raciocínio, os limites de contexto e as capacidades das ferramentas que o Codex utiliza para esse nome. Sem uma entrada correspondente, um pedido pode chegar ao modelo a montante pretendido enquanto o Codex utiliza definições genéricas.
Aloje um catálogo remoto com model_providers.<id>.model_catalog_url para atualizar os metadados dos modelos de forma centralizada ou distribua um ficheiro local com model_catalog_json. Utilize um catálogo local quando o OAuth nativo do gateway for a única credencial; o OAuth, por si só, não permite a descoberta de catálogos remotos. Consulte a referência de configuração para ambas as definições.
Obtenha junto do seu fornecedor de cloud ou de gateway um endpoint ou ficheiro de catálogo compatível com a sua versão do Codex. Certifique-se de que inclui cada alias aprovado e os metadados do respetivo modelo. Para a implementação do catálogo, consulte Implementar catálogos de modelos para gateways e clouds.
Disponibilizar um catálogo remoto
Utilize o endpoint HTTPS do catálogo fornecido pelo seu fornecedor.
Distribua o URL completo do endpoint na tabela config.toml do fornecedor selecionado:
model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"Disponibilize CODEX_GATEWAY_API_KEY ao processo do Codex. Defina base_url
separadamente para encaminhar a inferência através do gateway. Se o omitir, o Codex utiliza o
ponto final predefinido da OpenAI para o modo de autenticação atual.
A descoberta requer autenticação por API key, baseada num comando ou através do backend do Codex. O OAuth nativo do gateway ou os cabeçalhos personalizados, por si só, não a acionam.
Coordene as atualizações do catálogo com o seu fornecedor quando os modelos aprovados mudarem. Reinicie o cliente após alterar a respetiva configuração.
Remova qualquer definição model_catalog_json efetiva, incluindo uma imposta através de
requirements.toml. Esta tem precedência sobre o URL remoto e impede a obtenção dos dados.
Distribuir um catálogo local
Utilize model_catalog_json para carregar o ficheiro fornecido pelo fornecedor no arranque. Um catálogo personalizado
local substitui o catálogo incluído.
Defina o alias do gateway, slug do catálogo e model do Codex como company-coding-model. Adicione estas definições antes da primeira tabela TOML na configuração do Codex que distribuir, utilizando o caminho absoluto real do ficheiro:
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"Reinicie a CLI ou a aplicação de ambiente de trabalho depois de alterar o catálogo, pois o Codex carrega-o no arranque.
Verificar as rotas dos modelos
Para cada modelo, verifique a rota com um pedido Responses real e os registos
do gateway. Uma resposta /v1/models pode ajudar a descobrir nomes, mas não comprova que um
modelo suporta o comportamento exigido para pedidos e ferramentas.
O encaminhamento de modelos e a autorização de ferramentas são partes distintas da disponibilização. Configure as ligações MCP, a distribuição de plugins e as respetivas políticas separadamente.
Escolher a autenticação
OAuth nativo do gateway
- Registe um cliente OAuth público que suporte o código de autorização com PKCE e aprove os utilizadores ou grupos que podem iniciar sessão.
- Configure o gateway para validar o token de acesso emitido no cookie ou cabeçalho personalizado selecionado. Aplique os modelos aprovados, os limites de pedidos e os orçamentos à identidade de cada utilizador.
- Siga as instruções de OAuth nativo do gateway para recolher os URLs de autorização e de token, o ID do cliente público, os âmbitos, o recurso opcional, as definições de entrega de tokens e qualquer porta fixa de redirecionamento. Registe o URI de redirecionamento de loopback correspondente junto do seu fornecedor de identidade.
- Teste o início de sessão no navegador, a renovação de tokens e a revogação de acesso com um utilizador de teste na CLI ou na aplicação de ambiente de trabalho que pretende implementar. Confirme que o navegador consegue aceder ao callback, incluindo no caso de utilizadores remotos da CLI.
Os utilizadores iniciam sessão individualmente. Distribui-se a configuração OAuth, não um segredo do cliente, uma API key do gateway ou um executável auxiliar. Mantenha as credenciais do fornecedor a montante no gateway.
API keys ou auxiliares de credenciais
- Emita uma credencial de gateway com âmbito limitado por programador, para poder atribuir a utilização e revogar o acesso individualmente.
- Defina os modelos aprovados, os limites de pedidos, o orçamento, a expiração e o período de renovação de cada credencial.
- Entregue as credenciais através do seu gestor de segredos ou de um utilitário de credenciais instalado. Mantenha as credenciais do fornecedor a montante e do administrador do gateway fora das máquinas dos programadores.
- Se utilizar um utilitário, siga o contrato de autenticação baseada em comandos e teste a obtenção e a atualização de tokens antes da distribuição.
- Informe os programadores sobre como renovar as credenciais e quem contactar para obter ajuda.
Testar o Codex através do gateway
Antes de distribuir qualquer elemento, siga Configurar o fornecedor para configurar um utilizador de teste isolado com o bloco do fornecedor e o método de autenticação que pretende distribuir.
Se o gateway disponibilizar o catálogo de modelos, confirme que devolve um array models compatível com o Codex. Para inferência OpenAI com a credencial do utilizador, confirme que o gateway reencaminha os cabeçalhos ChatGPT necessários para o backend do Codex.
Registe a versão do cliente, o sistema operativo, o ID do fornecedor, o alias do modelo e o método de autenticação do seu teste piloto. Execute as verificações abaixo em cada interface CLI ou de aplicação de ambiente de trabalho que pretende suportar. Se disponibilizar tanto autenticação apenas no gateway como autenticação no gateway em conjunto com o início de sessão no ChatGPT, teste cada combinação separadamente.
| Verificação | Ação | Evidência de êxito |
|---|---|---|
| Configuração efetiva | Inspecione as camadas de configuração e confirme o fornecedor, o modelo e os requisitos pretendidos. | O piloto utiliza as definições distribuídas. As predefinições do utilizador ou do perfil não selecionam uma rota diferente. |
| Ligação | Siga Verificar a ligação. | O fornecedor e o alias esperados estão ativos, o pedido de teste é bem-sucedido e os registos do gateway identificam o utilizador de teste. |
| Streaming | Peça uma resposta curta com vários parágrafos. | O texto chega de forma incremental e o transporte ativo emite response.completed. Teste HTTP separadamente para verificar se o gateway reencaminha os eventos SSE sem os acumular numa memória intermédia. |
| Ciclo de ferramentas locais | Numa pasta descartável com permissões só de leitura, peça ao Codex para listar os ficheiros de nível superior e resumi-los. | O Codex efetua uma chamada de ferramenta local, devolve o resultado e produz uma resposta final sem alterações. |
| Seguimento | Faça uma pergunta de seguimento na mesma conversa. | A resposta utiliza a interação anterior; o gateway aceita a entrada reenviada. Se o transporte WebSocket ou incremental estiver ativado, também preserva previous_response_id. |
| Erros e atribuição | Repita com um alias de teste intencionalmente inválido ou uma credencial de teste expirada. | O cliente recebe um erro de encaminhamento ou autenticação útil e os pedidos válidos continuam a ser atribuídos ao utilizador de teste. |
Se a aprovação automática estiver ativada, utilize uma pasta de teste descartável para desencadear uma ação de ferramenta que exija revisão ao abrigo da política pretendida. Confirme que o gateway processa o pedido de revisão e que o cliente aplica a decisão de aprovação. Uma chamada de ferramenta só de leitura que não precise de aprovação não testa este percurso. Registe qualquer fluxo de trabalho não suportado antes de alargar o piloto.
Se a implementação alterar o fornecedor dos utilizadores existentes, teste uma conversa nova e uma conversa criada antes da alteração em cada cliente suportado. Registe se os utilizadores conseguem ver, continuar ou criar uma ramificação da conversa existente e forneça-lhes um procedimento de recuperação para qualquer fluxo de trabalho bloqueado. Não pressuponha que alterar o fornecedor predefinido migra o histórico de conversas.
Depois de estas verificações serem bem-sucedidas, prepare a passagem de informações aos programadores.
Distribuir a configuração
Para que todas as máquinas utilizem o mesmo caminho de ligação, distribua o URL base do gateway, o ID do fornecedor, o alias do modelo aprovado e as definições de autenticação.
O que distribuir
Para OAuth nativo do gateway, distribua as tabelas do fornecedor e
[model_providers.<id>.gateway_oauth] do guia de
ligação, com os
valores de registo recolhidos acima. Mantenha requires_openai_auth = false e omita
env_key, experimental_bearer_token e a tabela auth baseada num comando quando
OAuth for a única credencial do gateway.
Para um auxiliar de credenciais, distribua o seguinte bloco config.toml através da
camada de configuração que escolheu. Utilize um modelo reconhecido pela sua versão do Codex ou
forneça o catálogo correspondente descrito acima. Instale o componente de obtenção de tokens no
caminho do comando configurado:
model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000Para uma chave de teste estática de curta duração, remova o bloco de autenticação, coloque env_key = "CODEX_GATEWAY_API_KEY" dentro de [model_providers.enterprise-gateway] e defina essa variável fora do TOML. Não combine env_key com autenticação baseada em comandos.
Distribuir predefinições e requisitos
Se os seus utilizadores não iniciarem sessão no Codex com o ChatGPT, pode distribuir definições da equipa a partir do seu próprio servidor. O Codex obtém essas definições independentemente da forma como encaminha os pedidos aos modelos.
Utilize Precedência da configuração para escolher onde distribuir as predefinições. Para definições impostas e payloads MDM para macOS, consulte Configuração gerida.
Para predefinições aplicáveis a todo o sistema anfitrião no macOS ou Linux, utilize /etc/codex/config.toml. No
Windows, coloque config.toml em %ProgramData%\OpenAI\Codex\. Os utilizadores e os
perfis podem substituir estas predefinições. As referências indicadas descrevem os requisitos
suportados e as localizações dos respetivos ficheiros.
Distribua separadamente quaisquer executáveis auxiliares e ficheiros de catálogo locais referenciados.
Para impor um URL de catálogo remoto, coloque a definição completa do fornecedor em
requirements.toml, em [model_providers.<id>]. Uma definição de fornecedor
imposta substitui a tabela do fornecedor correspondente da configuração normal;
inclua o respetivo base_url, as definições de autenticação e outros campos obrigatórios.
Utilize o requisito model_provider quando também precisar de impor a seleção do
fornecedor.
model_catalog_json aponta para um ficheiro JSON local. Se o impuser através de
requirements.toml, o requisito fixa o caminho; não distribui o
ficheiro. Coloque o catálogo nesse caminho absoluto antes de o Codex arrancar.
Escreva caminhos absolutos do Windows já resolvidos no TOML. O Codex não expande
%ProgramData% dentro de model_catalog_json nem dos valores command de autenticação do fornecedor. Por
exemplo, utilize estes caminhos apenas se a sua implementação tiver colocado os ficheiros nesses locais:
model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'
[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]Uma CLI dentro do WSL lê caminhos Linux e CODEX_HOME do Linux; não herda automaticamente
a configuração nativa do Windows.
Distribuir cabeçalhos de encaminhamento
Se o seu gateway encaminhar pedidos por configuração ou ferramenta, adicione os cabeçalhos que espera ao fornecedor no seu requirements.toml gerido. O exemplo seguinte fornece um ID de configuração de encaminhamento e identifica o Codex como cliente:
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'Utilize env_http_headers para valores de cabeçalho fornecidos pelo ambiente do cliente. Envie um pedido de teste e confirme a rota selecionada nos registos do gateway. Consulte Fornecedores de modelos personalizados para conhecer as opções de cabeçalho.
Entregar os valores de configuração aos programadores
Forneça aos programadores um único procedimento de configuração que corresponda ao piloto que testou. Inclua as seguintes informações, mesmo quando distribui a configuração de forma centralizada:
| Informação a transmitir | O que fornecer |
|---|---|
| Cliente aprovado | O cliente, a versão, o sistema operativo e as instruções de instalação ou atualização utilizados no piloto. |
| Distribuição da configuração | Se as definições já são geridas ou exigem configuração local; identifique qualquer utilitário auxiliar ou ficheiro de catálogo instalado separadamente. |
| Ligação esperada | O ID do fornecedor, o alias do modelo e o URL do gateway, incluindo o respetivo caminho da API. Explique quais os valores que os utilizadores podem alterar. |
| Passos de início de sessão | Se os utilizadores têm de iniciar sessão num espaço de trabalho do ChatGPT, autenticar-se no gateway ou fazer ambas as coisas. Indique o espaço de trabalho necessário e o método de autenticação do gateway. |
| Credenciais e catálogos | Os valores de registo OAuth, a variável de ambiente da credencial ou a configuração do utilitário auxiliar instalado, bem como qualquer URL de catálogo ou caminho local resolvido. Entregue os segredos através do seu mecanismo aprovado de distribuição de segredos. |
| Verificação e suporte | O teste de ligação, o resultado esperado, o responsável pelo gateway e as informações a incluir ao comunicar uma falha. |
Para máquinas geridas, encaminhe os programadores para Verificar se existe uma configuração. Para a configuração manual, encaminhe-os para Configurar o fornecedor.
Inclua as instruções que testou para conversas existentes se esta implementação alterar o fornecedor. Mantenha a configuração anterior que funcionava disponível para o responsável pela implementação, caso o piloto revele um problema.
A configuração manual não é um canal de imposição de definições. O .codex/config.toml local do projeto não pode substituir chaves sensíveis de encaminhamento do fornecedor ou de autenticação.
Verificar a partir da máquina de um programador
Para confirmar que as definições distribuídas chegaram à máquina de um programador:
- Confirme que o cliente aprovado e quaisquer utilitários auxiliares ou ficheiros de catálogo necessários estão instalados. Reinicie o Codex e conclua os inícios de sessão indicados nas informações transmitidas.
- Confirme o fornecedor e o modelo esperados. Na CLI, utilize
/status. Utilize/debug-configpara inspecionar as camadas de configuração quando as definições efetivas diferirem das informações transmitidas. - Execute o teste breve em Ligar a um gateway.
- Faça uma pergunta de seguimento para confirmar a continuação e, em seguida, procure nos registos do gateway o pedido desse programador.
Alargue o acesso depois de o piloto ser bem-sucedido nos clientes e nas combinações de autenticação que suporta. Guarde a configuração testada e os resultados juntamente com as instruções de implementação, para poder repetir as verificações após atualizações do cliente, do gateway ou da política.
Resolver falhas na disponibilização
Utilize o problema para identificar a camada de configuração, credenciais ou gateway que requer atenção:
| Problema | Resolução |
|---|---|
| O fornecedor esperado não aparece após o reinício. | Inspecione a camada de configuração que tem precedência. A configuração do utilizador ou do perfil pode substituir as predefinições do sistema. |
| A autenticação falha para todos os utilizadores. | Verifique a autenticação do gateway e a credencial do fornecedor a montante; identifique o serviço que rejeitou o pedido. |
| A autenticação falha para um utilizador. | Verifique o acesso desse utilizador ao fornecedor de identidade, a credencial do gateway ou o componente de obtenção de tokens. |
| O streaming bloqueia. | Inspecione o armazenamento em buffer do gateway e o reencaminhamento do evento final response.completed. |
| Um modelo não aparece ou utiliza capacidades genéricas. | Para um alias personalizado, confirme que o alias do gateway, model do Codex e slug do catálogo correspondem. Verifique o caminho do catálogo e a compatibilidade com a versão instalada do Codex e, em seguida, reinicie o Codex. |
| Um caminho do Windows falha. | Utilize caminhos absolutos resolvidos. Em TOML, utilize cadeias entre plicas para caminhos do Windows com barras invertidas simples. |
Reutilizar uma implementação de gateway existente
Se a sua organização já utiliza o Claude Code através de um gateway, poderá ser possível
reutilizar o produto de gateway, o percurso de rede, o registo de eventos e o acesso ao Bedrock. Adicione uma
rota Responses para o Codex, uma credencial, aliases de modelos e config.toml, mantendo
a configuração existente em funcionamento. As definições do cliente Claude e o
contrato /v1/messages não configuram o Codex.
| Implementação existente do Claude | Migração para o Codex |
|---|---|
| Produto de gateway, DNS, TLS, rede privada, registo, ocultação de dados sensíveis e monitorização | Mantenha estes serviços. Adicione uma rota para o Codex que cumpra os requisitos de compatibilidade do gateway. |
| Conta Bedrock, credencial do fornecedor, limite IAM, perfis de inferência e rotação de credenciais | Mantenha-os apenas se autorizarem os modelos a montante associados aos novos aliases do Codex. A credencial do fornecedor permanece no gateway. |
Rota /v1/messages do Claude, formato InvokeModel do Bedrock, cabeçalhos Anthropic e novas tentativas ou erros específicos do Claude |
Não os reutilize como prova de compatibilidade. O Codex necessita de POST /v1/responses, streaming de Responses, continuação, chamadas de ferramentas e erros úteis. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY ou apiKeyHelper |
O Codex não suporta apiKeyHelper. Configure OAuth nativo do gateway, uma chave com âmbito limitado através de env_key ou um componente de obtenção de tokens do Codex baseado num comando. |
Nomes de modelos do Claude, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides e mapeamentos de perfis Bedrock |
Peça à equipa responsável pelo gateway para escolher os nomes dos modelos e configurar quaisquer aliases personalizados. Utilize o nome do modelo e qualquer JSON de catálogo de modelos que a equipa fornecer. |
settings.json e managed-settings.json do Claude, blocos JSON env, plist ou payloads do registo |
Mantenha o mesmo canal MDM ou de gestão de configuração, mas distribua antes config.toml do Codex e os valores requirements.toml suportados. |
Para migrar em segurança, conclua estes passos por ordem:
- Faça um inventário do percurso atual do Claude: URL do gateway, origem das credenciais, cabeçalhos necessários, aliases de modelos, mapeamentos de perfis do Bedrock e canal de distribuição gerido.
- Adicione uma rota Responses paralela destinada ao Codex e aliases de modelos do Codex.
- Escolha OAuth nativo do gateway, uma API key ou um utilitário auxiliar de credenciais e autorize um utilizador de teste. Para uma credencial estática, disponibilize-a através de
env_key; para um utilitário auxiliar, implemente e teste o contrato do resolvedor do Codex baseado em comandos. - Configure o fornecedor para esse programador utilizando o método de autenticação que selecionou no passo 3. Para uma implementação gerida, adapte o payload aos caminhos e à precedência do Codex descritos em Implementar um gateway.
- Execute a verificação breve da ligação na CLI ou na interface de ambiente de trabalho efetivamente utilizada pelo programador e, em seguida, execute todas as verificações de streaming, continuação, chamadas de ferramentas, erros, registos e encaminhamento por alias em Testar o Codex através do gateway.
- Depois de o piloto ser bem-sucedido, distribua a configuração aos restantes programadores.
Referência do catálogo de modelos
Começar com um ficheiro models.json local
Primeiro, configure e selecione o seu fornecedor de gateway na máquina onde executa o Codex.
Guarde este catálogo como models.json na máquina que executa o Codex. Substitua
gateway-model pelo ID exato do modelo que o seu gateway aceita. O nome a apresentar
é a designação que os utilizadores veem no seletor de modelos.
{
"models": [
{
"slug": "gateway-model",
"display_name": "Gateway model",
"base_instructions": "Help the user with their coding tasks.",
"supported_reasoning_levels": [],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": true,
"priority": 0,
"support_verbosity": false,
"truncation_policy": { "mode": "tokens", "limit": 10000 },
"experimental_supported_tools": []
}
]
}Para um exemplo mais extenso, consulte o catálogo de modelos do Codex.
Defina model_catalog_json em config.toml como o caminho absoluto do ficheiro.
Reinicie o Codex, selecione Gateway model e envie um pedido. Verifique se o
gateway recebeu o ID do modelo que definiu em slug.
Para um alias de um modelo incluído, copie a respetiva entrada completa do catálogo para a sua versão do Codex
e altere slug e display_name. Se o alias não tiver um destino de migração, defina upgrade como null. Isto preserva a
janela de contexto, as opções de raciocínio e as definições de ferramentas do modelo.
Disponibilizar um catálogo aos clientes
Esta página destina-se a programadores que implementam o formato Codex Models, que define o catálogo de modelos e suporta o seletor de modelos. Se desenvolver um fornecedor de inferência, como um gateway ou um serviço na nuvem, utilize esta especificação para permitir que a aplicação de ambiente de trabalho do Codex e a CLI descubram os seus modelos e utilizem as respetivas instruções e definições de capacidades.
Se administra uma empresa e pretende controlar o catálogo de modelos, consulte as
orientações de configuração de model_catalog_url.
Para suportar o formato, implemente um endpoint de catálogo autenticado. Obtenha os valores predefinidos atuais do fornecedor a montante para a versão do Codex que faz o pedido, aplique as suas substituições e devolva o catálogo resultante.
client_version Implementar o endpoint de catálogo
O endpoint de catálogo predefinido é /models no base_url do fornecedor.
Por exemplo, com base_url = "https://gateway.example.com/v1", o Codex faz o seguinte pedido:
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>A descoberta predefinida suporta autenticação baseada em comandos e autenticação pelo backend do Codex,
como a do ChatGPT. Para um fornecedor personalizado que utilize autenticação por API key
sem autenticação baseada em comandos, defina model_providers.<id>.model_catalog_url
explicitamente para ativar a descoberta remota. Uma API key, por si só, não desencadeia a descoberta
no caminho predefinido.
Utilize model_catalog_url para escolher um URL completo do catálogo, como
https://gateway.example.com/codex/models. Também pode apontar para o endpoint predefinido
/v1/models. O Codex utiliza este URL diretamente, sem acrescentar /models.
Para a descoberta por API key, mantenha features.api_key_model_discovery ativado; está ativado
por predefinição. Os cabeçalhos personalizados, por si só, não ativam a descoberta.
O Codex envia os dados de autenticação e os cabeçalhos configurados do fornecedor selecionado e
acrescenta client_version e quaisquer query_params do fornecedor. Aloje o catálogo num
serviço autorizado a receber essas credenciais.
Autentique o autor do pedido, obtenha os valores predefinidos correspondentes a montante, aplique as suas
substituições e devolva diretamente o JSON ModelsResponse completo. Atribua a cada
entrada um slug único e não vazio. Para um model_catalog_url explícito, o Codex rejeita
redirecionamentos e respostas superiores a 1 MiB. Continue a aplicar o controlo de acesso aos modelos nos
pedidos de inferência.
Remova qualquer definição model_catalog_json em vigor dos clientes que utilizam o endpoint:
o ficheiro local tem precedência e impede a obtenção remota.
Corresponder ao esquema do cliente
Leia o parâmetro de consulta client_version no pedido de catálogo. O Codex envia a sua
versão da CLI no formato major.minor.patch, sem qualquer sufixo de pré-lançamento. Nos clientes de ambiente de trabalho,
esta é a versão da CLI incluída.
Utilize a tag rust-v<version> correspondente no repositório público do Codex ou o
commit exato do código-fonte para uma compilação personalizada. Estas ligações utilizam rust-v0.162.1; selecione
a revisão correspondente ao seu cliente:
- Leia os tipos de resposta
ModelsResponseeModelInfopara consultar o esquema. - Consulte o
models.jsonincluído para ver um exemplo completo. Trata-se de dados de catálogo, não de um documento JSON Schema.
O ficheiro incluído é um retrato de uma versão lançada. Obtenha os valores predefinidos atuais antes de produzir o seu catálogo.
Obter os valores predefinidos atuais a montante
Os fornecedores de serviços na nuvem que disponibilizam modelos da OpenAI obtêm os valores predefinidos da OpenAI. Os gateways leem o catálogo do seu fornecedor de serviços na nuvem ou a montante para preservar as definições do modelo implementado e a disponibilidade por conta e região. Transmita a versão do Codex que faz o pedido em cada etapa e autentique-se separadamente em cada endpoint.
Para obter os valores predefinidos diretamente da OpenAI, faça uma chamada ao endpoint de modelos do Codex com o
mesmo client_version. Por exemplo, com uma API key da OpenAI:
curl --fail --silent --show-error \
'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
-H "Authorization: Bearer $OPENAI_API_KEY"Para uma integração com o ChatGPT, utilize o token de acesso do ChatGPT do autor do pedido e o
cabeçalho ChatGPT-Account-ID quando aplicável. Utilize credenciais autorizadas para o
endpoint a montante; a API key do próprio gateway não permite a autenticação na OpenAI.
Analise a resposta completa, incluindo o array models de nível superior. Este endpoint
devolve metadados do Codex, como instruções, valores predefinidos de raciocínio, definições de ferramentas,
limites de contexto e níveis de serviço. O endpoint público /v1/models não
fornece este catálogo.
Atualize estes valores predefinidos mesmo quando a versão do Codex não tiver mudado. Mantenha os pedidos limitados à identidade pretendida a montante e respeite os controlos de cache da resposta: os catálogos podem depender do acesso do autor do pedido. Mantenha as suas substituições separadas para que possa voltar a aplicá-las aos valores predefinidos atualizados.
Aplicar substituições do fornecedor
Altere os valores dos campos, preservando a estrutura de resposta da versão:
- Filtre os modelos para incluir apenas os que o autor do pedido pode utilizar. Associe cada
sluga uma rota de inferência suportada e ajustedisplay_name,descriptionoupriority. Para um alias sem migração de modelo, definaupgradecomonull. - Defina as opções de raciocínio, os limites de contexto, as modalidades de entrada e os níveis de serviço com
valores suportados pelo seu modelo e pela sua rota. Mantenha os valores predefinidos dentro das opções
suportadas. Para uma rota sem níveis de serviço, limpe
service_tierseadditional_speed_tierse definadefault_service_tiercomonull. - Preserve as instruções e as definições de ferramentas a montante, a menos que tenha testado uma alternativa. Os metadados não acrescentam capacidades ao modelo nem concedem acesso à inferência.
Para um alias de modelo do gateway, veja como fornecer metadados do modelo. Teste o catálogo resultante com cada versão suportada do Codex.
Utilizar os tipos públicos de Rust
Utilize crates da mesma tag ou do mesmo commit público do Git que o esquema do cliente:
- Utilize
codex-protocolparacodex_protocol::openai_models::{ModelsResponse, ModelInfo}. Analise comserde_json::from_slice::<ModelsResponse>(), editecatalog.modelse serialize todo o objeto envolvente comserde_json::to_vec(). O objeto envolvente trata dos campos de compatibilidade das instruções dos modelos. - Utilize
codex-models-manager::bundled_models_response()para carregar o catálogo estático incluído nessa revisão como umModelsResponse. Esta função não obtém os valores predefinidos atuais a montante.