Tutorial do Codex — instalar o Codex CLI, usar uma chave de API sem assinatura e quanto custa cada tarefa

O Codex é o agente de programação de IA (coding agent) da OpenAI. O uso mais básico é instalar o Codex CLI no terminal (npm install -g @openai/codex), executá-lo na pasta do projeto que você quer processar codex e dizer em chinês o que deseja fazer. Há duas formas de começar: entrar com um plano do ChatGPT (Plus, Pro, Business etc.) e usar a cota do plano; ou executar com uma chave de API e pagar conforme os tokens usados. Quase todos os tutoriais em chinês escrevem apenas sobre a primeira opção; este cobre a segunda — a configuração para executar o Codex CLI sem assinatura, a escolha do modelo por tarefa e quanto uma tarefa realmente custa.

O Codex não é uma ferramenta para colar código em uma janela de chat; é um agente que lê arquivos, altera arquivos, executa testes e roda comandos no projeto. Configure quais ações podem ser realizadas diretamente, sem confirmação, após a inicialização usando /permissions.

Duas formas de usar o Codex

Ao usar uma chave de API, os custos são calculados separadamente da cota do plano do ChatGPT. Você também pode usar diretamente uma chave de API da OpenAI, mas este artigo trata da conexão a um endpoint compatível com a Responses API: a mesma chave pode alternar entre GPT-6 Astra e GPT-5.6 Terra. Por exemplo, o preço oficial da OpenAI para GPT-5.6 Sol é $5,00 / $30,00(a OpenAI atualmente oferece pelo preço promocional de $4,00 / $20,00, mantido pelo menos até 21 de novembro de 2026, segundo a página oficial de preços), enquanto aqui é de $2,00 / $12,00 por 1M de tokens (a tarifa é lida diretamente do catálogo deste site, não digitada manualmente).

Instalar o Codex CLI — npm ou Homebrew

# npm（有 Node.js 就能用，macOS / Linux / Windows 通用）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

Ambas são formas de instalação oficiais no README da OpenAI; no Windows, a mesma linha de comando do npm também funciona. Depois de instalar, digite codex na pasta do projeto para iniciar. Se pretende entrar com o ChatGPT, está tudo pronto; você pode ignorar as configurações abaixo.

Executar com uma chave de API — adicionar um bloco ao config.toml

Primeiro, crie uma conta, adicione no mínimo $10 e depois acesse a página de chaves de API para criar uma chave. A chave será exibida apenas uma vez; 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 em que é mais fácil errar é env_key: aqui você informa o nome da variável de ambiente que armazena a chave, não a chave em si. A chave não aparecerá no arquivo de configuração, portanto você pode enviar config.toml ao git ou publicá-lo em um fórum para pedir ajuda.

# 把金鑰放進 env_key 指定名稱的變數（金鑰以 sk-kn- 開頭）
export KUNAVO_API_KEY="sk-kn-..."

# 寫進 shell 的設定檔，就不必每次都 export
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

No PowerShell do Windows, execute setx KUNAVO_API_KEY sk-kn-... e abra outro terminal; o arquivo de configuração fica em %USERPROFILE%\.codex\config.toml. Antes de iniciar o Codex, faça uma solicitação para confirmar que a chave e o endpoint estão corretos; assim, será mais fácil identificar a origem de um erro depois.

# 懷疑 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": "只回 OK"}'

Se retornar JSON, a chave e o endpoint estão funcionando; o problema restante está em config.toml. As descrições de cada campo de configuração estão na documentação de integração do Codex CLI (em inglês), e o método para chamar modelos Claude no Codex está no guia de chaves de API do Codex CLI (em inglês).

Primeira tarefa

# 1. 進到要處理的專案資料夾，啟動 Codex
cd ~/work/my-app
codex

# 2. 讓它產生 AGENTS.md 草稿（寫測試怎麼跑、專案規則的檔案）
> /init

# 3. 之後直接用中文交代。附上檔名，做得更快也更省
> src/utils/date.test.ts 一直失敗，找出原因修好，並確認測試通過

O /init gera um AGENTS.md usado para registrar “regras que não são visíveis apenas lendo o código” — como executar testes, quais bibliotecas usar e quais caminhos não modificar — que será carregado automaticamente em todas as sessões futuras. O conteúdo gerado é apenas um rascunho; revise-o e faça suas próprias alterações.

A dica para dar instruções é a mesma do Claude Code: inclua nomes de arquivos e caminhos e não envie tarefas grandes de uma só vez. Isso reduz os tokens gastos na exploração, deixa o resultado mais rápido e preciso e também diminui a conta.

Escolha o modelo conforme a tarefa — o custo real de uma tarefa

A maior vantagem de usar uma chave de API é poder escolher o modelo conforme a complexidade do trabalho. model é apenas o nome do modelo no endpoint; trocar de modelo não exige uma nova chave nem configuração adicional.

# config.toml 的預設（gpt-5-6-sol）不動，只有這次啟動換模型
codex -m gpt-6-astra     # 找不到原因的 bug、跨模組的修改
codex -m gpt-5-6-terra   # 例行修改、大量取代、整理日誌這類輕量工作

O cálculo de “uma tarefa” considera corrigir um teste com falha como 20 etapas. 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 alteração ou explicação), portanto uma tarefa equivale a 500.000 tokens de entrada e 24.000 de saída. Com GPT-5.6 Sol, custa aproximadamente $1,29; pela mesma quantidade de tokens paga diretamente à OpenAI, o preço promocional atual é $2,48 (o preço de tabela é $3,22). Modelos mais baratos podem exigir mais ciclos até acertar, portanto, na prática, se não resolver de uma vez, suba um nível.

Esse cálculo não inclui o cache. O Codex reenvia o histórico da conversa a cada etapa; as entradas atendidas pelo cache custam 0,10 vez o preço de entrada (GPT-5.6 Sol custa $0,20 por 1M de tokens), enquanto a parte recém-gravada no cache custa 1,25 vez o preço de entrada. Além disso, na série GPT-5.6 e no GPT-6 Astra, quando o prompt de uma solicitação excede 272K tokens, a solicitação inteira é cobrada a 2 vezes o preço de entrada e 1,5 vez o de saída; portanto, não coloque trabalho demais na mesma sessão — é mais seguro reiniciar uma vez por tarefa. Os tokens de raciocínio dos modelos de raciocínio são cobrados à tarifa de saída; quanto mais difícil o problema, maior a saída. Para ver o valor real, consulte usage e o registro de uso na resposta. As especificações estão na página do modelo GPT-5.6 Sol, e as tarifas de todos os modelos estão na tabela de preços.

Erros comuns

Falando com franqueza — quando o plano do ChatGPT compensa mais

Se você passa várias horas por dia conversando com o Codex, um plano mensal fixo geralmente é mais barato. A cobrança por uso é proporcional aos tokens consumidos; quanto maior e mais estável o uso, maior a vantagem da mensalidade. O ponto de equilíbrio é “mensalidade ÷ preço de uma tarefa”; o ponto de equilíbrio entre os planos já foi calculado na página de custos do Codex.

Há mais duas coisas que você precisa saber. Segundo a documentação da OpenAI, recursos que dependem do workspace do ChatGPT ou de serviços em nuvem ficam limitados ou indisponíveis ao usar uma chave de API. Além disso, este caminho da Kunavo usa capacidade compartilhada, sem cota dedicada nem SLA garantido por contrato; se você precisa de cota ou SLA garantidos, é mais adequado contratar diretamente com a OpenAI.

Por outro lado, a chave de API é adequada para quem tem uso variável, quer escolher o modelo conforme a tarefa, precisa separar limites e registros de uso por chave na equipe ou quer continuar trabalhando depois de esgotar a cota do plano. É possível usar os dois: remova a linha config.toml de model_provider para voltar ao login do ChatGPT; para alternar a cada inicialização, use --profile do Codex.

Pague com um cartão de crédito internacional (incluindo JCB), Apple Pay ou Google Pay; Taiwan não possui meios de pagamento locais — JKoPay e LINE Pay não estão na lista de opções disponíveis. No modelo pré-pago, o cartão é cobrado apenas uma vez no momento da recarga, o saldo não expira e solicitações com falha não são cobradas. Se ainda estiver em dúvida entre Codex e Claude Code, consulte Claude Code vs Codex CLI (em inglês); para saber como o Claude Code é cobrado, veja Custos do Claude Code.

Perguntas frequentes