Ligar a um gateway
Ligue o Codex a um gateway de LLM utilizando o URL do gateway, o alias do modelo e a credencial ou o resolvedor de tokens fornecidos pela sua organização.
Verifique se já existe uma configuração
Antes de adicionar algo, verifique se o seu administrador já configurou o Codex.
- 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, avance para Verificar a ligação.
Obtenha os detalhes de ligação ao gateway
Instale a Codex CLI ou a aplicação para computador aprovada pela sua organização. Para configurar o Codex, obtenha estes valores junto da equipa responsável pelo 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.
- A sua credencial do gateway com âmbito limitado e a respetiva variável de ambiente, ou um resolvedor de tokens instalado e a respetiva configuração.
- Qualquer ficheiro de catálogo de modelos necessário 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"
env_key = "CODEX_GATEWAY_API_KEY"Se o seu administrador fornecer um catálogo de modelos, guarde-o localmente e adicione
model_catalog_json antes da primeira tabela TOML, utilizando o caminho absoluto do ficheiro.
Os aliases personalizados precisam 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.
enterprise-gateway é um ID de fornecedor ilustrativo. Utilize o mesmo ID em
model_provider, [model_providers.<id>] e [model_providers.<id>.auth].
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.
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.
Utilize um auxiliar de credenciais da organização
Se o seu administrador fornecer autenticação baseada em comandos, utilize o auxiliar instalado
por este e a respetiva configuração em vez de env_key. Não configure ambos os mecanismos.
O auxiliar tem de existir na sua máquina; o Codex não o instala. Por exemplo,
substitua a definição env_key do exemplo por esta tabela, utilizando o caminho do resolvedor e
os argumentos fornecidos pelo seu 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.
Utilize caminhos absolutos resolvidos para os executáveis auxiliares e os ficheiros de catálogo.
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
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.
Isto verifica uma ligação inicial. Os administradores devem também concluir as verificações de implementação para streaming, ferramentas e turnos subsequentes.
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. |
| A autenticação falha. | Verifique se a variável de credencial chega ao processo do cliente ou se o auxiliar instalado consegue obter um token atual. Peça ao administrador para distinguir a autenticação do gateway da autenticação 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 turnos subsequentes falham. | Peça ao responsável pelo gateway para verificar a colocação em memória intermédia no proxy, o evento terminal response.completed e a Compatibilidade do gateway. |
| Um caminho de catálogo ou auxiliar falha. | Confirme que o ficheiro existe no caminho absoluto configurado no ambiente que executa o Codex. |
Ao pedir ajuda, inclua a mensagem de erro, removendo os tokens e os prompts sensíveis.
Utilize uma implementação de gateway existente
Se a sua organização já utilizar um gateway com outra ferramenta de programação, poderá reutilizar o respetivo caminho de rede, registo e acesso a fornecedores. Trabalhe com a sua equipa responsável pelo gateway para configurar e testar uma ligação do Codex:
- Identifique o URL do gateway existente, o mecanismo de credenciais, os cabeçalhos necessários, as rotas dos modelos e o método de distribuição da configuração.
- Peça à equipa responsável pelo gateway para confirmar que o gateway suporta o comportamento da API exigido pelo Codex e para configurar uma rota de modelo do Codex.
- Obtenha uma credencial do gateway com âmbito limitado ou um auxiliar de credenciais, o nome do modelo e qualquer catálogo de modelos necessário junto da equipa responsável pelo gateway.
- Configure o Codex com esses valores.
- Verifique a ligação na CLI ou na aplicação para computador que pretende utilizar. Peça à equipa responsável pelo gateway para concluir as verificações de streaming, ferramentas e turnos subsequentes.
- Depois de o projeto-piloto passar nas verificações, siga Implementar o Codex através de um gateway para distribuir a configuração a outros programadores.
Para consultar a lista de verificação de migração para administradores e o mapeamento de configuração, consulte Reutilizar uma implementação de gateway existente.