Codex CLI com chave de API — configuração, modelos e custo de sessão

O Codex CLI é o agente de código de terminal open source da OpenAI, e ele roda tanto com login do ChatGPT quanto com chave de API. A rota de chave é a que vale entender: cobra por token, sem mensalidade, e é a única que permite apontar a CLI para outro provedor — ou para outra família de modelos. Este guia traz a configuração que funciona, o requisito que derruba a maioria dos gateways, quanto custa uma sessão e como pagar do Brasil por Pix.

O único requisito que importa

O Codex CLI fala a Responses API da OpenAI, e só ela: o bloco model_providers aceita apenas wire_api = "responses". Um gateway que ofereça somente /v1/chat/completions simplesmente não pode ser configurado — é por isso que boa parte dos endpoints “compatíveis com OpenAI” falha aqui. A Kunavo serve POST /v1/responses junto com o endpoint de chat, então o bloco abaixo funciona sem adaptação.

A configuração

# ~/.codex/config.toml
model          = "gpt-5-3-codex"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

O env_key é o nome da variável de ambiente, não a chave: o Codex nunca grava a chave no arquivo de configuração.

# O Codex lê a chave da variável indicada em env_key.
export KUNAVO_API_KEY="sk-kn-..."     # crie em kunavo.com/app/keys

# Deixe persistente (escolha o arquivo que o seu shell realmente carrega):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explique a estrutura deste repositório"

Crie a chave no dashboard depois de se cadastrar e recarregar $10 — ela aparece uma única vez.

Pagar do Brasil — Pix, sem cartão internacional

Para o desenvolvedor brasileiro, o obstáculo raramente é o arquivo TOML: é o meio de pagamento. Cobrar a API da OpenAI diretamente exige cartão de crédito internacional habilitado para compras no exterior. Na Kunavo o checkout é processado pelo Stripe e o Pix aparece como forma de pagamento para quem paga do Brasil — valor em reais e compensação imediata. Cartões internacionais (Visa, Mastercard, American Express) e Apple Pay continuam disponíveis para quem preferir.

As tarifas por token são definidas em USD: no Pix o Stripe exibe a conversão em reais na hora do pagamento; no cartão, a conversão segue a taxa do emissor (confira IOF e tarifa de transação internacional no app do banco) — o passo a passo da recarga por Pix está no guia de como pagar a API com Pix. A carteira é pré-paga — recarga mínima de $10, sem assinatura e sem renovação automática, com saldo que nunca expira.

Qual modelo usar

O gpt-5-3-codex é o GPT ajustado para código e o padrão natural desta CLI, a $0.70 / $5.60 por 1M de tokens contra $1.75 / $14.00 na tabela da OpenAI. As tarifas completas estão na página de preços.

Rodar modelos Claude no Codex CLI

Isso costuma surpreender: o Codex CLI é preso ao protocolo, não ao modelo. Ele fala o formato Responses, e qualquer modelo de chat atrás desse endpoint responde. Aponte para claude-opus-5 e ele roda de ponta a ponta — inclusive as chamadas de ferramenta, então o agente continua lendo arquivos, propondo edições e rodando comandos.

# Mesmo bloco de provider, outro modelo — sem chave nova, sem config nova.
model          = "claude-opus-5"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

O gateway traduz a requisição Responses para a API nativa Anthropic Messages e a resposta de volta ao formato Responses. Uma ressalva honesta: o Codex envia itens reasoning opacos que só um modelo nativo de Responses consegue consumir, e eles são descartados no caminho para um upstream que não seja GPT. O modelo perde o rascunho privado do turno anterior; a transcrição visível de que ele parte continua intacta. Na prática isso custa um pouco de continuidade em cadeias longas de raciocínio, e nada nos laços comuns de editar-rodar-corrigir.

Se você quer Claude especificamente, o Claude Code foi feito para isso e passa cache_control sem tradução. Mas se prefere o sandbox do Codex CLI e quer Claude atrás dele, a combinação existe.

Quanto custa uma sessão

CLIs agentic reenviam o system prompt, o histórico da tarefa e o contexto dos arquivos a cada passo, então os tokens se acumulam mais rápido do que a contagem de passos sugere. Um passo típico tem cerca de 25.000 tokens de input e 1.200 de output:

Ou seja: uma recarga de $10 por Pix cobre cerca de 21 tarefas agentic de 20 passos. E requisições com falha não são cobradas — um 5xx no meio de uma sessão não vira linha na fatura.

Quando algo não funciona

Antes de culpar o Codex, prove que a chave e o endpoint respondem:

# Confirme a chave e o endpoint antes de culpar o Codex.
curl https://api.kunavo.com/v1/responses \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-3-codex",
    "input": "Responda OK e nada mais."
  }'

• 404 — o provedor não implementa /v1/responses, ou a base_url já inclui /responses. O Codex acrescenta o caminho sozinho: a base termina em /v1.
• 401 — a variável indicada em env_key está vazia no shell que abriu o Codex. Confira com echo $KUNAVO_API_KEY nesse mesmo terminal.
• 402 — saldo insuficiente: recarregue em billing (o Pix cai na hora).
• model_not_found — o slug do modelo não existe no catálogo; confira em /models.

Perguntas frequentes