Como usar o Codex CLI: guia passo a passo

Para usar o Codex CLI, instale com um comando, rode codex dentro da pasta de um projeto, entre com sua conta do ChatGPT e descreva a mudança que você quer em linguagem natural. O Codex lê o código, edita arquivos e roda comandos dentro do projeto, e pergunta antes de sair da pasta ou acessar a rede.

Esse é o ciclo básico. Este guia cobre o resto: modos de aprovação e sandbox, um arquivo AGENTS.md, o config.toml, servidores MCP, os comandos que você vai usar todo dia, retomar sessões e alguns hábitos que deixam o Codex mais confiável. Tudo aqui segue a documentação oficial do Codex da OpenAI em outubro de 2026.

O que é o Codex CLI

O Codex CLI é o agente de código da OpenAI para o terminal. Ele roda localmente, trabalha na pasta de onde você o inicia e pode rodar seus testes, linters e o git. O mesmo Codex também existe como extensão de IDE, app desktop e versão na nuvem, e todos compartilham o seu login. Se você está escolhendo entre agentes, Claude Code vs Codex e Codex vs Gemini CLI comparam os dois em detalhes. Em resumo, o Codex é um agente de código, não um autocomplete: você dá uma tarefa, ele planeja e executa.

Passo 1: instale o Codex CLI

A OpenAI oferece um script de instalação para cada plataforma, e a CLI também está no npm e no Homebrew.

Para atualizar, rode o mesmo script de instalação de novo, rode codex update ou use o seu gerenciador de pacotes (brew upgrade --cask codex). Confira se funcionou:

codex --version

Passo 2: faça login

Entre em um projeto e inicie o Codex:

cd my-project
codex

Na primeira execução, o Codex pergunta como você quer entrar:

• Sign in with ChatGPT (entrar com o ChatGPT): usa o seu plano do ChatGPT. O uso conta nos limites do plano. É a escolha mais comum, e a única que também libera o Codex na nuvem.
• API key (chave de API): usa uma chave de API da OpenAI e é cobrada por token. Útil para CI ou quando você quer cobrança por uso.

Você também pode gerenciar isso pelo shell. codex login abre o login no navegador, codex login --device-auth dá um código de dispositivo para uma máquina remota ou sem interface gráfica, codex login status diz se você está logado e codex logout apaga as credenciais salvas. Para entrar com uma chave sem digitá-la, mande por pipe: printenv OPENAI_API_KEY | codex login --with-api-key.

No momento em que escrevo, o Codex está incluído no ChatGPT Free, Go, Plus, Pro, Business, Edu e Enterprise. Planos maiores dão limites maiores; confira a página de preços do Codex da OpenAI para os números atuais. Você vê onde está a qualquer momento com /status ou /usage dentro de uma sessão.

Passo 3: sua primeira tarefa

Comece com algo pequeno e real para ver como o Codex trabalha:

Explain how authentication works in this project, then add a test for
the password reset flow. Run the test suite when you're done.

O Codex lê os arquivos relevantes, diz o que planeja fazer, edita o código e roda os testes. Algumas coisas deixam isso mais fluido:

• Digite @ para buscar um arquivo e anexá-lo ao prompt.
• Comece uma linha com ! para rodar você mesmo um comando de shell, por exemplo !git status.
• Enquanto o Codex trabalha, aperte Enter para adicionar instruções ao turno atual, ou Tab para enfileirar uma mensagem para depois que ele terminar.
• Aperte Esc duas vezes com o campo vazio para editar a mensagem anterior e continuar dali.
• /diff mostra o que mudou, incluindo arquivos não rastreados.

Para capturas de tela ou mockups de design, anexe imagens com codex --image path/to/file.png ou cole no prompt.

Passo 4: modos de aprovação e sandbox

Vale entender esta parte antes de dar trabalhos maiores ao Codex. O Codex combina duas configurações: um sandbox que limita o que os comandos podem fazer tecnicamente, e uma política de aprovação que decide quando o Codex para e pergunta a você.

Dentro de uma sessão, /permissions alterna entre Auto e Read Only. O acesso à rede vem desligado no sandbox workspace-write; você pode ligá-lo no config.toml (veja abaixo) se os seus testes precisarem.

Se o Codex precisa escrever em uma segunda pasta, como uma biblioteca compartilhada ao lado do projeto, use --add-dir em vez de passar para acesso total. A OpenAI desaconselha explicitamente o --dangerously-bypass-approvals-and-sandbox (apelido --yolo) fora de uma VM dedicada e isolada.

O sandbox é um isolamento real no nível do sistema operacional: Seatbelt no macOS, bubblewrap com seccomp no Linux e um sandbox nativo no Windows. Dentro do WSL2, o Codex usa o sandbox do Linux. Para uma visão mais ampla do que pode dar errado com agentes e como limitar, veja segurança de agentes de código com IA.

Passo 5: escreva um AGENTS.md

O AGENTS.md é um arquivo Markdown de instruções que o Codex lê antes de começar a trabalhar. É onde você coloca o que repetiria em todo prompt: como fazer build e testar, estilo de código, pastas que não devem ser tocadas.

Rode /init em uma sessão e o Codex gera uma primeira versão para você. Um bom arquivo é curto e específico:

# AGENTS.md

## Commands
- Install: pnpm install
- Test: pnpm test (run before saying a task is done)
- Lint: pnpm lint

## Conventions
- TypeScript strict mode, no any.
- New API routes go in src/routes and need a test.

## Don't
- Don't edit files in src/generated.
- Don't add dependencies without asking.

O Codex procura esses arquivos em uma ordem definida:

1. Global: ~/.codex/AGENTS.md (ou AGENTS.override.md para substituí-lo temporariamente). Use para as suas preferências pessoais.
2. Projeto: da raiz do git até a pasta em que você está, o Codex pega no máximo um arquivo por diretório, checando primeiro AGENTS.override.md e depois AGENTS.md.

Os arquivos são juntados da raiz para baixo, então as instruções de uma subpasta vêm depois e prevalecem sobre as gerais. O tamanho combinado tem limite de 32 KiB por padrão (project_doc_max_bytes), mais um motivo para mantê-los enxutos. Como o AGENTS.md é um formato compartilhado, outros agentes também o leem; CLAUDE.md vs AGENTS.md explica como manter um só conjunto de regras para várias ferramentas.

Passo 6: config.toml

As configurações do Codex ficam em arquivos TOML:

• ~/.codex/config.toml para as suas configurações de usuário;
• .codex/config.toml dentro de um projeto, que o Codex só carrega depois que você marca o projeto como confiável.

Um exemplo pequeno:

model_reasoning_effort = "medium"
web_search = "cached"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true

model define o modelo padrão (rode /model em uma sessão para ver o que a sua conta oferece). model_reasoning_effort controla quanto tempo o modelo pensa. web_search pode ser cached (o padrão), live ou disabled; a flag --search liga a busca ao vivo em uma execução.

As configurações são aplicadas nesta ordem, da maior prioridade para a menor: flags de linha de comando e -c key=value, a configuração do projeto, um perfil nomeado escolhido com --profile, a configuração do usuário e, por fim, a configuração do sistema. Então codex -c model_reasoning_effort="high" muda o esforço em uma execução sem mexer nos seus arquivos. Se não tiver certeza de qual valor venceu, /debug-config mostra as camadas.

Passo 7: conecte servidores MCP

O MCP permite ao Codex usar ferramentas externas: busca em documentação, um navegador, o seu issue tracker, um banco de dados. Adicione um servidor com um comando:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Tudo depois de -- é o comando que inicia o servidor. Passe variáveis de ambiente com --env VAR=value. Para um servidor remoto, use codex mcp add <name> --url https://... e, se ele usa OAuth, entre com codex mcp login <name>. codex mcp list mostra o que está configurado.

Os mesmos servidores podem ser escritos à mão no config.toml:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Dentro de uma sessão, /mcp lista os servidores ativos e as ferramentas deles. Se a ideia é nova para você, o que é um servidor MCP é uma boa introdução. Mantenha a lista curta: cada servidor adiciona descrições de ferramentas à janela de contexto.

Passo 8: os comandos que vale conhecer

Os comandos de barra funcionam dentro de uma sessão:

E alguns subcomandos pelo shell:

O codex exec é o que vale lembrar para automação. Ele imprime o resultado e sai, aceita --json para saída legível por máquina e --output-last-message para salvar a resposta final em um arquivo. No CI, combine com um sandbox, por exemplo codex exec --sandbox workspace-write "fix the failing lint errors".

Passo 9: retome e ramifique sessões

O Codex guarda as conversas localmente, então fechar o terminal não faz você perder trabalho:

• codex resume abre um seletor de sessões anteriores.
• codex resume --last vai direto à mais recente da pasta atual; adicione --all para procurar em todas as pastas.
• codex fork (ou /fork em uma sessão) copia uma conversa para uma nova, para você tentar outra abordagem sem perder a original.
• Em execuções não interativas, codex exec resume --last continua a última sessão de exec.

Ramificar é útil quando o Codex já montou um bom contexto sobre um problema e você quer testar duas soluções a partir do mesmo ponto.

Dicas para resultados melhores

• Faça commit antes e depois. O próprio conselho da OpenAI é criar um checkpoint no git antes e depois de uma tarefa. Se uma mudança der errado, git restore é mais rápido do que discutir com o agente.
• Diga como verificar. “Rode pnpm test e corrija as falhas” dá resultados melhores do que “faça funcionar”.
• Planeje mudanças maiores. Use /plan para qualquer coisa que toque mais do que alguns arquivos, e leia o plano antes de o Codex começar a editar.
• Uma tarefa por conversa. Comece do zero com /new entre tarefas sem relação; contexto antigo custa tokens e confunde o modelo.
• Compacte sessões longas. /compact mantém as partes importantes e descarta o resto.
• Use um worktree para trabalho em paralelo. Dois agentes na mesma pasta sobrescrevem um ao outro. Git worktrees dão a cada um a sua própria cópia.

Quando um terminal não basta

Quando o Codex vira parte do seu dia, você vai querer mais de uma sessão rodando: uma corrigindo um bug, outra escrevendo testes, talvez uma segunda conta quando a primeira bater no limite. É aí que um único terminal fica desajeitado.

O AgentVera é um app desktop para macOS, Windows e Linux que roda o Codex (e outros agentes de CLI) em terminais de verdade, lado a lado. Ele usa o login do Codex que você já tem. Veja a página Codex no AgentVera para os detalhes.

• Workspace: uma grade de agentes por projeto, de 1×1 a 5×4. Escolha o modelo e o esforço por agente; a lista é lida ao vivo do Codex. Os agentes retomam a conversa depois de reabrir o app.
• Permissões por agente: escolha Ask, Auto ou Full access ao criar um agente, em vez de lembrar de flags.
• Worktrees: crie um worktree pelo painel Git e inicie um agente nele com um clique.
• Troca de conta: cada conta do Codex tem a própria pasta home, os limites restantes aparecem na barra de status e, no Pro e no Team, uma cadeia de contas passa para a próxima conta quando o limite de 5 horas ou o semanal acaba.
• Gerenciador de MCP: configure os servidores MCP uma vez; eles se conectam ao Codex em toda inicialização.
• Revisão de código: peça a outro agente para revisar o que o Codex mudou antes do merge.

A grade, os worktrees, a revisão de código e o gerenciador de MCP estão no plano gratuito. Baixe o AgentVera e teste no seu próprio repositório.

Conclusão

Instale o Codex, rode codex, entre com o ChatGPT e comece com uma tarefa pequena e real. Deixe no modo Auto e troque para somente leitura com /permissions quando quiser só respostas. Coloque as regras do projeto no AGENTS.md, os seus padrões no config.toml e adicione servidores MCP só quando precisar. Faça commit antes e depois de cada tarefa, e use codex resume para continuar de onde parou. Se você também quer testar o agente do Google, leia como usar o Gemini CLI.