Como usar o Codex — da instalação ao uso com chave de API sem assinatura, incluindo o custo real de uma tarefa

Codex é o agente de programação da OpenAI. Para começar, instale o Codex CLI, que roda no terminal (npm install -g @openai/codex), execute codex no repositório em que trabalhará e faça seu pedido em coreano. Há duas formas de começar: entrar com um plano ChatGPT (Plus · Pro · Business etc.) e usar dentro do limite de uso, ou executá-lo com uma chave de API e pagar apenas pelos tokens usados. Como quase todos os artigos sobre o uso na Coreia tratam apenas da primeira opção, este artigo organiza a segunda — como executar o Codex CLI sem assinatura, como escolher o modelo para cada tarefa e o custo real de uma tarefa — em ordem. Os limites por plano e as opções quando você esgota o limite estão reunidos separadamente em Limites de uso do Codex.

O Codex não é uma ferramenta para colar código na janela de chat; é um agente que lê e altera arquivos no repositório, executa testes e comandos. Depois da execução, você pode definir o que confiar a ele sem confirmação com /permissions.

Duas formas de usar o Codex

Com uma chave de API, a cobrança é calculada separadamente do uso do plano ChatGPT. Você pode usar diretamente uma chave da API da OpenAI, mas este artigo aborda como conectar-se a um endpoint compatível com a Responses API. Com a mesma chave, você pode alternar entre modelos de GPT-6 Astra a GPT-5.6 Terra; por exemplo, GPT-5.6 Sol custa $2,00 / $12,00 por 1M de tokens, em comparação com o preço oficial da OpenAI de $5,00 / $30,00. (a OpenAI oferece atualmente pelo preço promocional de $4,00 / $20,00, mantido pelo menos até 21 de novembro de 2026, segundo a página de preços) (As tarifas são lidas diretamente do catálogo.)

Instalação do Codex — npm ou Homebrew

# npm (Node.js만 있으면 macOS / Linux / Windows 공통)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

Ambos os métodos de instalação estão no README oficial da OpenAI. No Windows, a instalação também é feita com o comando npm. Depois da instalação, digite codex no diretório do repositório em que trabalhará para executá-lo. Se você for entrar com o ChatGPT, pode parar aqui; a configuração abaixo não é necessária.

Emissão e configuração da chave da API do Codex — um bloco no config.toml

Primeiro, faça cadastro, recarregue a partir de $10 e crie uma chave na tela de chaves da API. A chave é exibida apenas uma vez, portanto salve-a imediatamente. Depois, adicione um bloco de provedor ao arquivo de configuração do Codex.

# ~/.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"        # 유일하게 유효한 값. 생략해도 같습니다

O ponto em que mais ocorrem erros é env_key. O que deve ser escrito ali é o nome da variável de ambiente que conterá a chave, não a própria chave. Como a chave não entra no arquivo de configuração, config.toml pode ser versionado ou colado com segurança em uma pergunta.

# env_key에 적은 이름의 변수에 키를 넣습니다 (키는 sk-kn-으로 시작)
export KUNAVO_API_KEY="sk-kn-..."

# 매번 export하지 않도록, 쓰는 셸의 설정 파일에 추가해 둡니다
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

No Windows PowerShell, execute setx KUNAVO_API_KEY sk-kn-... e abra um novo terminal. A localização do arquivo de configuração é %USERPROFILE%\.codex\config.toml. Antes de executar o Codex, verificar a chave e o endpoint com uma solicitação facilita separar os problemas.

# 코덱스를 의심하기 전에, 키와 엔드포인트만 요청 한 번으로 확인합니다
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": "OK라고만 답해줘"}'

Se retornar JSON, a chave e o endpoint estão normais; o problema restante está no lado de config.toml. Os itens de configuração estão na documentação de integração do Codex CLI (em inglês); para uma explicação que também cobre como chamar modelos Claude no Codex, consulte o guia de chave de API do Codex CLI (em inglês).

Primeira tarefa

# 1. 작업할 저장소로 들어가 실행합니다
cd ~/work/my-app
codex

# 2. AGENTS.md 초안을 만들게 합니다 (테스트 실행법이나 규칙을 적는 파일)
> /init

# 3. 이후엔 한국어로 요청합니다. 파일 경로를 붙일수록 빠르고 싸게 끝납니다
> src/utils/date.test.ts가 실패해. 원인을 찾아서 고치고 테스트가 통과하는지 확인해줘

O AGENTS.md criado por /init é um arquivo que registra “regras que não podem ser descobertas apenas lendo o código”, como como executar testes, quais bibliotecas usar e quais caminhos não devem ser alterados, e que será lido automaticamente nas sessões seguintes. O conteúdo gerado é um rascunho; refine-o manualmente.

As dicas para fazer solicitações são iguais às do Claude Code: inclua o caminho do arquivo e não entregue uma tarefa grande de uma só vez. Isso reduz os tokens usados na exploração, tornando o resultado mais rápido e preciso e diminuindo a cobrança. As práticas operacionais do Claude Code estão reunidas em Como usar o Claude Code.

Escolha o modelo para cada tarefa — custo real de uma tarefa

A maior vantagem de usar uma chave de API é poder escolher o modelo de acordo com o peso da tarefa. model é apenas o nome do modelo no endpoint, portanto alterá-lo não exige uma nova chave nem configuração adicional.

# config.toml의 기본값(gpt-5-6-sol)은 그대로 두고, 이번 실행만 모델을 바꿉니다
codex -m gpt-6-astra     # 원인을 모르는 버그, 여러 모듈에 걸친 변경
codex -m gpt-5-6-terra   # 정형화된 수정, 일괄 치환, 로그 요약 같은 가벼운 작업

“Uma tarefa” é um cálculo que considera como 20 etapas corrigir um teste que falha. Uma etapa consiste em 25.000 tokens de entrada (prompt do sistema + histórico da conversa + arquivos lidos) e 1.200 tokens de saída (uma alteração ou explicação), portanto uma tarefa usa 500.000 tokens de entrada e 24.000 de saída. Se for GPT-5.6 Sol, será $1,29, pagar os mesmos tokens diretamente à OpenAI custa atualmente $2,48 com o preço promocional (com o preço oficial, $3,22). Modelos mais baratos podem aumentar as idas e voltas porque precisam corrigir e corrigir novamente; na prática, se não terminar de uma vez, suba um nível. Para inserir diretamente sua própria quantidade de tokens, use a calculadora de custos.

Este cálculo não considera o cache. O Codex reenvia o histórico da conversa a cada etapa; portanto, entradas armazenadas em cache são cobradas a 0,10 vez o preço de entrada (para GPT-5.6 Sol, $0,20 por 1M de tokens), enquanto a parte gravada no cache pela primeira vez custa 1,25 vez o preço de entrada. Além disso, para a família GPT-5.6 e o GPT-6 Astra, se o prompt de uma solicitação exceder 272K tokens, toda a solicitação será cobrada a 2 vezes a tarifa de entrada e 1,5 vez a tarifa de saída. Não concentre tarefas demais em uma sessão; é mais seguro iniciar uma nova execução para cada tarefa. Tokens de raciocínio de modelos de raciocínio são cobrados como saída, portanto tarefas difíceis também aumentam a saída. Consulte o valor real em usage na resposta e no histórico de uso. As especificações do modelo estão na página do modelo GPT-5.6 Sol, as tarifas completas estão na tabela de preços e a tabela que compara lado a lado as tarifas por token dos modelos GPT usados pelo Codex está em Preços da API GPT.

Erros frequentes

Sinceramente — quando o plano ChatGPT é melhor

Se você trabalha com o Codex por várias horas todos os dias, um plano fixo geralmente sai mais barato. A cobrança conforme o uso é diretamente proporcional à quantidade de tokens, portanto quanto maior e mais constante o uso, maior a vantagem do plano fixo. O critério é “tarifa mensal ÷ custo de uma tarefa”, e o ponto de equilíbrio em relação ao plano foi calculado em Preços do Codex.

Há mais duas coisas a saber. Segundo a documentação da OpenAI, recursos que dependem do workspace do ChatGPT ou da nuvem são limitados ou indisponíveis quando usados com uma chave de API. Além disso, o caminho da Kunavo usa capacidade compartilhada, sem cota dedicada nem SLA contratual. Se você precisa de limite garantido ou SLA, é melhor contratar diretamente com a OpenAI.

Por outro lado, a chave de API é adequada para quem tem grande diferença entre os dias em que usa e os dias em que não usa, quer escolher o modelo para cada tarefa, quer dividir limites e histórico de uso por chave na equipe ou quer continuar trabalhando apenas nos dias em que o limite do plano se esgotou. As duas opções podem ser usadas juntas. Remova a linha model_provider de config.toml para voltar ao login do ChatGPT; se quiser alternar a cada execução, use o --profile do Codex.

A recarga da Kunavo pode ser feita com cartões, Apple Pay, Google Pay etc.; quando a tela de pagamento é exibida em won, KakaoPay, Naver Pay, PAYCO, Samsung Pay e cartões domésticos (incluindo cartões sem pagamentos internacionais habilitados) também aparecem. O Toss não é aceito. O saldo não expira e requisições com falha não são cobradas. Se você estiver em dúvida entre Codex e Claude Code, consulte Codex vs Claude Code.

Perguntas frequentes