Codex CLI/App: provedor próprio, API Key e Base URL

Codex CLI e Codex App compartilham config.toml e auth.json para tarefas locais. Esta configuração usa uma BetterToken API Key via OpenAI Responses.

Configurações principais

Campo	Valor
API Key	auth.json → OPENAI_API_KEY
Base URL	https://bettertoken.ai/v1
Model	gpt-6-astra

Pré-requisitos

• Instale Node.js se usar npm ou o script de configuração automática BetterToken
• Crie uma BetterToken API Key
• Copie um Model ID do model plaza ou da caixa de diálogo Setup da Key

Cadastre-se e obtenha uma BetterToken API Key→

Já tem uma conta? Entre, recarregue o saldo e crie uma chave no console.

Instalação

Você pode usar os instaladores autônomos oficiais para macOS/Linux ou Windows sem Node.js. Se preferir npm, instale Node.js primeiro e execute:

npm install -g @openai/codex

Localize os arquivos e faça backup

Se você definiu um CODEX_HOME personalizado, edite config.toml e auth.json nesse diretório. Caso contrário, use ~/.codex no macOS / Linux ou %USERPROFILE%\.codex no Windows. CLI e App devem usar o mesmo diretório. O WSL tem seu próprio diretório de usuário.

Feche o Codex completamente antes de editar. Faça backup dos dois arquivos em um local privado. Crie os arquivos que faltarem. Substitua as configurações existentes sem duplicar chaves ou tabelas; preserve as demais configurações.

Esta configuração troca o login com ChatGPT pela autenticação com API Key. Ela não preserva o acesso à conta oficial. Proteja auth.json e seus backups; não os compartilhe nem os inclua no repositório.

Configuração pela linha de comando

O script de configuração automática do BetterToken grava a configuração do provedor para o Codex. Ele exige Node.js e solicita a API Key ou o Model ID quando esses valores não são informados como argumentos.

macOS / Linux

curl -fsSL "https://bettertoken.ai/install-codex-provider.sh" | bash

Windows

iwr "https://bettertoken.ai/install-codex-provider.ps1" -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"

Após a instalação, compare os dois arquivos com a configuração manual abaixo e corrija as diferenças antes de iniciar o Codex.

Configuração manual

Edite config.toml

Este guia usa config.toml do usuário. Coloque chaves raiz antes de todas as tabelas TOML, não em [projects."<path>"]; essa tabela armazena o trust_level do projeto. O ID selecionado deve corresponder à tabela. Na autenticação por arquivo, remova env_key e experimental_bearer_token do provider selecionado.

model_provider = "bettertoken"
model = "gpt-6-astra"
cli_auth_credentials_store = "file"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

O exemplo usa GPT-6 Astra (gpt-6-astra). Para outro modelo, copie o ID completo da model plaza e substitua model. GPT, Kimi e GLM usam a mesma estrutura de autenticação por arquivos; a configuração automática está disponível para GPT.

Edite auth.json

auth.json fica no mesmo diretório que config.toml. Se auth.json não existir, crie esse arquivo no mesmo diretório. Use o JSON abaixo como conteúdo do arquivo, substitua YOUR_API_KEY pela sua BetterToken API Key e salve o arquivo.

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

Parâmetros de configuração

Parâmetro	Função e localização	Padrões e exemplos
model_provider	Raiz da configuração do usuário; seleciona o ID definido abaixo.	Padrão: openai; aqui bettertoken.
model	Raiz; Model ID completo da praça de modelos.	Exemplo: gpt-6-astra; substitua conforme necessário.
cli_auth_credentials_store	Raiz; armazenamento das credenciais de login.	Aqui file: lê auth.json no mesmo diretório.
name	Tabela do provider; apenas o nome exibido.	BetterToken não é um Model ID.
base_url	Tabela do provider; Base URL da API do modelo.	Use https://bettertoken.ai/v1; Codex adiciona /responses.
wire_api	Tabela do provider; protocolo das requisições.	Atualmente só aceita responses, também usado por padrão.
requires_openai_auth	Tabela do provider; autenticação OpenAI e armazenamento de credenciais.	Padrão: false; aqui true. Não é um seletor para preservar arquivos de login.
supports_websockets	Tabela do provider; suporte a Responses WebSocket.	Padrão: false; aqui mantém HTTP/SSE.
auth_mode	Em auth.json; modo de autenticação.	Aqui apikey: substitui a autenticação oficial do ChatGPT.
OPENAI_API_KEY	Em auth.json; chave da autenticação da API.	Substitua YOUR_API_KEY pela BetterToken API Key.

A autenticação por arquivo muda para o modo API Key. Para manter a conta oficial, use preservação do login; não misture os modos. A diferença é o objetivo de autenticação, não CLI, App ou Extension.

Ajustes opcionais

Os três ajustes são opcionais, não requisitos de conexão. Adicione-os à tabela existente [model_providers.bettertoken] quando necessário; não crie uma tabela duplicada.

request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000

Parâmetro	Função e localização	Padrões e exemplos
request_max_retries	Tabela do provider; máximo de novas tentativas HTTP.	Padrão: 4; ajuste à conexão.
stream_max_retries	Tabela do provider; reconexões após interrupção do fluxo.	Padrão: 5; 8 é um valor personalizado opcional.
stream_idle_timeout_ms	Tabela do provider; limite de inatividade do fluxo em milissegundos.	Padrão: 300000; não é o tempo total da tarefa.

Camadas de configuração e chaves antigas

Não coloque modelo ou raciocínio em [projects."<path>"]. O modelo de um projeto pode usar chaves raiz em .codex/config.toml de um projeto confiável; provider e autenticação ficam na configuração do usuário. Perfis atuais usam NAME.config.toml em CODEX_HOME, selecionado com codex --profile NAME, não tabelas antigas [profiles.NAME] nem o seletor raiz profile.

Verificar a conexão

Salve os dois arquivos. Inicie uma nova sessão do Codex CLI diretamente pelo terminal:

codex

Feche o Codex App completamente, incluindo os processos em segundo plano. Abra-o novamente e crie uma nova tarefa local. Envie um prompt curto em cada cliente que usa. Uma resposta normal confirma a conexão desse cliente.

O Codex CLI 0.164.0 também passou nos testes de autenticação por variável de ambiente, incluindo chamadas de ferramentas para leitura de arquivos: env_key funcionou tanto com requires_openai_auth = false quanto com esse campo omitido.

Trocar de modelo

Altere model e, opcionalmente, review_model. Salve o arquivo, encerre o processo atual do Codex e inicie-o novamente. Use o Model ID da caixa de diálogo Setup ou do model plaza.

Erros comuns

Em caso de 401, 403 ou solicitação de login, confira o diretório ativo, a Key em auth.json, auth_mode = apikey, cli_auth_credentials_store = file e requires_openai_auth = true. Para erros de provedor ou modelo, confira o ID do provedor, https://bettertoken.ai/v1, wire_api = responses e a disponibilidade do modelo. Se as alterações não forem aplicadas, verifique as opções que sobrescrevem a configuração e confirme que CLI e App usam o mesmo CODEX_HOME.

Configuração avançada

Extensão Codex

CLI, App e Extension compartilham configuração com o mesmo CODEX_HOME. Escolha a autenticação pelo objetivo: API Key ou preservar o login oficial.

guia de configuração da extensão Codex

Perguntas relacionadas

• Use as APIs diretamente com exemplos de SDK

• Diagnostique erros da API e limites de requisições

• O que é Codex CLI

• Codex CLI, Codex App ou Codex Web

• Guia de configuração de config.toml no Codex

• O que são model_provider, base_url e wire_api

• O que significam review_model e reasoning_effort

• O que é AGENTS.md e como escrever esse arquivo

• O que são os modos sandbox e approval do Codex CLI

• Como manter o login oficial do Codex com uma API de terceiros

• API compatível com OpenAI ou API compatível com Anthropic

• Claude Code ou Codex CLI

• Gerenciar o provedor do Codex com o CC Switch

• Compare as ferramentas compatíveis

Referência oficial

• Referência de configuração do Codex
• Referência oficial de autenticação

Detalhes técnicos

Protocolo Responses

O Codex usa OpenAI Responses. Defina base_url como https://bettertoken.ai/v1 e mantenha wire_api = "responses". O Codex acrescenta /responses.