Como configurar uma API OpenAI-compatible no Codex
Configure um custom model provider no Codex com a Base URL correta e a Responses API, depois valide a conexão com uma solicitação segura.
Para conectar uma API compatível ao Codex, crie um provedor de modelos personalizado na configuração do usuário, informe a Base URL do provedor, a variável de ambiente que contém a chave de API e o protocolo responses. Ser compatível apenas com /v1/chat/completions não basta: os custom providers da versão atual do Codex usam a Responses API. Os quatro passos abaixo, incluindo a inicialização com --profile, aplicam-se somente ao Codex CLI.
Para a BetterToken, os valores corretos são base_url = "https://www.bettertoken.ai/v1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-016&utm_content=openai-sovmestimyy-api-codex-podklyuchenie", env_key = "BETTERTOKEN_API_KEY" e wire_api = "responses". Antes de começar, abra o guia atual da BetterToken para Codex, crie sua própria chave de API e copie o Model ID completo e atual do Setup, do model plaza ou do guia vigente. Nomes de groups e mappings podem mudar; não os reaproveite de exemplos antigos. Esse é um workflow de API separado dos recursos incluídos em uma assinatura do ChatGPT.
Pré-requisitos
- Node.js e npm, necessários para instalar o Codex CLI oficial.
- Sua própria conta BetterToken, sua própria chave de API e o Model ID completo e atual do Setup, do model plaza ou do guia vigente.
- Saldo ou uma cota de teste atualmente disponível para uma solicitação curta. Elegibilidade, validade, modelos aceitos e demais regras dependem do Workspace ou da oferta vigente.
- Um terminal no macOS/Linux ou o Windows PowerShell. Há comandos para os dois sistemas abaixo.
- Para outro provedor, a confirmação de suporte à Responses API, ao streaming SSE e aos tool calls necessários para o seu uso.
Verifique a compatibilidade antes de configurar
Se o provedor mostra apenas um exemplo de Chat Completions e não informa nada sobre Responses, peça uma confirmação ou faça primeiro um teste mínimo. Não copie às cegas para o Codex a configuração de um cliente de chat genérico.
Passo 1. Instale ou atualize o Codex CLI
Confira os campos atuais na Config Reference oficial do Codex. Em 14 de agosto de 2026, model_provider seleciona uma entrada de model_providers, env_key nomeia a variável de ambiente que contém a chave do provedor e responses é o único valor aceito para wire_api. A referência atual armazena profiles nomeados ao lado do config.toml principal e os seleciona com --profile profile-name.
Passo 2. Crie um arquivo de profile separado
A referência de configuração atual da OpenAI armazena o profile nomeado em $CODEX_HOME/bt.config.toml. Por padrão, CODEX_HOME costuma corresponder a ~/.codex no macOS/Linux e a %USERPROFILE%\.codex no Windows, mas um valor personalizado tem prioridade e altera o caminho real.
Confira o diretório no macOS/Linux sem alterar a variável:
No PowerShell:
Crie bt.config.toml exatamente no diretório exibido:
O arquivo $CODEX_HOME/bt.config.toml corresponde ao comando --profile bt. Esse profile não substitui o $CODEX_HOME/config.toml principal, portanto o provider oficial continua disponível. Substitua YOUR_MODEL_ID pelo API ID completo e atual do Setup, do model plaza ou do guia vigente. Não use o nome exibido para o modelo se ele for diferente do API ID.
Os nomes do provider também precisam coincidir exatamente: model_provider = "bettertoken", no nível raiz, aponta para [model_providers.bettertoken].
O Codex acrescenta /responses por conta própria. Por isso, a Base URL termina em /v1, não em /v1/responses; incluir o endpoint em base_url duplicaria o caminho.
Passo 3. Forneça a chave de API pelo ambiente
No macOS/Linux:
Para uma configuração persistente, use um gerenciador de segredos protegido ou um arquivo de configuração do shell com permissões adequadas. Nunca adicione a chave a um repositório, a .env.example, ao README ou a um comando que permanecerá no histórico do shell de um computador compartilhado. Não grave a chave BetterToken em ~/.codex/auth.json; esse arquivo é usado para o login oficial do Codex.
Confirme que a variável existe sem exibir o valor:
No Windows PowerShell, defina a chave na janela atual e salve-a para as próximas sessões:
Passo 4. Inicie o profile e verifique a rota
Reinicie o Codex CLI e execute:
O primeiro teste deve ser curto e não pode alterar arquivos:
Uma resposta correta, sozinha, não comprova qual rota processou a solicitação. Confirme todos os itens abaixo:
- a resposta chega sem erro de autenticação, modelo ou protocolo;
- o modelo ativo corresponde ao Model ID escolhido;
- depois do horário do teste, uma nova solicitação aparece no BetterToken Workspace com o modelo, o status e o uso esperados.
Depois, permita que o Codex leia um único arquivo descartável. Só abra um repositório de trabalho ou autorize alterações de arquivos após esse teste read-only ser concluído com sucesso.
Os quatro passos com --profile desta seção são específicos do Codex CLI. No Codex Desktop, confirme no guia atual da BetterToken como selecionar a configuração e iniciar o cliente. Para a extensão do VS Code, siga o guia separado; não copie o profile do CLI nem seu método de autenticação sem verificar as instruções atuais.
Diagnóstico por código de erro
Profile não encontrado ou configuração não aplicada
Verifique três correspondências exatas: o arquivo se chama bt.config.toml, o comando contém --profile bt e model_provider = "bettertoken" aponta para [model_providers.bettertoken]. Em seguida, feche completamente o Codex CLI, abra um novo terminal e repita o teste curto.
Variáveis de ambiente antigas da OpenAI podem substituir a rota esperada. No macOS/Linux, verifique apenas se elas existem, sem imprimir seus valores, e depois remova-as:
No PowerShell, remova-as da janela atual e das próximas sessões do usuário:
Depois da limpeza, abra um novo terminal, defina novamente apenas BETTERTOKEN_API_KEY e execute codex --profile bt.
404 ou HTML no lugar de JSON
Na maioria dos casos, o endpoint foi montado de forma incorreta. Verifique se base_url não contém /responses, /chat/completions nem um caminho extra de proxy. Para a BetterToken, o valor deve ser exatamente `https://www.bettertoken.ai/v1%60.?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-016&utm_content=openai-sovmestimyy-api-codex-podklyuchenie
401 ou 403
Confira o nome de env_key, confirme que BETTERTOKEN_API_KEY está disponível no mesmo processo que inicia o Codex e verifique se o modelo escolhido está acessível com o mapping atual da chave. Se a chave puder ter aparecido em logs ou outra saída exposta, revogue-a e crie outra.
model not found
Copie novamente o Model ID completo e atual do Setup, do model plaza ou do guia vigente e confirme que ele está disponível com o mapping atual da chave. Não tente adivinhar o sufixo de uma versão nem trate o nome de um group antigo como permanente.
Erro de Chat Completions ou campo não suportado
Confirme que wire_api = "responses" e que o provedor implementa os recursos da Responses API necessários para o Codex. Trocar o valor para chat não resolve: a referência atual do Codex aceita apenas responses para custom providers.
O stream começa e é interrompido
Repita primeiro uma única solicitação curta. Se ela ainda falhar, verifique o proxy, o timeout e o suporte a SSE. Não aumente a quantidade de retries sem um limite: novas tentativas podem criar solicitações duplicadas e uso adicional.
Como reverter sem perder a configuração oficial
No Codex CLI, como o provider está isolado em $CODEX_HOME/bt.config.toml, encerre a sessão atual e inicie o cliente sem --profile bt; assim, o $CODEX_HOME/config.toml principal volta a ser aplicado. Não exclua auth.json nem substitua o token oficial por uma chave de API de terceiros. No Codex Desktop, siga o procedimento de seleção ou reversão indicado no guia atual. Para a extensão do VS Code, use as instruções de reversão do guia separado.
Resumo
Uma conexão funcional exige mais do que uma URL “OpenAI-compatible”. Quatro elementos precisam coincidir: suporte à Responses API, Base URL exata, Model ID disponível e variável de ambiente com a chave de API. Mantenha o custom provider em um arquivo de profile separado, faça um teste read-only e confirme a nova solicitação no Workspace antes de abrir um repositório de trabalho.
Para evitar campos ou mappings desatualizados, siga a configuração atual da BetterToken para Codex, crie sua própria chave de API, copie o Model ID completo e atual e envie a primeira solicitação read-only com o profile bt.