Codex CLI com um provedor personalizado: config.toml, modelos GPT e Claude, extensão para IDE e correções

O Codex lê um único arquivo, ~/.codex/config.toml, compartilhado pela CLI, codex exec e pela extensão para IDE. Um provedor personalizado nesse arquivo direciona o Codex para este gateway, onde a mesma configuração executa modelos GPT e Claude. As versões atuais do Codex usam apenas a Responses API (wire_api = "responses"), portanto, os guias antigos que usam wire_api = "chat" não funcionam mais.

Instalar o Codex

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or with a package manager
npm install -g @openai/codex
brew install --cask codex

codex --version

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

A extensão do Codex para VS Code, Cursor e Windsurf é instalada pela loja de extensões do editor e usa o mesmo ~/.codex/config.toml que a CLI, portanto, tudo abaixo se aplica a ambos.

Use uma chave do grupo correto

Uma chave do gateway pertence a um grupo, e esse grupo determina quais modelos a chave pode chamar. Para modelos GPT, crie a chave no grupo **Codex** no painel. Para modelos Claude, qualquer chave Claude com pagamento por uso funciona. Uma chave de um grupo Ilimitado exige um plano ativo; sem ele, todas as solicitações falham com No active subscription found for this group.

export AIPRIME_CODEX_KEY=key_from_the_codex_group    # GPT models
export AIPRIME_CLAUDE_KEY=key_from_a_claude_group    # Claude models

setx AIPRIME_CODEX_KEY "key_from_the_codex_group"
setx AIPRIME_CLAUDE_KEY "key_from_a_claude_group"
# open a new terminal afterwards

config.toml para modelos GPT

model_provider = "aiprime"
model = "gpt-6-astra"
model_reasoning_effort = "high"

[model_providers.aiprime]
name = "AI Prime Tech"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CODEX_KEY"
wire_api = "responses"
supports_websockets = false

Execute o Codex com modelos Claude

O gateway aceita solicitações da Responses API para modelos Claude e as traduz, permitindo que o Codex também use o Claude. Adicione um segundo provedor que use sua chave Claude e, depois, um perfil para alternar para ele.

[model_providers.aiprime_claude]
name = "AI Prime Tech (Claude)"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CLAUDE_KEY"
wire_api = "responses"
supports_websockets = false

model_provider = "aiprime_claude"
model = "claude-sonnet-5"
model_reasoning_effort = "high"

codex --profile claude
codex exec --profile claude "review the last commit for bugs"

Desde o Codex 0.134.0, cada perfil tem seu próprio arquivo, ~/.codex/<name>.config.toml, com suas chaves no nível superior; [profiles.<name>] as tabelas dentro de config.toml não são mais lidas. Perfis e provedores só podem ser definidos na sua configuração de usuário: o arquivo do projeto .codex/config.toml ignora model_provider e model_providers.

Modelos e esforço de raciocínio

model_reasoning_effort aceita low, medium, high, xhigh ou max, dependendo do modelo. Não defina none: esses modelos rejeitam esse valor com 'none' is not supported. review_model define um modelo diferente para /review se você quiser. O painel mostra todos os modelos que o grupo da sua chave pode chamar.

Extensão para IDE e codex exec

A extensão para IDE lê o mesmo config.toml, mas env_key é resolvido a partir do ambiente do próprio editor. Um editor iniciado pelo dock ou pelo menu Iniciar não vê as variáveis exportadas em .bashrc, e o Codex então falha com Invalid API key enquanto a CLI funciona. Defina a variável para todo o sistema (no Windows, setx faz isso) ou inicie o editor a partir de um terminal, por exemplo, code ..

codex exec executa uma tarefa sem a interface interativa, o que é adequado para scripts e CI. Usa a mesma configuração e os mesmos perfis:

codex exec "write unit tests for utils.py"
codex exec --profile claude "summarise the changes on this branch"
codex login status        # which authentication method is active

Novas tentativas e tempos limite

Cada provedor tem suas próprias configurações de novas tentativas e streaming. Os valores padrão são 4 novas tentativas de solicitação, 5 reconexões de streaming e um tempo limite de inatividade de 5 minutos por stream. Etapas longas de raciocínio podem ficar sem transmitir dados por algum tempo, então aumentar o tempo limite de inatividade ajuda em níveis altos de esforço.

[model_providers.aiprime]
# ...settings from above...
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000

Solução de problemas: erros encontrados por usuários do Codex

Os erros abaixo são os que os clientes Codex realmente produzem neste gateway, começando pelos mais comuns.

Está comparando o Codex com o Claude Code antes de escolher um deles? Veja Claude Code vs Codex.

Perguntas frequentes

AI Prime Tech é um gateway de API independente. Não tem afiliação com a Anthropic, não é endossado por ela e não é seu revendedor. Claude e os nomes dos modelos relacionados são marcas comerciais de seus respectivos proprietários.