Codex CLI with an API Key — Setup, Models, and Session Cost

Codex CLI is OpenAI's open-source terminal coding agent, and it works with either ChatGPT sign-in or an API key. The API key route is the one to understand: it charges per token, has no monthly fee, and is the only route that lets you point the CLI to another provider—or another model family. This guide covers a working configuration, the requirement that rules out most gateways, what a session costs, and how to pay by Pix from Brazil.

The only requirement that matters

Codex CLI speaks only OpenAI's Responses API: the model_providers block accepts only wire_api = "responses". A gateway that offers only /v1/chat/completions simply cannot be configured—which is why many “OpenAI-compatible” endpoints fail here. Kunavo serves POST /v1/responses alongside the chat endpoint, so the configuration block below works without modification.

The configuration

# ~/.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"

env_key is the name of the environment variable, not the key: Codex never writes the key to the configuration file.

# 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"

Create the key in the dashboard after you sign up and add $10—it is shown only once.

Paying from Brazil — Pix, no international card

For Brazilian developers, the obstacle is rarely the TOML file; it is the payment method. Paying the OpenAI API directly requires an international credit card enabled for overseas purchases. At Kunavo, checkout is processed by Stripe, and Pix appears as a payment method for those paying from Brazil—the amount is shown in reais and settlement is immediate. International cards (Visa, Mastercard, American Express), Apple Pay, and Google Pay remain available for those who prefer them.

Token rates are set in USD: for Pix, Stripe displays the conversion to reais at checkout; for cards, conversion follows the issuer’s rate (check the IOF tax and international transaction fee in your banking app) — the step-by-step Pix top-up instructions are in the guide to paying for the API with Pix. The wallet is prepaid — minimum top-up of $10, no subscription or automatic renewal, and a balance that never expires.

Which model to use

gpt-5-6-sol is the GPT model tuned for code and the natural default for this CLI, at $2.00 / $12.00 per 1M tokens versus $5.00 / $30.00 at OpenAI's list price — OpenAI currently charges the promotional price of $4.00 / $20.00, available at least until November 21, 2026 according to the pricing page. Full rates are on the pricing page.

Run Claude models in Codex CLI

This often comes as a surprise: Codex CLI is protocol-bound, not model-bound. It speaks the Responses format, and any chat model behind that endpoint can respond. Point it at claude-opus-5 and it runs end to end — including tool calls, so the agent can still read files, propose edits, and run commands.

# 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"

The gateway translates the Responses request into the native Anthropic Messages API and translates the response back into Responses format. One honest caveat: Codex sends opaque reasoning items that only a native Responses model can consume, and they are discarded when routed to a non-GPT upstream. The model loses the private draft from the previous turn; the visible transcript it continues from remains intact. In practice, this costs a little continuity in long reasoning chains, and nothing in the usual edit-run-fix loops.

If you specifically want Claude, Claude Code was built for that and passes cache_control through without translation. But if you prefer the Codex CLI sandbox and want Claude behind it, that combination is possible.

What a session costs

Agentic CLIs resend the system prompt, task history, and file context at every step, so tokens add up faster than the step count suggests. A typical step has about 25,000 input tokens and 1,200 output tokens:

In other words: a $10 Pix top-up covers about 8 20-step agentic tasks. And failed requests aren’t charged — a 5xx in the middle of a session doesn’t show up as a billing line item.

When something doesn’t work

Before blaming Codex, verify that the key and endpoint respond:

# 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-6-sol",
    "input": "Responda OK e nada mais."
  }'

• 404 — the provider doesn’t implement /v1/responses, or base_url already includes /responses. Codex adds the path automatically: the base should end in /v1.
• 401 — the variable specified in env_key is empty in the shell that launched Codex. Check it with echo $KUNAVO_API_KEY in that same terminal.
• 402 — insufficient balance: top up at billing (Pix is credited immediately).
• model_not_found — the model slug doesn’t exist in the catalog; check /models.

Frequently asked questions