Implementar o Codex através de um gateway

Implemente o Codex através do gateway de LLM da sua organização. Configure rotas de modelos, emita credenciais para programadores e distribua uma configuração do Codex verificada.

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 utilização pelo Codex, mapeados para os modelos pretendidos a montante.
• Uma credencial de teste do gateway com âmbito limitado.
• Um mecanismo de entrega de segredos ou um utilitário de credenciais testado.
• Uma forma de distribuir a configuração, os executáveis auxiliares e quaisquer 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_id apenas quando o transporte WebSocket ou incremental estiver ativado.
• Preservar chamadas de funções e os itens function_call_output correspondentes.
• 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:

1. Escolher nomes de modelos e verificar rotas.
2. Emitir credenciais para programadores.
3. Testar o Codex através do gateway.
4. Distribuir a configuração.
5. Verificar 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.

Utilizar um catálogo de modelos para nomes personalizados

Utilize model_catalog_json quando o seu gateway utilizar um nome de modelo que o Codex não reconhece. 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 pretendido a montante enquanto o Codex utiliza definições genéricas.

Por exemplo, para utilizar company-coding-model como alias de gpt-6-luna:

1. Crie o alias company-coding-model no gateway e encaminhe-o para o modelo aprovado a montante gpt-6-luna.
2. Transfira o catálogo de modelos do Codex para a sua versão do Codex e guarde uma cópia como gateway-models.json. Utilize este ficheiro como ponto de partida.
3. Edite a entrada gpt-6-luna na sua cópia: defina slug como company-coding-model e verifique se os restantes metadados correspondem ao modelo a montante e às capacidades do gateway. Para um alias sem migração de modelo, defina upgrade como null.
4. Mantenha as entradas no array models de nível superior e distribua o ficheiro a cada cliente. Um catálogo personalizado substitui o catálogo incluído, pelo que deve incluir todos os modelos que os utilizadores precisam de selecionar.

Para o Bedrock através do LiteLLM, aplique as alterações obrigatórias ao catálogo.

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.

Emitir credenciais para programadores

1. Emita uma credencial de gateway com âmbito limitado por programador, para poder atribuir a utilização e revogar o acesso individualmente.
2. Defina os modelos aprovados, os limites de pedidos, o orçamento, a expiração e o período de renovação de cada credencial.
3. 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.
4. 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.
5. 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 Ligar a um gateway para configurar um utilizador de teste isolado com o bloco de fornecedor e o mecanismo de credenciais que pretende distribuir.

Execute as verificações abaixo na mesma interface da CLI ou da aplicação de ambiente de trabalho que os programadores irão utilizar:

Depois de estas verificações serem concluídas com êxito, encaminhe os programadores para Ligar a um gateway para configurarem e verificarem as suas próprias máquinas.

Distribuir a configuração

Para que todas as máquinas utilizem o mesmo percurso de ligação, distribua o URL base do gateway, o ID do fornecedor, o alias de modelo aprovado e o mecanismo de credenciais.

O que distribuir

Para definir as predefinições do fornecedor, distribua este 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 seu utilitário de resoluçã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 = 300000

Para 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

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 referenciados.

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.

Entregar os valores de configuração aos programadores

Se não dispuser de distribuição gerida, forneça a cada programador o URL do gateway, o ID do fornecedor, o alias do modelo, a variável de credencial ou o utilitário de resolução e qualquer caminho de catálogo. Encaminhe-os para Ligar a um gateway para configurarem e verificarem as suas próprias máquinas.

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:

1. Reinicie o Codex e confirme o fornecedor e o modelo esperados.
2. Execute o teste breve em Ligar a um gateway.
3. Faça uma pergunta de seguimento para confirmar a continuação e, em seguida, procure nos registos do gateway o pedido desse programador.

Resolver falhas na disponibilização

Utilize o problema para identificar a camada de configuração, credenciais ou gateway que requer atenção:

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.

Para migrar em segurança, conclua estes passos por ordem:

1. Faça o inventário do percurso atual do Claude: URL do gateway, origem das credenciais, cabeçalhos obrigatórios, aliases de modelos, mapeamentos de perfis Bedrock e canal de entrega gerida.
2. Adicione uma rota Responses paralela para o Codex e aliases de modelos do Codex.
3. Emita uma credencial do Codex com âmbito limitado. Se o Codex utilizar uma credencial estática, disponibilize essa nova credencial através de env_key; se o Claude utilizar um utilitário de credenciais, implemente e teste o contrato do utilitário de resolução do Codex baseado em comandos.
4. Configure esse programador com o bloco de fornecedor. Para uma disponibilização gerida, adapte o payload aos caminhos e à precedência do Codex descritos em Implementar o Codex através de um gateway.
5. Execute a verificação breve da ligação na interface da CLI ou da aplicação de ambiente de trabalho efetivamente utilizada pelo programador e, em seguida, execute todas as verificações de transmissão em fluxo, continuação, chamadas de ferramentas, erros, registo de eventos e encaminhamento de aliases em Testar o Codex através do gateway.
6. Depois de o projeto-piloto ser concluído com êxito, distribua a configuração aos restantes programadores.

Documentação relacionada

• Ligar a um gateway
• MCP
• Plugins
• Configuração gerida