Chave de API da CLI do Codex — configuração funcional de provedor personalizado

Uma chave de API do Codex é qualquer chave que o Codex CLI possa usar para cobrar por token em vez de um plano ChatGPT: uma chave de API da OpenAI obtida em platform.openai.com ou uma chave de provedor, como a sk-kn- da Kunavo, que o Codex lê da variável de ambiente indicada por env_key em um bloco model_providers. O provedor precisa disponibilizar a API Responses — esse é o único requisito abaixo.

Codex CLI é o agente de programação de terminal de código aberto da OpenAI, e pode ser executado com login no ChatGPT ou com uma chave de API. A opção com chave de API é a que vale a pena entender: ela cobra por token, sem taxa mensal, e é a única que permite apontar o CLI para outro provedor — ou para uma família de modelos completamente diferente. Este guia apresenta a configuração funcional, o único requisito que causa problemas na maioria dos gateways e quanto uma sessão realmente custa.

O único requisito importante

O Codex CLI é mais rigoroso com endpoints personalizados do que a maioria das ferramentas. Seu bloco model_providers tem uma chave wire_api e aceita exatamente um valor: responses. Isso significa que um provedor personalizado precisa disponibilizar a API Responses da OpenAI em POST /v1/responses — não o muito mais comum /v1/chat/completions. A maioria dos gateways compatíveis com a OpenAI oferece apenas este último, e é por isso que tantos deles não conseguem operar o Codex CLI, independentemente do base_url que você forneça.

A Kunavo disponibiliza ambas as superfícies, portanto a configuração abaixo funciona como está escrita.

A configuração

O Codex lê ~/.codex/config.toml. Duas chaves de nível superior selecionam o modelo e o provedor; o bloco do provedor descreve como acessá-lo:

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

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

Observe o que não está nesse arquivo: a própria chave. env_key indica uma variável de ambiente, e o Codex lê a chave dali ao ser iniciado; assim, o arquivo de configuração permanece seguro para ser versionado ou compartilhado.

# Codex reads the key from the variable named by env_key.
export KUNAVO_API_KEY="sk-kn-..."     # create at kunavo.com/app/keys

# Persist it (pick the file your shell actually loads):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explain the structure of this repository"

Crie a chave no painel depois de se cadastrar e adicionar US$ 10. Ela é exibida uma única vez, portanto armazene-a imediatamente. Se codex já estiver em execução em outro shell, reinicie-o — ele lê a variável ao ser iniciado, não a cada solicitação.

Verifique antes de depurar

Se algo estiver errado, descubra se o problema está na chave, no endpoint ou no CLI. Uma solicitação resolve a questão:

# Confirm the key and the endpoint before blaming Codex.
curl https://api.kunavo.com/v1/responses \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-sol",
    "input": "Say OK and nothing else."
  }'

Uma resposta JSON significa que a chave e o endpoint estão corretos, e que qualquer problema restante está em config.toml. Um 401 significa que a chave está errada ou que a variável está vazia neste shell. Um 404 em model significa que o slug não corresponde ao catálogo.

Qual modelo definir

O valor de model é apenas um slug no mesmo endpoint, portanto trocar de modelo exige editar uma palavra — sem nova chave e sem novo bloco de provedor.

gpt-5-6-sol é o GPT ajustado para programação e o padrão natural para este CLI, a $2,00 / $12,00 por 1 milhão de tokens, em comparação com o preço de tabela da OpenAI de $5,00 / $30,00 — embora a OpenAI atualmente cobre o preço promocional de $4,00 / $20,00, disponível pelo menos até 21 de novembro de 2026. As tarifas completas de todos os modelos estão na página de preços.

Executando modelos Claude no Codex CLI

Isso surpreende as pessoas: o Codex CLI é vinculado ao protocolo, não ao modelo. Ele usa o formato de comunicação Responses, e qualquer modelo de chat por trás desse endpoint responde. Aponte-o para claude-opus-5 e ele funcionará de ponta a ponta — incluindo chamadas de ferramentas, portanto o agente continuará lendo arquivos, propondo edições e executando comandos normalmente.

# Same provider block, different model — no new key, no new config.
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 solicitação Responses para a API Messages da Anthropic e traduz a resposta de volta para o formato Responses. Uma ressalva importante: o Codex envia itens reasoning opacos que somente um modelo nativo de Responses consegue consumir, e esses itens são descartados a caminho de um upstream que não seja GPT. O modelo perde seu bloco de rascunho privado da rodada anterior; o histórico visível com que ele trabalha permanece intacto. Na prática, isso reduz um pouco a continuidade em cadeias longas de raciocínio e não causa nenhum impacto em ciclos comuns de editar-executar-corrigir.

Se isso é uma boa ideia é uma questão separada de saber se funciona. Se você quer especificamente o Claude, o Claude Code foi criado para ele e repassa cache_control sem tradução. Mas, se prefere o sandbox do Codex CLI e quer usar Claude por trás dele, essa combinação está disponível.

Quanto custa uma sessão

CLIs agênticos reenviam o prompt do sistema, o histórico da tarefa e o contexto atualizado dos arquivos a cada etapa, portanto os tokens se acumulam mais rapidamente do que a contagem de etapas sugere. Uma etapa típica tem aproximadamente 25.000 tokens de entrada e 1.200 de saída:

Como as tarifas de saída diferem entre famílias de modelos muito mais do que as tarifas de entrada, trabalhos com muita saída alteram a classificação — use seus próprios números na calculadora de custos em vez de confiar em um único exemplo calculado. Solicitações malsucedidas não são cobradas.

Quando a opção com chave de API supera uma assinatura

Um plano ChatGPT inclui o uso do Codex por uma tarifa mensal fixa; uma chave de API cobra apenas pelo que você executar. A opção com chave vence quando você programa em períodos concentrados em vez de diariamente, quando quer limites de gastos por chave e visibilidade do uso em vez de uma franquia opaca, ou quando deseja um modelo que a assinatura não oferece. Ela perde quando você é um usuário intenso do dia a dia — nesse volume, uma tarifa fixa é difícil de superar. As opções não são exclusivas: os perfis do Codex permitem manter ambas e alternar por tarefa.

Solução de problemas

Perguntas frequentes