Ligar a um gateway
Configure um gateway de modelos e autentique-se com OAuth nativo do gateway, uma API key ou um auxiliar de credenciais.
Ligue o Codex ao gateway de modelos da sua organização utilizando as definições do fornecedor e o método de autenticação disponibilizados pela equipa responsável pelo gateway. O gateway encaminha os pedidos de modelos para o seu backend, como o Amazon Bedrock.
Verifique se já existe uma configuração
Instale o cliente Codex e a versão que o seu administrador testou. Se a sua organização gerir as definições, abra esse cliente e conclua os passos de início de sessão indicados nas instruções que recebeu. Pode ignorar os exemplos de configuração do fornecedor abaixo.
- Para a CLI, inspecione o perfil selecionado e execute
codex doctor. Após o arranque, utilize/statuspara confirmar o modelo e o fornecedor ativos. - Para a aplicação macOS, inspecione
~/.codex/config.tomlou a configuração gerida distribuída pela sua organização. - Para a aplicação Windows, inspecione
%USERPROFILE%\.codex\config.tomlou a configuração do sistema distribuída pela sua organização.
Se o fornecedor do gateway e o modelo esperados já estiverem ativos, conclua os passos de início de sessão fornecidos pelo seu administrador e, em seguida, avance para Verificar a ligação. Evite adicionar uma segunda configuração de fornecedor a um computador gerido. Se as definições diferirem das instruções do seu administrador, pergunte que camada de configuração as deve fornecer antes de editar ficheiros locais.
Obtenha os detalhes de ligação ao gateway
Para a configuração manual, confirme se precisa de iniciar sessão no espaço de trabalho ChatGPT, de autenticação no gateway ou de ambos.
Para configurar o Codex por si, obtenha estes valores junto da sua equipa de gateway:
- O URL base HTTPS do gateway, incluindo o caminho da API, como
https://gateway.example.com/v1. - O nome do modelo e o ID do fornecedor a utilizar.
- O método de autenticação: OAuth nativo do gateway, uma API key com âmbito limitado e a respetiva variável de ambiente, ou um auxiliar de credenciais instalado.
- Para OAuth, o URL de autorização, o URL do token, o ID de cliente público e quaisquer âmbitos necessários. Para gateways que utilizem um cookie ou um cabeçalho personalizado, o respetivo nome.
- Qualquer URL de catálogo de modelos necessário, ou um ficheiro de catálogo e o respetivo caminho local absoluto.
Configure o fornecedor
Abra config.toml em ~/.codex/config.toml no macOS ou Linux, ou
%USERPROFILE%\.codex\config.toml no Windows.
Integre este exemplo na sua configuração existente, substituindo o URL e o modelo
pelos valores fornecidos pelo seu administrador. Não adicione uma segunda definição de uma
chave ou tabela existente. Este exemplo utiliza gpt-6-sol; utilize-o sem um catálogo
personalizado apenas se o seu administrador confirmar que a sua versão do Codex reconhece
o modelo e que os metadados incluídos correspondem ao gateway.
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"
requires_openai_auth = falseEm seguida, adicione as definições de autenticação que a equipa responsável pelo gateway disponibiliza.
enterprise-gateway é um ID de fornecedor exemplificativo. Utilize o mesmo ID em
model_provider e nas respetivas tabelas de fornecedor e autenticação.
Este exemplo desativa a pesquisa na Web
para o teste inicial de ligação; o seu administrador deve verificar o suporte da funcionalidade
antes de a ativar.
Configure o seu catálogo de modelos
Confirme com a sua equipa de gateway como o Codex obtém as capacidades e as instruções do modelo selecionado:
- Nome incluído: Se o gateway aceitar o nome exato do modelo incluído na sua versão do Codex e o encaminhar para o modelo correspondente, defina
modelcom esse nome. O Codex já tem os respetivos metadados. - Endpoint de catálogo: Se o gateway fornecer metadados compatíveis com o Codex, utilize o URL completo do catálogo. Pode ser um endpoint
/v1/modelsque implemente a resposta de catálogo do Codex. Uma resposta que apenas liste IDs de modelos é insuficiente para aliases personalizados. - Ficheiro de catálogo: Se o seu gateway utilizar aliases personalizados e o seu administrador distribuir um ficheiro, utilize o exemplo de models.json local. Utilize um ficheiro local quando o OAuth nativo do gateway for a sua única credencial e precisar de metadados personalizados.
Para autenticação com API key ou auxiliar, se o administrador disponibilizar um URL de
catálogo, adicione-o à tabela existente
[model_providers.enterprise-gateway]:
model_catalog_url = "https://gateway.example.com/codex/models.json"Remova qualquer definição model_catalog_json efetiva; esta tem precedência sobre o
URL. Os administradores podem consultar os requisitos do ponto final em
configuração do catálogo remoto.
Se o administrador fornecer um ficheiro local de catálogo de modelos, guarde-o e adicione
model_catalog_json antes da primeira tabela TOML, utilizando o caminho absoluto do ficheiro.
Os aliases personalizados necessitam de metadados de catálogo correspondentes. Por exemplo:
model_catalog_json = "/etc/codex/gateway-models.json"Utilize o nome do modelo e o catálogo fornecidos em conjunto pelo seu administrador. Não adicione um caminho de catálogo a menos que o ficheiro exista nessa localização.
Escolher um método de autenticação
Utilize OAuth nativo do gateway para iniciar sessão no navegador, uma API key para uma credencial com âmbito limitado ou um auxiliar de credenciais se a sua organização disponibilizar um comando.
{/* prettier-ignore */}
Utilizar OAuth nativo do gateway
O OAuth do gateway funciona independentemente do início de sessão no ChatGPT. Utilize-o quando o gateway aceitar tokens de acesso emitidos pelo fornecedor de identidade da sua organização, como o Microsoft Entra ID. O Codex gere o início de sessão no navegador, o armazenamento encriptado de credenciais e a renovação de tokens quando o servidor de autorização emite um token de renovação.
Para autenticação apenas no gateway, o Codex CLI 0.166.0 e versões posteriores envia o token de acesso em Authorization: Bearer <gateway access token> por predefinição. Remova qualquer entrada Authorization de http_headers ou env_http_headers deste fornecedor.
A equipa responsável pelo gateway tem de registar um cliente OAuth público que suporte o
fluxo de código de autorização com PKCE. Adicione esta tabela à configuração do fornecedor
em config.toml, substituindo os URLs e o ID do cliente pelos respetivos valores:
[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127Adicione scopes e, se necessário, resource a esta tabela utilizando os valores que o seu
fornecedor de identidade e o gateway exigem. Solicite os âmbitos necessários para os tokens de
renovação se o seu fornecedor os exigir. Por predefinição, o Codex utiliza uma porta de loopback disponível.
Se o seu fornecedor de identidade exigir um URI de redirecionamento fixo, defina redirect_port e
registe http://127.0.0.1:43127/callback para este exemplo.
Se o gateway esperar um cookie ou um cabeçalho personalizado, defina o campo opcional delivery na tabela OAuth. Escolha o método que o gateway valida:
delivery = { kind = "cookie", name = "auth-openid" }delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }Se a sua implementação também exigir o início de sessão no ChatGPT, utilize o cookie ou um cabeçalho separado do gateway apresentado acima. Consulte Ativar o início de sessão no ChatGPT.
Um gateway que aceite apenas uma API key estática tem de adicionar suporte para o token OAuth e o respetivo método de entrega antes de poder utilizar este fluxo. O gateway continua a gerir as suas próprias credenciais de acesso aos serviços a montante, como as credenciais AWS para o Bedrock.
Quando o OAuth for a sua única credencial, mantenha requires_openai_auth = false e remova as
configurações anteriores env_key, experimental_bearer_token ou auth utilizadas para a
credencial do gateway. Utilize um catálogo local de modelos se precisar de metadados de modelos
personalizados; o OAuth, por si só, não permite a descoberta de catálogos remotos.
Reinicie a aplicação de ambiente de trabalho e siga a indicação de início de sessão no gateway para abrir o navegador.
Na CLI, inicie codex e siga o processo de início de sessão no navegador quando o Codex aceder pela primeira vez
ao gateway. Conclua o início de sessão e a MFA da sua organização e, em seguida, regresse ao
cliente. Se a autorização expirar ou o Codex não a conseguir renovar, inicie sessão novamente quando lhe for solicitado.
O OAuth nativo do gateway requer um navegador e um callback de loopback acessível. Não dispõe de
uma alternativa com código de dispositivo. Se a CLI for executada através de SSH, defina redirect_port = 43127 na
tabela OAuth e registe o URI de redirecionamento correspondente descrito acima. A partir da
máquina com o navegador, encaminhe essa porta antes de iniciar o Codex:
ssh -L 43127:127.0.0.1:43127 user@remoteNessa sessão SSH, inicie codex e abra o URL de início de sessão do gateway no seu navegador
local. Uma CLI dentro de um contentor também necessita de um callback acessível a partir do
navegador. Se não conseguir tornar o callback acessível, utilize uma API key ou um auxiliar de
credenciais em alternativa.
Utilizar uma API key
Utilize esta definição quando o gateway espera uma API key no cabeçalho Authorization.
Adicione a seguinte definição à tabela existente
[model_providers.enterprise-gateway]:
env_key = "CODEX_GATEWAY_API_KEY"Disponibilize a sua credencial do gateway como CODEX_GATEWAY_API_KEY no
ambiente do processo que inicia o Codex, utilizando o mecanismo de distribuição de segredos
da sua organização. Não coloque a credencial no TOML nem num repositório. Uma variável
definida num terminal pode não estar disponível para uma aplicação iniciada a partir do ambiente de trabalho.
Utilize um cabeçalho de autenticação personalizado
Se o seu gateway exigir um cabeçalho como X-API-Key em vez de um token bearer,
substitua env_key na tabela do fornecedor por:
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }Utilize o nome exato do cabeçalho fornecido pelo seu administrador. O Codex lê o valor da
variável de ambiente indicada; mantenha a credencial fora do ficheiro de configuração.
Consulte a referência de configuração para obter informações sobre
model_providers.<id>.env_http_headers.
Com o início de sessão com o ChatGPT, utilize o cabeçalho personalizado para a chave do gateway, para que o Codex possa enviar a credencial OpenAI do utilizador em Authorization.
Se o cabeçalho personalizado for o seu único mecanismo de autenticação, utilize
model_catalog_json; a deteção remota do catálogo não será executada.
Utilize um auxiliar de credenciais da organização
Se o administrador fornecer autenticação baseada em comandos, utilize o utilitário auxiliar instalado
e a configuração fornecidos por ele em vez de env_key. Não configure ambos os mecanismos.
O utilitário auxiliar tem de existir na sua máquina; o Codex não o instala. Por exemplo,
adicione esta tabela sem env_key, utilizando o caminho do resolvedor e os
argumentos fornecidos pelo administrador:
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000A referência de autenticação de fornecedores personalizados define o comando, os argumentos, o tempo limite, o intervalo de atualização e o contrato de saída do token. Pergunte ao seu administrador como renovar o início de sessão se o auxiliar deixar de conseguir obter um token.
Com o início de sessão com o ChatGPT, execute o utilitário auxiliar antes de iniciar o Codex e transmita a respetiva saída através de um cabeçalho personalizado do gateway em vez de configurar a tabela auth. Quando a chave expirar, obtenha uma nova chave e reinicie o Codex.
Utilize caminhos absolutos resolvidos para os executáveis auxiliares e os ficheiros de catálogo.
Ativar o início de sessão com o ChatGPT (recomendado)
Se a sua organização utilizar um espaço de trabalho do ChatGPT, o início de sessão dá aos utilizadores acesso às funcionalidades para as quais são elegíveis, como os plugins da OpenAI. Aplicam-se os controlos do seu espaço de trabalho e o gateway continua a tratar os pedidos aos modelos. Compare a disponibilidade das funcionalidades.
Para a configuração manual, atualize a tabela [model_providers.enterprise-gateway] existente antes de iniciar sessão:
- Defina
requires_openai_auth = truee mantenhabase_urla apontar para o gateway. Remova quaisquer configuraçõesenv_key,experimental_bearer_tokeneauthdo fornecedor para que o Codex utilize a sua credencial OpenAI para a autenticação principal. - Envie a credencial do gateway separadamente. Para OAuth nativo do gateway, configure
gateway_oauth.deliverypara utilizar o cookie ou cabeçalho personalizado que o gateway aceita. Para uma API key ou um auxiliar de credenciais, utilize um cabeçalho de autenticação personalizado. ReserveAuthorizationpara a credencial OpenAI.
Inicie sessão no espaço de trabalho do ChatGPT indicado pelo administrador. Conclua o início de sessão no gateway, se lhe for solicitado, e depois verifique a ligação.
Os administradores podem distribuir configurações geridas do fornecedor e verificar o reencaminhamento de credenciais.
Tratar as credenciais no gateway
O gateway recebe duas credenciais em cada pedido ao modelo. Por exemplo, quando o Codex envia o token OAuth do gateway num cookie:
POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>Valide a credencial do gateway e remova o respetivo cookie ou cabeçalho personalizado. Oculte as credenciais e os dados sensíveis dos pedidos nos registos. Escolha a credencial a utilizar no serviço a montante:
- Reencaminhe a credencial do utilizador para inferência direta na OpenAI (recomendado). Isto permite à OpenAI atribuir a utilização e aplicar as definições de inferência desse utilizador. Para esta rota, o gateway tem de atuar como proxy de
/modelse/responsesparahttps://chatgpt.com/backend-api/codexe reencaminharAuthorizatione qualquer cabeçalhoChatGPT-Account-IDsem alterações. - Deixe o gateway autenticar-se junto do fornecedor de inferência. Utilize as credenciais configuradas no gateway para esse fornecedor. Exclua o token OpenAI do utilizador e qualquer cabeçalho
ChatGPT-Account-IDdo pedido ao serviço a montante.
Estes diagramas mostram a rota recomendada para inferência na OpenAI.
Como funciona uma chave do gateway com o início de sessão com o ChatGPT


Como funciona o OAuth do gateway com o início de sessão com o ChatGPT


Adicionar cabeçalhos de encaminhamento (opcional)
Utilize as configurações de encaminhamento fornecidas pelo administrador. Os operadores do gateway podem distribuir estas configurações e verificar a rota selecionada nos registos do gateway.
Apenas os pedidos ao fornecedor de modelos utilizam esta rota do gateway. As sessões de voz utilizam uma rota separada. O início de sessão no espaço de trabalho, os MCP servers e os plugins também podem utilizar outros caminhos de rede.
Iniciar o cliente
Com o início de sessão com o ChatGPT, inicie o cliente e inicie sessão no espaço de trabalho que fornece a configuração gerida. Se utilizar OAuth nativo do gateway, conclua também o início de sessão no gateway da sua organização quando lhe for solicitado. Em seguida, verifique a ligação.
Para um fornecedor configurado localmente, siga as instruções do seu cliente.
Configure a CLI
A CLI lê ~/.codex/config.toml por predefinição no macOS ou Linux. Depois de guardar
as definições do fornecedor, execute codex. No WSL, utilize a configuração e os caminhos do Linux,
a menos que CODEX_HOME aponte para outro local.
Configure a aplicação macOS
A aplicação macOS lê o mesmo ~/.codex/config.toml. Depois de guardar as definições do
fornecedor, reinicie a aplicação. Se utilizar uma variável de ambiente para a credencial,
certifique-se de que está disponível para o processo da aplicação.
Configure a aplicação Windows
Coloque as definições do fornecedor em %USERPROFILE%\.codex\config.toml e, em seguida, reinicie
a aplicação. Para autenticação baseada em comandos, utilize o resolvedor instalado pelo seu
administrador. Por exemplo, substitua a tabela de autenticação Unix por:
[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000No TOML do Windows, as cadeias literais entre aspas simples preservam as barras invertidas. Substitua
também os caminhos de catálogo Unix, por exemplo por
'C:\ProgramData\OpenAI\Codex\models.json', utilizando o caminho real
fornecido pelo seu administrador.
Configure os MCP servers e os plugins separadamente. Uma credencial de gateway de modelos não autoriza o acesso às suas ferramentas ou aos sistemas ligados.
Verifique a ligação
Utilize o ID do fornecedor e o alias do modelo indicados nas instruções do administrador. O fornecedor identifica a ligação configurada; o alias do modelo identifica um modelo encaminhado através dessa ligação. O início de sessão no ChatGPT e a autenticação no gateway controlam o acesso e podem ser ambos necessários.
Reinicie o cliente depois de alterar a configuração. Na CLI, inicie codex
e utilize /status para inspecionar o modelo e o fornecedor ativos. Na aplicação para computador,
verifique o modelo selecionado e a configuração.
Envie este prompt numa nova tarefa:
Reply with exactly: gateway-okA resposta esperada é gateway-ok. Uma resposta, por si só, não comprova que rota a processou: peça
ao seu administrador para confirmar que o gateway registou o seu utilizador, o alias do modelo
e a rota a montante pretendida. Não identifique o modelo perguntando-lhe o nome.
Resolva problemas de ligação
| Sintoma | O que verificar |
|---|---|
| O fornecedor esperado não está ativo. | Verifique o perfil selecionado e a precedência da configuração. Confirme que as chaves de nível superior não estão dentro de uma tabela de fornecedor. |
| O início de sessão OAuth ou a entrega do token falha. | Verifique o registo do cliente público, o URI de redirecionamento, os âmbitos e o cookie ou cabeçalho configurado. Confirme que o gateway aceita o token de acesso emitido. |
| A autenticação por API key ou auxiliar falha. | Verifique se a variável de credencial chega ao processo do cliente ou se o auxiliar instalado consegue obter um token válido. Peça ao administrador para distinguir a autenticação do gateway da autenticação do fornecedor a montante. |
| O modelo não é encontrado. | Confirme o nome do modelo fornecido e peça ao administrador para verificar a respetiva rota. |
| O modelo utiliza capacidades inesperadas. | Peça ao administrador para verificar se os metadados do catálogo correspondem ao modelo associado ao alias. |
| O streaming bloqueia ou os pedidos de seguimento falham. | Peça ao responsável pelo gateway para verificar o armazenamento em buffer do proxy, o evento final response.completed e a Compatibilidade do gateway. |
| Um caminho de catálogo ou de auxiliar falha. | Confirme que o ficheiro existe no caminho absoluto configurado no ambiente onde o Codex está em execução. |
Ao pedir ajuda, inclua a versão do cliente, o sistema operativo, o fornecedor e o alias do modelo esperados, o método de autenticação e o passo que falhou. Inclua a mensagem de erro e a hora do pedido para que o responsável pelo gateway possa localizar o pedido. Remova tokens, cookies, cabeçalhos de autorização e prompts sensíveis. Não envie ficheiros de credenciais nem uma exportação da configuração que contenha segredos.
Utilize uma implementação de gateway existente
Peça à equipa responsável pelo gateway as configurações do fornecedor para o Codex e o alias do modelo aprovado. Se a equipa ainda precisar de ativar uma rota para o Codex, partilhe a lista de verificação de migração para administradores.