Documentação

Codex CLI

O Codex aceita apenas a API Responses. Um único bloco de provedor em config.toml aponta para a interface nativa /v1/responses do Kunavo, com a chave armazenada em uma variável de ambiente, em vez de no arquivo.

Um bloco [model_providers.kunavo] em ~/.codex/config.toml com env_key, para que a chave permaneça no ambiente e nunca no arquivo de configuração.

~/.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"     # the NAME of the variable, not the key
# wire_api defaults to "responses", which is the only supported value

wire_api tem exatamente um valor válido agora: "responses", que é o padrão quando omitido. O suporte a Chat Completions foi removido do Codex, então qualquer guia antigo que recomende escrever wire_api = "chat" está desatualizado — e nenhum endpoint sem uma rota /v1/responses funcional pode ser usado pelo Codex. O Kunavo a implementa nativamente.

env_key contém o nome de uma variável de ambiente, não a própria chave. Isso é intencional por parte da OpenAI: config.toml é um arquivo que as pessoas versionam e colam em relatos de problemas.

Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de Codex CLI.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
Adicione o bloco acima a ~/.codex/config.toml, criando o arquivo se ele não existir.
Exporte a variável indicada por env_key: export KUNAVO_API_KEY=sk-kn-...
Execute codex. O campo model_provider no nível superior seleciona o bloco; model seleciona o ID dentro dele.
Para trocar de modelo por sessão, sem editar o arquivo, use codex -m <model id> ou mantenha vários blocos de provedor e altere model_provider.

Verificado em a referência do arquivo de configuração do Codex em 6 de setembro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Esta é a versão resumida. O guia completo — escolha do modelo, custo de uma sessão real e modos de falha — está em o guia de chaves de API do Codex CLI.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Codex CLI.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

ID do modelo	Entrada / saída da Kunavo	Onde se encaixa em Codex CLI
`gpt-5-6-sol`	$2.00 / $12.00	a combinação padrão do Codex — nativa de Responses, sem intermediários
`gpt-6-sol`	$0.80 / $4.00	O GPT-6 da OpenAI para tarefas complexas de programação e agentes — o mesmo caminho de Responses, com uma tarifa inferior à do 5.6 Sol
`gpt-6-luna`	$0.04 / $0.20	o GPT-6 mais barato, para operações de alto volume ou baixo esforço
`gpt-5-6-terra`	$0.70 / $4.20	uma opção mais barata da linha GPT para sessões com muitas edições
`claude-sonnet-5`	$1.40 / $7.00	um modelo que não é GPT pela API Responses — traduzido no gateway
`claude-opus-5`	$3.50 / $17.50	etapas de planejamento em que a profundidade de raciocínio justifica a tarifa

A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

Perguntas frequentes

Como direciono o Codex CLI para um endpoint de API personalizado?

Adicione uma tabela [model_providers.<id>] a ~/.codex/config.toml com name, base_url e env_key; em seguida, defina model_provider no nível superior com esse ID e model com o ID que você quer usar. base_url é a raiz /v1 do serviço; env_key indica o nome da variável de ambiente que contém a chave, para que ela nunca apareça no próprio arquivo.

Qual valor de wire_api o Codex CLI exige?

"responses" — a referência de configuração afirma que esse é o único valor compatível e o padrão quando omitido. O Codex removeu o suporte a Chat Completions, então um endpoint que implemente apenas /v1/chat/completions não pode ser usado pelo Codex, independentemente da configuração. O endpoint precisa disponibilizar uma rota /v1/responses funcional.

O Codex CLI consegue executar modelos Claude?

Sim, se o endpoint os disponibilizar pela API Responses. O Codex envia uma solicitação no formato Responses para a URL indicada por base_url e repassa o ID do modelo. Assim, um gateway que traduza Responses para o formato próprio do modelo pode disponibilizar IDs Claude ou Gemini ao Codex. O próprio Codex não sabe qual fornecedor responde.

Onde o Codex CLI armazena a chave de API?

Em uma variável de ambiente indicada pelo campo env_key do bloco de provedor, não em config.toml. O Codex lê a variável na inicialização, então a chave fica no perfil do shell ou no gerenciador de segredos, e o arquivo de configuração continua seguro para versionar e colar em um relatório de erro.