Codex CLI: Uma Introdução Prática

Anteriormente, apresentamos o Claude Code. Este capítulo aborda outra ferramenta de codificação com IA no terminal igualmente poderosa: Codex CLI.

Nota: O Codex também possui uma versão para desktop (interface gráfica), que será abordada em um capítulo posterior. Este capítulo foca no Codex CLI baseado em terminal.

O Codex CLI baseado em terminal, assim como o Claude Code, é um assistente de codificação com IA que roda no terminal. Se você já aprendeu o Claude Code no capítulo anterior, achará o Codex CLI muito fácil de pegar, pois a lógica operacional é quase idêntica.

O que é o Codex CLI?

Introdução em uma frase

Codex CLI = Assistente de codificação com IA no terminal da OpenAI

Semelhante ao Claude Code, é uma ferramenta de IA que roda no terminal. Você diz o que deseja em linguagem natural, e ela pode ajudá-lo a:

• Criar novos projetos
• Escrever código
• Modificar código
• Corrigir bugs
• Executar comandos
• Pesquisar na web por informações atualizadas

Qual a diferença entre Codex CLI e Claude Code?

Diferença central: modelos subjacentes diferentes. O Claude Code usa modelos Claude, o Codex CLI usa o modelo GPT-5-Codex da OpenAI otimizado para programação. Ambas as ferramentas têm seus pontos fortes. Recomenda-se instalar ambas e escolher com base na tarefa.

Como instalar o Codex CLI?

Pré-requisitos

1. Node.js: Assim como o Claude Code, requer ambiente Node.js

   • Se você já possui (da instalação anterior do Claude Code), não precisa reinstalar
   • Caso contrário, acesse https://nodejs.org e baixe a versão LTS

2. Rede: Necessário acesso aos serviços da OpenAI (pode exigir um proxy)

Passos da instalação

Abra o terminal e execute:

npm install -g @openai/codex

Aguarde a conclusão.

Verifique a instalação:

codex --version

Se aparecer um número de versão (ex.: codex-cli 0.98.0), a instalação foi bem-sucedida.

Usuários de Mac também podem instalar via Homebrew:

brew install codex

Várias formas de usar

Assim como o Claude Code, o Codex CLI suporta múltiplas maneiras de acessar as capacidades de IA.

Método 1: Comprar assinatura do ChatGPT (mais simples)

O Codex CLI está incluído nos planos pagos do ChatGPT.

Tipos de assinatura suportados:

Configuração:

1. Após comprar a assinatura do ChatGPT, abra o terminal
2. Execute codex para iniciar
3. Siga as instruções para fazer login na sua conta ChatGPT (um navegador será aberto para autorização)
4. Após o login, você pode usar

Você também pode fazer login manualmente:

codex login

Método 2: Usar a chave da API OpenAI

Se você possui uma chave da API OpenAI, pode usá-la diretamente:

1. Defina a variável de ambiente:

export OPENAI_API_KEY="your API Key"

2. Em seguida, execute codex

Método 3: Usar API de terceiros (integração com modelos nacionais)

Esta é a parte que muitos usuários nacionais mais se importam!

Assim como o Claude Code, o Codex CLI também pode ser integrado com APIs de terceiros, como DeepSeek, Volcengine e outros modelos nacionais.

A configuração é feita modificando o arquivo ~/.codex/config.toml (detalhado na próxima seção).

Integração com modelos nacionais: Modificando o config.toml

Onde está o config.toml?

Caminho do arquivo de configuração: ~/.codex/config.toml

• Mac/Linux: /Users/seunome/.codex/config.toml
• Windows (WSL): ~/.codex/config.toml

Dica: Se esse arquivo não existir, execute codex uma vez primeiro; ele criará automaticamente a pasta .codex. Depois, você pode criar manualmente o arquivo config.toml.

Estrutura básica de configuração

A configuração do config.toml é dividida em várias partes principais:

# ===== Basic settings =====
model = "gpt-5.3-codex"              # Model to use
model_provider = "openai"             # Model provider (default openai)
approval_policy = "on-failure"        # Approval policy
sandbox_mode = "workspace-write"      # Sandbox mode

# ===== Custom model providers =====
[model_providers.custom_name]
name = "Display name"
base_url = "API URL"
env_key = "API_KEY environment variable name"
wire_api = "responses"

# ===== Profiles =====
[profiles.profile_name]
model_provider = "custom_name"
model = "model name"

Importante: wire_api deve usar “responses”

Esta é uma armadilha comum!

O Codex CLI suporta dois protocolos de API: "chat" (Chat Completions legado) e "responses" (nova API Responses).

A partir de fevereiro de 2026, a OpenAI descontinuou o protocolo "chat" e migrou completamente para "responses". Portanto, ao configurar modelos de terceiros, wire_api deve ser definido como "responses". Se seu provedor de API de terceiros não suportar o formato da API Responses, você não poderá integrá-lo diretamente com o Codex.

Felizmente, as principais plataformas de retransmissão de API (como OpenRouter, etc.) já suportam a API Responses.

Para discussão detalhada, consulte: https://github.com/openai/codex/discussions/7782

Prática: Integrando DeepSeek

Usando DeepSeek como exemplo, veja como configurar:

Passo 1: Edite o config.toml

# Default to DeepSeek
model_provider = "deepseek"
model = "deepseek-chat"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

Passo 2: Defina a variável de ambiente

Defina sua chave da API DeepSeek no terminal:

export DEEPSEEK_API_KEY="your DeepSeek API Key"

Para torná-la permanente, adicione a linha ao final do seu ~/.zshrc (Mac) ou ~/.bashrc (Linux):

echo 'export DEEPSEEK_API_KEY="your DeepSeek API Key"' >> ~/.zshrc
source ~/.zshrc

Passo 3: Inicie o Codex

codex

Agora o Codex usará o modelo DeepSeek.

Nota: Se a API oficial do DeepSeek ainda não suportar o formato da API Responses e causar falhas de conexão, você pode mudar para uma plataforma de retransmissão que suporte a API Responses (como OpenRouter) e alterar o base_url para o endereço da plataforma de retransmissão.

Prática: Integrando Volcengine (Doubao)

model_provider = "volcengine"
model = "doubao-pro-32k"

[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

Também é necessário definir a variável de ambiente:

export VOLCENGINE_API_KEY="your Volcengine API Key"

Usando perfis para alternar entre vários modelos

Se você configurou vários modelos, pode usar perfis para alternar rapidamente:

# Default to OpenAI
model_provider = "openai"
model = "gpt-5.3-codex"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

# Define Volcengine provider
[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

# DeepSeek profile
[profiles.ds]
model_provider = "deepseek"
model = "deepseek-chat"

# Volcengine profile
[profiles.volc]
model_provider = "volcengine"
model = "doubao-pro-32k"

Alternando durante o uso:

# Use default OpenAI
codex

# Use DeepSeek
codex --profile ds

# Use Volcengine
codex --profile volc

Isso permite que você alterne livremente entre diferentes modelos, muito conveniente!

Um método mais simples: OPENAI_BASE_URL

Se você apenas deseja usar temporariamente uma API de terceiros sem modificar o config.toml, pode definir diretamente as variáveis de ambiente:

export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your DeepSeek API Key"
codex

Este método é mais simples, mas se torna inválido após fechar o terminal.

Como usar o Codex CLI?

Inicialização básica

Assim como no Claude Code:

1. Abra o terminal
2. Use cd para navegar até a pasta do seu projeto
3. Digite codex e pressione Enter

cd /path/to/your/project
codex

O Codex iniciará uma interface de terminal em tela cheia, onde você pode começar a digitar seus requisitos.

Três modos de operação

O Codex CLI possui três modos que controlam seu “nível de autonomia”:

Iniciantes são aconselhados a usar o modo Suggest (padrão), para que possam ver o que o Codex está fazendo a cada passo.

Depois de se familiarizar, você pode usar o modo Full Auto:

codex --full-auto "Run tests and fix all failing cases"

Atribuição direta de tarefas (modo não interativo)

Você também pode adicionar uma descrição de tarefa diretamente após o comando:

codex "Create a Snake game for me"

Dessa forma, o Codex iniciará diretamente a execução da tarefa sem precisar entrar na interface interativa.

Retomar conversa anterior

Semelhante ao --resume do Claude Code, o Codex também suporta retomar sessões anteriores:

codex resume

Isso permite que você continue de onde parou.

Prática: Vamos fazer o Codex criar um jogo da cobrinha para nós

Passo 1: Crie a pasta do projeto

1. Crie uma nova pasta na área de trabalho, ex.: codex-demo
2. Abra esta pasta no terminal

Passo 2: Inicie o Codex

codex

Passo 3: Digite os requisitos

No Codex, digite:

Create a Snake game for me with the following requirements:

1. Features:
   - Classic Snake gameplay
   - Control snake movement with arrow keys
   - Snake grows longer when eating food, score increases
   - Game over when hitting wall or itself
   - Start and restart buttons

2. Interface:
   - Clean and beautiful, pixel style
   - Display current score and high score
   - Support dark theme

3. Technical requirements:
   - Use only HTML, CSS, JavaScript
   - All code in a single HTML file
   - Use Canvas for game rendering

Please create this HTML file directly.

Passo 4: Aguarde o Codex terminar

O Codex criará automaticamente o arquivo HTML e escreverá todo o código. Dependendo do modo escolhido:

• Modo Suggest: Ele pedirá confirmação a cada passo; você confirma antes de executar
• Modo Full Auto: Ele concluirá tudo diretamente

Passo 5: Abra o jogo

Clique duas vezes no arquivo HTML gerado para jogá-lo no seu navegador!

Codex CLI vs Claude Code: Como escolher?

Recomendo instalar ambos. Cada um tem seus pontos fortes:

Minha sugestão:

• Instale ambos, escolha o mais adequado com base na tarefa
• Projetos simples: Ambos são capazes, escolha qualquer um
• Projetos complexos: Tente um primeiro; se o resultado não for bom, mude para o outro
• Usuários de modelos nacionais: Ambos suportam integração com API de terceiros, configuração semelhante

A filosofia central permanece: Você não precisa saber programar, só precisa saber descrever requisitos.

Resumo

O que aprendemos hoje:

1. O que é Codex CLI: Assistente de codificação com IA no terminal da OpenAI, semelhante ao Claude Code
2. Como instalar: npm install -g @openai/codex, um comando
3. Como usar: Mesma lógica operacional do Claude Code, cd para o diretório do projeto e depois codex para iniciar
4. Integração com modelos nacionais: Modificar ~/.codex/config.toml, configurar model_providers
5. Três modos: Suggest (conservador), Auto Edit (moderado), Full Auto (totalmente automático)
6. Alternância de perfis: Configurar vários modelos, usar o parâmetro --profile para alternar livremente

Agora você tem duas ferramentas poderosas de codificação com IA: Claude Code e Codex CLI!