Conecte o Codex ao gateway de modelos da sua organização usando as configurações do provedor e o método de autenticação fornecidos pela equipe responsável pelo gateway. O gateway encaminha as solicitações de modelo para o seu backend, como o Amazon Bedrock.
Para implantar o gateway em toda a organização, consulte Implantar um gateway. Para saber qual comportamento a API deve oferecer, consulte Compatibilidade do gateway. Para se conectar diretamente ao Bedrock sem um gateway, consulte Amazon Bedrock.
Verificar se já existe uma configuração
Instale o cliente do Codex na versão que o administrador testou. Se a sua organização gerencia as configurações, abra esse cliente e siga as instruções de login que você recebeu. Nesse caso, você pode pular os exemplos de configuração do provedor abaixo.
- Na CLI, verifique o perfil selecionado e execute
codex doctor. Após iniciar a CLI, use/statuspara confirmar o modelo e o provedor ativos. - No aplicativo para macOS, verifique
~/.codex/config.tomlou a configuração gerenciada que sua organização distribui. - No aplicativo para Windows, verifique
%USERPROFILE%\.codex\config.tomlou a configuração do sistema que sua organização distribui.
Se o provedor do gateway e o modelo esperados já estiverem ativos, conclua as etapas de login indicadas pelo administrador e prossiga para Verificar a conexão. Evite adicionar uma segunda configuração de provedor a uma máquina gerenciada. Se as configurações forem diferentes das indicadas pelo administrador, pergunte a ele qual camada de configuração deve fornecê-las antes de editar os arquivos locais.
Obter os dados de conexão do gateway
Para a configuração manual, confirme se é preciso fazer login no espaço de trabalho do ChatGPT, autenticar-se no gateway ou realizar as duas etapas.
Para configurar o Codex por conta própria, peça à equipe responsável pelo gateway os seguintes dados:
- A URL base HTTPS do gateway, incluindo o caminho da API, como
https://gateway.example.com/v1. - O nome do modelo e o ID do provedor que você deve usar.
- O método de autenticação: OAuth nativo do gateway, uma chave de API com escopo delimitado e a respectiva variável de ambiente ou um auxiliar de credenciais instalado.
- Para OAuth, a URL de autorização, a URL do endpoint de token, o ID do cliente público e os escopos exigidos, se houver. Se o gateway usar um cookie ou um cabeçalho personalizado, peça também o nome desse cookie ou cabeçalho.
- A URL do catálogo de modelos, caso seja necessária, ou o arquivo de catálogo e seu caminho absoluto local.
Configurar o provedor
Abra config.toml em ~/.codex/config.toml no macOS ou Linux, ou em %USERPROFILE%\.codex\config.toml no Windows.
Incorpore este exemplo à configuração existente e substitua a URL e o modelo pelos valores fornecidos pelo administrador. Não defina novamente uma chave ou tabela que já existe. Este exemplo usa gpt-6-sol. Só use esse modelo sem um catálogo personalizado se o administrador confirmar que sua versão do Codex reconhece o modelo e que os metadados incluídos nessa versão correspondem aos do gateway.
Mantenha model, model_provider, model_catalog_json e web_search antes da primeira tabela TOML. As chaves inseridas após o cabeçalho de uma tabela pertencem a essa tabela. Por isso, o Codex não as lê como configurações de nível superior.
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 configurações de autenticação fornecidas pela equipe responsável pelo gateway.
enterprise-gateway é um exemplo de ID de provedor. Use o mesmo ID em model_provider e nas tabelas de provedor e de autenticação correspondentes. Este exemplo desativa a pesquisa na Web para o teste inicial de conexão. Antes de ativá-la, o administrador deve verificar se há suporte ao recurso.
Configurar o catálogo de modelos
Confirme com a equipe responsável pelo gateway como o Codex obtém as informações sobre os recursos e as instruções do modelo selecionado:
- Nome incluído no Codex: se o gateway aceitar o nome exato do modelo incluído na sua versão do Codex e encaminhar as solicitações ao modelo correspondente, defina
modelcom esse nome. O Codex já tem os metadados desse modelo. - Endpoint do catálogo: se o gateway fornecer metadados compatíveis com o Codex, use a URL completa do catálogo. Pode ser um endpoint
/v1/modelsque implemente o formato de resposta do catálogo do Codex. Para usar aliases personalizados, não basta que a resposta liste os IDs dos modelos. - Arquivo de catálogo: se o gateway usar aliases personalizados e o administrador distribuir um arquivo, siga o exemplo de arquivo models.json local. Use um arquivo local se o OAuth nativo do gateway for sua única credencial e você precisar de metadados personalizados.
Se você usar uma chave de API ou um auxiliar de credenciais para a autenticação e o administrador fornecer uma URL de catálogo, adicione-a à tabela [model_providers.enterprise-gateway] existente:
model_catalog_url = "https://gateway.example.com/codex/models.json"Remova qualquer configuração model_catalog_json em vigor, pois ela tem prioridade sobre a URL. Os administradores podem consultar os requisitos do endpoint na seção sobre configuração de um catálogo remoto.
Se o administrador fornecer um arquivo de catálogo de modelos local, salve-o e adicione model_catalog_json antes da primeira tabela TOML, usando o caminho absoluto do arquivo. Os aliases personalizados precisam de metadados correspondentes no catálogo. Por exemplo:
model_catalog_json = "/etc/codex/gateway-models.json"Use o nome do modelo e o catálogo que o administrador forneceu em conjunto. Só adicione um caminho de catálogo se o arquivo existir nesse local.
Escolher um método de autenticação
Use o OAuth nativo do gateway para fazer login pelo navegador, uma chave de API se precisar de uma credencial com escopo delimitado ou um auxiliar de credenciais se a organização fornecer um comando.
Usar o OAuth nativo do gateway
O OAuth do gateway funciona independentemente do login com o ChatGPT. Use-o quando o gateway aceitar tokens de acesso emitidos pelo provedor de identidade da organização, como o Microsoft Entra ID. O Codex gerencia o login pelo navegador, armazena as credenciais de forma criptografada e renova o token de acesso quando o servidor de autorização emite um token de atualização.
Se a autenticação for feita apenas no gateway, a CLI do Codex, a partir da versão 0.166.0, envia por padrão o token de acesso em Authorization: Bearer <gateway access token>. Remova qualquer entrada Authorization de http_headers ou env_http_headers desse provedor.
A equipe responsável pelo gateway deve registrar um cliente OAuth público compatível com o fluxo de código de autorização com PKCE. Adicione a tabela abaixo à configuração do provedor em config.toml e substitua as URLs e o ID do cliente pelos valores fornecidos pela equipe:
[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 essa tabela usando os valores exigidos pelo provedor de identidade e pelo gateway. Se o provedor exigir escopos específicos para emitir tokens de atualização, solicite esses escopos. Por padrão, o Codex usa uma porta de loopback disponível. Se o provedor de identidade exigir uma URI de redirecionamento fixa, defina redirect_port e registre http://127.0.0.1:43127/callback para este exemplo.
Se o gateway esperar o token em um cookie ou 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 implantação também exigir login com o ChatGPT, use o cookie ou um cabeçalho separado para o gateway, conforme os exemplos acima. Consulte Habilitar o login com o ChatGPT.
Para usar esse fluxo com um gateway que só aceita uma chave de API estática, primeiro é preciso adicionar ao gateway suporte ao token OAuth e ao método usado para enviá-lo. O gateway continua gerenciando suas próprias credenciais de acesso aos serviços de destino, como as credenciais da AWS para o Bedrock.
Quando o OAuth for sua única credencial, mantenha requires_openai_auth = false e remova as configurações anteriores de env_key, experimental_bearer_token ou auth usadas para a credencial do gateway. Use um catálogo de modelos local se precisar de metadados personalizados para o modelo. O OAuth, por si só, não habilita a descoberta de catálogos remotos.
Reinicie o aplicativo de desktop e siga a instrução de login do gateway para abrir o navegador. Na CLI, inicie codex e siga as instruções de login pelo navegador quando o Codex acessar o gateway pela primeira vez. Conclua o login e a MFA da organização e volte ao cliente. Se a autorização expirar ou o Codex não conseguir renová-la, faça login novamente quando solicitado.
O OAuth nativo do gateway exige um navegador e um endereço de callback de loopback acessível. Não há opção de autenticação por código de dispositivo. Se você executar a CLI via SSH, defina redirect_port = 43127 na tabela OAuth e registre a URI de redirecionamento correspondente, descrita acima. Na máquina em que você usa o navegador, configure o encaminhamento dessa porta antes de iniciar o Codex:
ssh -L 43127:127.0.0.1:43127 user@remoteNessa sessão SSH, inicie codex e abra a URL de login do gateway no navegador local. Uma CLI executada em um contêiner também precisa de um endereço de callback acessível pelo navegador. Se não for possível tornar esse endereço acessível, use uma chave de API ou um auxiliar de credenciais.
Usar uma chave de API
Use esta configuração quando o gateway esperar uma chave de API no cabeçalho Authorization.
Adicione a seguinte configuração à tabela [model_providers.enterprise-gateway] existente:
env_key = "CODEX_GATEWAY_API_KEY"Use o mecanismo de distribuição de segredos da organização para disponibilizar a credencial do gateway como CODEX_GATEWAY_API_KEY no ambiente do processo que inicia o Codex. Não inclua a credencial no arquivo TOML nem em um repositório. Uma variável definida em um terminal pode não estar disponível para um aplicativo iniciado pela interface gráfica.
Usar um cabeçalho de autenticação personalizado
Se o gateway exigir um cabeçalho como X-API-Key em vez de um token do tipo bearer, substitua env_key na tabela do provedor pela seguinte configuração:
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }Use exatamente o nome do cabeçalho fornecido pelo administrador. O Codex lê o valor da variável de ambiente indicada. Mantenha a credencial fora do arquivo de configuração. Consulte a referência de configuração para saber mais sobre model_providers.<id>.env_http_headers.
Se você fizer login com o ChatGPT, use o cabeçalho personalizado para a chave do gateway. Assim, o Codex poderá enviar a credencial da OpenAI do usuário em Authorization.
Se o cabeçalho personalizado for seu único mecanismo de autenticação, use model_catalog_json, pois a descoberta de catálogos remotos não será executada.
Usar um auxiliar de credenciais da organização
Se o administrador fornecer autenticação por comando, use o auxiliar instalado e a configuração fornecida por ele em vez de env_key. Não configure os dois mecanismos ao mesmo tempo. O auxiliar precisa estar instalado na sua máquina. O Codex não o instala. Por exemplo, adicione a tabela abaixo sem env_key, usando o caminho do executável que obtém a credencial 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 para provedores personalizados define o comando, os argumentos, o tempo limite, o intervalo de atualização e os requisitos para a saída que contém o token. Se o auxiliar não conseguir mais obter um token, pergunte ao administrador como renovar sua sessão.
Se você fizer login com o ChatGPT, execute o auxiliar antes de iniciar o Codex e envie a saída pelo cabeçalho personalizado do gateway em vez de configurar a tabela auth. Quando a chave expirar, obtenha outra e reinicie o Codex.
Use caminhos absolutos já resolvidos para os executáveis auxiliares e os arquivos de catálogo.
Habilitar o login com o ChatGPT (recomendado)
Se sua organização usa um espaço de trabalho do ChatGPT, o login dá aos usuários acesso aos recursos para os quais são elegíveis, como os plug-ins da própria OpenAI. Os controles do espaço de trabalho se aplicam, e o gateway continua processando as solicitações de modelo. Compare a disponibilidade dos recursos.
Para a configuração manual, atualize a tabela [model_providers.enterprise-gateway] existente antes de fazer login:
- Defina
requires_openai_auth = truee mantenhabase_urlapontando para o gateway. Remova as configuraçõesenv_key,experimental_bearer_tokeneauthdo provedor, se houver, para que o Codex use sua credencial da OpenAI na autenticação principal. - Envie a credencial do gateway separadamente. Para o OAuth nativo do gateway, configure
gateway_oauth.deliverypara usar o cookie ou o cabeçalho personalizado que o gateway aceita. Para uma chave de API ou um auxiliar de credenciais, use um cabeçalho de autenticação personalizado. ReserveAuthorizationpara a credencial da OpenAI.
Faça login no espaço de trabalho do ChatGPT indicado pelo administrador. Se solicitado, conclua o login no gateway. Em seguida, verifique a conexão.
Os administradores podem distribuir as configurações gerenciadas do provedor e verificar o encaminhamento das credenciais.
Processar credenciais no gateway
O gateway recebe duas credenciais em cada solicitação de modelo. Veja um exemplo em que o Codex envia o token OAuth do gateway em um 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 da solicitação o cookie ou o cabeçalho personalizado que a contém. Oculte nos logs as credenciais e os dados sensíveis das solicitações. Escolha qual credencial usar ao encaminhar a solicitação ao provedor de inferência:
- Encaminhe a credencial do usuário para inferência direta na OpenAI (recomendado). Isso permite que a OpenAI atribua o uso ao usuário e aplique as configurações de inferência dele. Nessa rota, o gateway deve atuar como proxy para
/modelse/responses, encaminhando as solicitações parahttps://chatgpt.com/backend-api/codex. Deve também encaminharAuthorizatione, se presente, o cabeçalhoChatGPT-Account-ID, sem alterá-los. - Deixe o gateway se autenticar no provedor de inferência. Use as credenciais configuradas no gateway para esse provedor. Não inclua o token da OpenAI do usuário nem o cabeçalho
ChatGPT-Account-IDna solicitação encaminhada ao provedor.
Os diagramas mostram a rota recomendada para inferência na OpenAI.
Como o gateway usa a chave quando o usuário faz login com o ChatGPT
Como o OAuth do gateway funciona quando o usuário faz login com o ChatGPT
Adicionar cabeçalhos de roteamento (opcional)
Use as configurações de roteamento fornecidas pelo administrador. Os operadores do gateway podem distribuir essas configurações e verificar nos logs do gateway qual rota foi selecionada.
Somente as solicitações destinadas ao provedor de modelos usam essa rota do gateway. As sessões de voz usam uma rota separada. O login no espaço de trabalho, os servidores MCP e os plug-ins também podem usar outros caminhos de rede.
Iniciar o cliente
Se você usar o login com o ChatGPT, inicie o cliente e entre no espaço de trabalho que fornece a configuração gerenciada. Se usar o OAuth nativo do gateway, conclua também o login no gateway da organização quando solicitado. Em seguida, verifique a conexão.
Se o provedor estiver configurado localmente, siga as instruções do seu cliente.
Configurar a CLI
Por padrão, a CLI lê ~/.codex/config.toml no macOS ou Linux. Depois de salvar as configurações do provedor, execute codex. No WSL, use a configuração e os caminhos do Linux, a menos que CODEX_HOME aponte para outro local.
Configurar o aplicativo para macOS
O aplicativo para macOS lê o mesmo arquivo ~/.codex/config.toml. Depois de salvar as configurações do provedor, reinicie o aplicativo. Se usar uma variável de ambiente para a credencial, verifique se ela está disponível para o processo do aplicativo.
Configurar o aplicativo para Windows
Insira as configurações do provedor em %USERPROFILE%\.codex\config.toml e reinicie o aplicativo. Para autenticação por comando, use o executável que o administrador instalou para obter a credencial. Por exemplo, substitua a tabela de autenticação do Unix pela seguinte tabela:
[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 = 300000Em arquivos TOML no Windows, strings literais entre aspas simples preservam as barras invertidas. Substitua também os caminhos de catálogo do Unix pelo caminho real fornecido pelo administrador, como 'C:\ProgramData\OpenAI\Codex\models.json'.
Configure os servidores MCP e os plug-ins separadamente. A credencial do gateway de modelos não autoriza o acesso às suas ferramentas nem aos sistemas conectados.
Verificar a conexão
Use o ID do provedor e o alias do modelo indicados pelo administrador. O provedor identifica a conexão configurada. O alias identifica o modelo ao qual as solicitações são encaminhadas por essa conexão. O login com o ChatGPT e a autenticação no gateway controlam o acesso, e ambos podem ser necessários.
Reinicie o cliente após alterar a configuração. Na CLI, inicie codex e use /status para verificar o modelo e o provedor ativos. No aplicativo de desktop, verifique o modelo selecionado e a configuração.
Envie este prompt em uma nova tarefa:
Reply with exactly: gateway-okA resposta esperada é gateway-ok. A resposta, por si só, não comprova qual rota processou a solicitação. Peça ao administrador que confirme se o gateway registrou seu usuário, o alias do modelo e a rota pretendida até o provedor. Não tente identificar o modelo perguntando a ele qual é o seu nome.
Solucionar problemas de conexão
| Sintoma | O que verificar |
|---|---|
| O provedor esperado não está ativo. | Verifique o perfil selecionado e a ordem de prioridade das configurações. Confirme se as chaves de nível superior estão fora das tabelas de provedor. |
| O login via OAuth ou o envio do token falha. | Verifique o registro do cliente público, a URI de redirecionamento, os escopos e o cookie ou cabeçalho configurado. Confirme se o gateway aceita o token de acesso emitido. |
| A autenticação por chave de API ou auxiliar de credenciais falha. | Verifique se a variável que contém a credencial está disponível para o processo do cliente ou se o auxiliar instalado consegue obter um token válido. Peça ao administrador que identifique se a falha ocorre na autenticação com o gateway ou com o provedor de destino. |
| O modelo não foi encontrado. | Confirme o nome do modelo fornecido e peça ao administrador que verifique a rota desse modelo. |
| O modelo usa recursos inesperados. | Peça ao administrador que verifique se os metadados do catálogo correspondem ao modelo associado ao alias. |
| O streaming trava ou as interações subsequentes falham. | Peça ao responsável pelo gateway que verifique o uso de buffer pelo proxy e o evento final response.completed e que consulte Compatibilidade do gateway. |
| O caminho do catálogo ou do auxiliar de credenciais não funciona. | Confirme se o arquivo existe no caminho absoluto configurado, no ambiente em que o Codex está em execução. |
Ao pedir ajuda, informe a versão do cliente, o sistema operacional, o provedor e o alias do modelo esperados, o método de autenticação e a etapa em que ocorreu a falha. Inclua a mensagem de erro e o horário da solicitação para que o responsável pelo gateway possa localizá-la. Remova tokens, cookies, cabeçalhos de autorização e prompts sensíveis. Não envie arquivos de credenciais nem uma cópia da configuração que contenha segredos.
Usar um gateway já implantado
Peça à equipe responsável pelo gateway as configurações do provedor para o Codex e o alias de modelo aprovado. Se a equipe ainda precisar habilitar uma rota para o Codex, compartilhe a lista de verificação de migração para administradores.