Como usar o Codex — da instalação ao uso com uma chave de API sem assinatura

Codex é o agente de programação da OpenAI. O uso básico consiste em instalar o Codex CLI, que funciona no terminal (npm install -g @openai/codex), iniciar codex no repositório em que deseja trabalhar e fazer solicitações em japonês. Há duas formas de começar. Você pode entrar com um plano do ChatGPT (Plus, Pro, Business etc.) e usar a franquia incluída, ou usar uma chave de API e pagar apenas pelos tokens consumidos. Como os artigos explicativos em japonês abordam quase exclusivamente a primeira opção, esta página explica a segunda — a configuração para executar o Codex CLI sem assinatura, como escolher o modelo por tarefa e o custo real de uma tarefa — nessa ordem.

O Codex não é uma ferramenta para colar código na tela de chat: ele lê e modifica arquivos no repositório e executa testes e comandos. Você decide até onde deixá-lo agir sem confirmação usando /permissions depois de iniciá-lo.

Duas formas de usar o Codex

Ao usar uma chave de API, a cobrança é contabilizada separadamente da franquia do plano da OpenAI. Você também pode usar diretamente uma chave de API da OpenAI, mas esta página aborda como direcionar o Codex para um endpoint compatível com a Responses API. É possível alternar entre modelos que vão do GPT-6 Astra ao GPT-5.6 Terra com a mesma chave; por exemplo, GPT-5.6 Sol custa $2,00 / $12,00 por 1M de tokens, em comparação com o preço de tabela da OpenAI de $5,00 / $30,00 (a OpenAI oferece atualmente pelo preço promocional de $4,00 / $20,00; segundo a página de preços, pelo menos até 21 de novembro de 2026) (as tarifas são carregadas diretamente do catálogo).

Instalação — npm ou Homebrew

# npm（Node.js が入っていれば macOS / Linux / Windows 共通）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

Ambos são métodos listados no README oficial da OpenAI. No Windows, o comando do npm também funciona. Depois da instalação, execute codex no diretório do repositório em que deseja trabalhar. Se você usar o login do ChatGPT, estará pronto aqui; nenhuma configuração adicional será necessária.

Executar com uma chave de API — 1 bloco em config.toml

Primeiro, crie uma conta, faça uma recarga a partir de $10 e crie a chave na página de chaves de API. A chave será exibida apenas uma vez, portanto salve-a imediatamente. Em seguida, 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 mais fácil de confundir aqui é env_key. Você deve escrever 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, é seguro deixar config.toml exatamente como está no commit ou colá-lo em uma pergunta.

# env_key で指定した名前の変数にキーを入れる（キーは sk-kn- で始まる）
export KUNAVO_API_KEY="sk-kn-..."

# 毎回 export しないよう、使っているシェルの設定ファイルに追記しておく
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

No PowerShell do Windows, execute setx KUNAVO_API_KEY sk-kn-... e depois abra um novo terminal. O arquivo de configuração fica em %USERPROFILE%\.codex\config.toml. Antes de iniciar o Codex, vale confirmar com uma única solicitação se a chave e o endpoint estão corretos; isso facilita a investigação posterior.

# Codex を疑う前に、キーとエンドポイントだけを 1 回で確かめる
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 for retornado JSON, a chave e o endpoint estão funcionando; se ainda houver um problema, ele está no lado do config.toml. Os detalhes das opções de configuração estão na documentação de integração do Codex CLI (em inglês); o guia que também explica como chamar modelos Claude pelo Codex está no guia de configuração de chaves de API do Codex CLI (em inglês).

Sua 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 “decisões que não ficam claras apenas lendo o código”, como como executar testes, quais bibliotecas usar e quais caminhos não devem ser tocados, e que é carregado automaticamente nas sessões seguintes. O conteúdo gerado é um rascunho; revise-o manualmente.

As dicas para fazer solicitações são as mesmas do Claude Code: inclua o nome e o caminho do arquivo e não envie uma solicitação grande de uma só vez. Como serão usados menos tokens na exploração, o resultado será mais rápido e preciso, e a cobrança diminuirá. A frequência dos diálogos de confirmação pode ser ajustada em /permissions. O uso do Claude Code está reunido em Como usar o Claude Code.

Escolha o modelo por tarefa — custo real de uma tarefa

A maior vantagem de usar uma chave de API é poder escolher o modelo de acordo com a complexidade do trabalho. model é apenas o nome do modelo no endpoint; não é necessário adicionar uma chave ou configuração para alternar.

# config.toml の既定（gpt-5-6-sol）はそのまま、この起動だけモデルを変える
codex -m gpt-6-astra     # 原因の見えないバグ、設計をまたぐ変更
codex -m gpt-5-6-terra   # 定型の修正、一括置換、ログの要約などの軽い作業

“Uma tarefa” é calculada considerando 20 etapas para corrigir um teste que está falhando. Cada etapa usa 25.000 tokens de entrada (prompt do sistema + histórico da conversa + arquivos lidos) e 1.200 tokens de saída (uma edição ou explicação); portanto, uma tarefa usa 500.000 tokens de entrada e 24.000 de saída. Com GPT-5.6 Sol, isso corresponde a $1,29; pagar a mesma quantidade de tokens diretamente à OpenAI custa atualmente $2,48 no preço promocional (ou $3,22 no preço de tabela). Modelos mais baratos podem exigir mais idas e vindas por retrabalho; na prática, se não terminar de uma vez, vale subir um nível.

Este cálculo não considera o cache. Como o Codex reenvia o histórico da conversa a cada etapa, a entrada armazenada em cache é cobrada a 0,10 vezes o preço da entrada (com GPT-5.6 Sol, $0,20 por 1M de tokens), enquanto a parte recém-gravada no cache é cobrada a 1,25 vezes o preço da entrada. Além disso, nos modelos da série GPT-5.6 e no GPT-6 Astra, se o prompt de uma solicitação exceder 272K tokens, toda a solicitação será cobrada com entrada a 2 vezes e saída a 1,5 vez. É mais seguro não concentrar trabalho demais em uma única sessão e reiniciar por tarefa. Os tokens de raciocínio dos modelos de raciocínio são cobrados como saída, portanto tarefas difíceis também aumentam a saída. Confira o custo real no campo usage da resposta e no histórico de uso. As especificações do modelo estão na página do modelo GPT-5.6 Sol, e os preços de todos os modelos estão na tabela de preços.

Erros comuns

Falando com franqueza — quando o plano do ChatGPT é mais vantajoso

Se você trabalha várias horas por dia conversando com o Codex, um plano fixo geralmente sai mais barato. A cobrança por uso é diretamente proporcional à quantidade de tokens; quanto maior e mais estável o uso, maior a vantagem do preço fixo. O ponto de equilíbrio é “mensalidade ÷ preço de uma tarefa”, e o ponto de equilíbrio com o plano é calculado em Preços do Codex.

Há mais dois pontos importantes. Segundo a documentação da OpenAI, recursos que dependem do workspace ou da nuvem do ChatGPT são limitados ou indisponíveis quando se usa uma chave de API. Além disso, a rota da Kunavo usa capacidade compartilhada e não oferece cota dedicada nem SLA contratual. Se você precisa de cota ou SLA garantidos, é mais apropriado contratar diretamente a OpenAI.

Por outro lado, uma chave de API é adequada para quem tem grande diferença entre os dias de uso e os dias sem uso, quer escolher o modelo por tarefa, quer separar limites e histórico de uso por chave em uma equipe ou quer continuar trabalhando apenas nos dias em que a franquia do plano acabou. As duas opções podem coexistir. Remova a linha model_provider de config.toml para voltar ao login do ChatGPT; se quiser alternar a cada inicialização, use --profile do Codex.

O pagamento pode ser feito com cartões (incluindo JCB), Apple Pay, Google Pay etc., e o saldo não expira. Pagamentos em lojas de conveniência e PayPay não são aceitos. Requests com falha não são cobradas. Se você estiver em dúvida entre usar Codex ou Claude Code, consulte Comparação entre Codex e Claude Code.

Perguntas frequentes