Como usar o Codex: guia completo para começar com CLI, extensão de IDE, Codex Cloud e app desktop

Na primeira vez que você usar o Codex, não peça para ele refatorar o projeto inteiro. Abra o repositório primeiro e dê uma tarefa pequena que você consiga verificar em cerca de 20 minutos.

Visão geral dos pontos de entrada

OpenAI Codex não é apenas uma ferramenta de terminal nem um único plugin de editor. É um coding agent que pode ser usado por vários pontos de entrada. Na documentação oficial, você vai ver CLI, IDE extension, Codex app e Codex web/cloud. Eles compartilham autenticação e capacidade de base, mas servem a cenários diferentes.

Comparação dos quatro pontos de entrada

Ponto de entrada	Definição	Melhor para	Usuário típico	Limitação
CLI	Coding agent rodando no terminal local	Repositórios locais existentes, mudanças pequenas, workflow de linha de comando	Usuários fortes de terminal, ambientes CI	Precisa de um repositório Git local; as mudanças aparecem nos arquivos locais
IDE Extension	Colaboração na barra lateral do editor	Trabalho atual no editor, contexto curto via open files / selected code	Usuários de VS Code / Cursor / Windsurf / JetBrains	Depende do ambiente do editor; tarefas complexas podem ser delegadas ao Cloud
Codex App	Command center desktop	Vários threads, worktrees, automations, gestão de Git	Usuários locais com várias tarefas em paralelo	Disponível em macOS / Windows; verifique Linux na página oficial
Codex Cloud/Web	Agente em nuvem conectado ao GitHub	Repositórios remotos, PRs, tarefas assíncronas, trabalho longe do computador	Equipes e workflows com repositórios remotos	Um Enterprise workspace pode exigir admin setup

Autenticação e diferenças de recursos

Codex aceita dois caminhos de autenticação, mas os recursos disponíveis não são iguais.

Autenticação	Pontos de entrada disponíveis	Disponibilidade de recursos Cloud	Melhor uso
ChatGPT account (Plus/Pro/Business/Edu/Enterprise)	Todos os pontos de entrada (CLI/IDE/App/Cloud)	Inclui GitHub code review, Slack e outros cloud-based features	Assinantes individuais e equipes
API key	CLI, SDK, IDE Extension	Não inclui GitHub code review, Slack nem outros cloud-based features	CI, automação e workflows cobrados por API

Preços, limites e recursos habilitados devem ser verificados na página oficial de pricing e no seu account dashboard. Se você entrar com uma API key e os recursos Cloud não aparecerem, isso é uma diferença de surface, não uma falha.

Ponto de entrada CLI

O CLI é um coding agent que roda no terminal local. Ele pode ler o código no diretório selecionado, modificar arquivos, executar comandos e verificar resultados. Por isso funciona bem quando você já tem um repositório local.

Definição e casos de uso do CLI

A função central do CLI é trabalhar dentro de um repositório local: ler código, editar arquivos, rodar testes, rodar lint, verificar erros e gerar um diff. Você não precisa abrir o arquivo no editor. Basta descrever a tarefa no terminal.

O CLI combina com:

• um repositório Git local já existente;
• tarefas que mexem em vários arquivos ou precisam de verificação por comando;
• mudanças que você quer ver localmente com git diff e commit;
• ambientes CI ou scripts de automação.

O CLI combina menos com:

• ausência de repositório local, quando é preciso clonar primeiro;
• alteração de apenas um arquivo aberto, em que IDE extension é mais confortável;
• workflow remoto de PR, em que Cloud se encaixa melhor.

Instalação e login do CLI

Instalação e login podem mudar. Use o fluxo abaixo como orientação geral e confira os comandos exatos na página oficial do CLI.

1. Escolher o método de instalação na página oficial do CLI: a página oficial atual oferece um standalone installer. Artigos antigos podem mencionar npm, mas a página oficial atual deve prevalecer.
2. Primeira execução: depois de instalar, execute codex e siga o fluxo de login.
3. Escolher o método de login: use um ChatGPT account ou uma API key. Um ChatGPT account cobre todas as surfaces; uma API key fica limitada a CLI, SDK e IDE extension, sem recursos Cloud.

O CLI oferece suporte a macOS, Windows e Linux. No Windows, você pode usar PowerShell native sandbox ou WSL2; siga os detalhes da página oficial do CLI.

Comandos CLI comuns

O CLI tem modos interactive e non-interactive. Estes são os seis comandos ou grupos de flags que um iniciante deve reconhecer primeiro. Os nomes podem mudar, então confira a CLI reference quando precisar da sintaxe exata.

Comando	Uso	Exemplo
codex	Modo interactive para trabalhar conversando no terminal	codex
codex exec	Modo non-interactive para CI ou scripts	codex exec "fix the CI failure"
codex login	Fazer login ou trocar de conta	codex login
codex update	Atualizar o CLI	codex update
codex doctor	Verificar configuração do ambiente e problemas comuns	codex doctor
Flags comuns	Ajustar permissões, modelo, sandbox e approvals	--sandbox read-only, --model, --ask-for-approval

A CLI reference inclui mais comandos e flags, como codex apply, codex cloud e codex app. Alguns comandos podem ter maturidade diferente. No começo, aprenda primeiro o modo interactive; codex exec fica para automação.

Primeira tarefa com CLI

A regra da primeira tarefa é simples: escolha um repositório existente e dê ao Codex uma tarefa verificável em cerca de 20 minutos.

As best practices oficiais recomendam um prompt com quatro partes.

Parte do prompt	O que significa	Exemplo
Goal	Resultado desejado	”Corrigir o comando de instalação desatualizado no README”
Context	Contexto relevante	”Este é um projeto Node.js. O README menciona npm install, mas o projeto agora usa yarn.”
Constraints	Limites da mudança	”Altere apenas o README. Não mude outros arquivos. Depois execute node README-example.js para confirmar que o comando funciona.”
Done when	Critério de conclusão	”O comando do README está atualizado e node README-example.js imprime a saída esperada.”

Boas primeiras tarefas:

• corrigir um comando ou link desatualizado no README;
• adicionar um teste ausente ou corrigir um teste falhando;
• corrigir um bug pequeno com mensagem de erro clara;
• limpar um comentário TODO;
• adicionar uma anotação de tipo simples a um módulo.

Evite como primeira tarefa:

• secrets ou dados de produção;
• grande refatoração ou recurso completo;
• pedido sem critério de validação, como “otimizar desempenho”.

Checklist de validação do CLI

Quando o CLI terminar, valide o resultado nesta ordem.

1. Ler o diff: execute git diff no terminal e confirme se a mudança corresponde ao pedido. Não confie apenas na mensagem “concluído”.
2. Rodar testes: se o projeto tiver testes, execute npm test ou o comando correspondente.
3. Rodar lint ou typecheck: se existirem, confirme que nenhum erro novo apareceu.
4. Conferir a saída do comando: se a tarefa incluía rodar um comando, confira se a saída é a esperada.
5. Manter secrets fora da primeira tarefa: se a tarefa tocar configuração sensível, revise antes se o agent realmente precisa alterar isso.

Faça commit ou push só depois da validação. Se a mudança não servir, reverta com Git, ajuste o prompt e tente de novo.

Ponto de entrada IDE Extension

IDE extension permite usar Codex na barra lateral do editor. É uma boa opção quando você já está trabalhando na IDE. A vantagem é o contexto mais curto e preciso: open files, selected code e referências @file, sem precisar descrever o projeto inteiro no terminal.

Definição e casos de uso da IDE

IDE extension não substitui o editor. Ela integra Codex como coding agent dentro do workflow do editor. O contexto vem dos arquivos abertos, do código selecionado ou de arquivos referenciados explicitamente com @file, o que ajuda em mudanças locais.

IDE extension combina com:

• trabalho em VS Code, Cursor, Windsurf ou JetBrains;
• tarefas sobre o arquivo atual ou poucos arquivos relacionados;
• vontade de ver as mudanças no editor enquanto acontecem;
• necessidade de referenciar um arquivo específico como contexto.

Combina menos com:

• ausência de ambiente de editor, em que o CLI é mais simples;
• tarefa longa em segundo plano, em que Cloud pode assumir;
• muitos arquivos ou fluxos de comandos complexos, em que CLI ou Cloud podem ser melhores.

IDEs compatíveis

IDE extension oferece suporte aos editores abaixo. Confira a disponibilidade atual na página oficial da IDE.

Editor	Observação
VS Code	Suporte oficial
Cursor	Fork do VS Code compatível com a VS Code extension
Windsurf	Fork do VS Code compatível com a VS Code extension
JetBrains	Suporte a Rider, IntelliJ, PyCharm, WebStorm e IDEs relacionados, conforme disponibilidade oficial

Se você trabalha no Cursor ou Windsurf, Codex extension e os recursos de IA nativos do editor podem conviver. Codex vira outro coding agent que você escolhe conforme a tarefa.

Instalação e login na IDE

Siga a página oficial da IDE para os passos atuais.

1. Instalar pelo marketplace de extensões: procure Codex extension no VS Code, Cursor, Windsurf ou JetBrains.
2. Fazer login: use um ChatGPT account ou uma API key. Um ChatGPT account cobre todas as surfaces; uma API key não inclui recursos Cloud.

Contexto disponível na IDE

O principal valor da IDE extension é o contexto do editor.

Tipo de contexto	O que significa	Exemplo
Open files	Arquivos abertos entram como contexto	Abra example.tsx e Codex pode inspecionar diretamente
Selected code	O trecho selecionado vira contexto	Selecione uma função e peça para Codex explicar ou refatorar
Referência @file	Referenciar outro arquivo explicitamente pelo nome	@example.tsx verifique os tipos deste componente
Reasoning effort	Ajustar quanto o agent raciocina	low/medium/high; use mais esforço em tarefas difíceis

IDE extension também oferece modos Chat, Agent e Agent Full Access. A diferença está em permissões e nível de automação. Comece com o modo Agent padrão e ajuste quando entender os trade-offs.

Delegar da IDE para Cloud

IDE extension pode delegar tarefas para Codex Cloud. Use isso quando:

• a tarefa pode demorar;
• envolve um repositório remoto;
• você precisa sair da máquina enquanto o trabalho continua;
• quer rodar uma tarefa complexa em segundo plano e revisar o resultado depois.

Slash commands comuns podem incluir os itens abaixo. Os nomes podem mudar; confira a página IDE features.

Comando	Uso
/cloud	Delegar a tarefa atual ao Cloud
/local	Executar a tarefa localmente
/review	Revisar base branch, mudanças sem commit ou um commit
/status	Ver o status de uma tarefa Cloud

Depois de usar /cloud, a IDE mostra o status da tarefa. Quando a tarefa Cloud terminar, volte para revisar o diff e o resultado.

Ponto de entrada Codex App

Codex app é um command center desktop para trabalho com vários threads e gestão de Git. Não é só mais uma janela de chat. Ele pode aproveitar histórico e configuração do CLI e da IDE extension, facilitando continuar em um projeto existente.

Definição e casos de uso do app

O app se concentra em vários threads, worktrees, automations e operações Git. Ele é útil quando você precisa de tarefas paralelas, diff pane e integração Git em um único espaço local.

O app combina com:

• vários task threads ao mesmo tempo;
• isolamento de trabalho paralelo com worktrees;
• diff pane visual e operações Git;
• workflow desktop com terminal integrada.

Combina menos com:

• alterar apenas o arquivo aberto, em que IDE extension é mais confortável;
• ausência de repositório local, caso em que você deve usar Cloud ou clonar primeiro;
• uma tarefa rápida, em que o CLI é mais direto.

Suporte de plataforma do app

Codex app oferece suporte a macOS e Windows. Confira a disponibilidade para Linux na página oficial do app.

Instalação e login no app

Siga a página oficial do app para os passos atuais.

1. Baixar e instalar: obtenha o instalador de macOS ou Windows na página oficial do app.
2. Fazer login: use um ChatGPT account ou uma API key. Alguns recursos podem não estar disponíveis com API key, conforme a orientação oficial.
3. Escolher um projeto: na primeira abertura, o app pede para selecionar um diretório de projeto local.

App Thread Mode

O app oferece três thread modes: Local, Worktree e Cloud.

Thread Mode	O que faz	Melhor para
Local	Trabalha diretamente no diretório atual do projeto	Mudanças pequenas, tarefa de um thread, primeira mensagem padrão
Worktree	Cria um worktree isolado para o thread	Tarefas paralelas, mudanças isoladas, evitar conflitos
Cloud	Delega a tarefa ao Codex Cloud	Repositórios remotos, PRs, tarefas longas

O workflow detalhado de Worktree fica para outro guia. Para começar, o modo Local basta.

Recursos principais do app

Os recursos centrais do app incluem:

Recurso	O que faz
Diff pane	Permite inspecionar mudanças de arquivos e fazer stage / revert por chunks
Operações Git	Oferece suporte a commit, push, criação de PR e ações do fluxo Git
Terminal integrada	Cmd+J abre a terminal no macOS; confira os atalhos atuais na página oficial
Sincronização com IDE	IDE extension e app podem sincronizar dentro do mesmo projeto
MCP settings compartilhados	CLI, IDE e app podem compartilhar MCP settings

O app também inclui um in-app browser, mas ele não usa páginas que exigem seu perfil de navegador logado. Abra páginas com login em um navegador externo.

Ponto de entrada Codex Cloud/Web

Codex web/cloud se conecta a um GitHub account e permite que Codex trabalhe em um repositório remoto e crie PRs. Ele combina com equipes, repositórios remotos e tarefas que você quer deixar rodando enquanto está longe do computador.

Definição e casos de uso do Cloud

Cloud gira em torno de repositórios remotos, PRs e trabalho assíncrono. Ele cria um contêiner na nuvem, faz checkout do repo, executa setup scripts, realiza a tarefa e devolve um diff e uma resposta.

Cloud combina com:

• repositórios remotos que você não quer alterar localmente;
• fluxos de PR em que Codex deve criar ou revisar uma PR;
• trabalho que deve continuar enquanto você está longe da máquina;
• workflow de equipe com revisão e colaboração.

Cloud combina menos com:

• pequenas mudanças locais, em que CLI ou IDE são melhores;
• sua primeira tarefa, que deve ser validada localmente;
• tarefas muito interativas, porque Cloud é assíncrono.

Tarefas adequadas para Cloud

Cloud funciona bem para estes tipos de tarefa:

Tipo de tarefa	Observação
PR review	Revisar uma PR em um repositório remoto
Trabalho complexo ou longo	Executar tarefas que precisam de mais tempo
Tarefas paralelas	Delegar várias tarefas ao mesmo tempo
Mudanças em repositórios remotos	Fazer mudanças sem tocar no checkout local

Não envie uma grande refatoração ou um recurso completo para Cloud no primeiro dia. Use primeiro CLI ou IDE localmente, aprenda a ler o resultado e só depois mova tarefas adequadas para Cloud.

Um Enterprise workspace pode exigir admin setup. Confira a página oficial do Cloud e a policy do seu workspace.

Fluxo do Cloud

Uma Cloud task segue, em geral, cinco passos:

1. Criar um contêiner: Cloud cria o ambiente de execução.
2. Checkout repo: o repositório do GitHub é baixado por checkout.
3. Executar setup script: se existir, o setup script configurado é executado.
4. Executar o agent loop: o agent executa comandos, verifica resultados e continua até concluir.
5. Devolver diff e resposta: ao final, a tarefa mostra o diff e uma resposta.

O cache do contêiner pode durar até 12 horas. Confira a política atual na página oficial Cloud environments.

Notas de segurança do Cloud

Cloud tem alguns limites de segurança importantes:

Item de segurança	O que significa
Secrets só ficam disponíveis durante setup	Secrets ficam disponíveis para setup scripts e são removidos antes do agent phase. Não faça o agent phase depender de scripts que leem secrets.
O agent phase não tem internet por padrão	O acesso à internet fica off por padrão durante o agent phase, embora limited ou unrestricted access possam ser configurados. Não presuma que o agent alcança serviços externos.
O cache dura até 12 horas	O cache do contêiner não é armazenamento de longo prazo. Não presuma que o estado vai persistir indefinidamente.

A configuração de segurança detalhada fica para um guia posterior sobre permissões, sandboxes e secrets.

Próximos passos

Depois da primeira tarefa, se Codex repetir o mesmo erro na segunda ou terceira execução, é hora de escrever um guia AGENTS.md do projeto. AGENTS.md dá instruções específicas do projeto para coding agents, para você não repetir o mesmo contexto em todo prompt.

Temas recomendados depois:

• Regras de projeto AGENTS.md: manter instruções do projeto e reduzir contexto repetido.
• Isolamento com worktree: executar várias tarefas em paralelo sem misturar mudanças.
• Workflow Cloud: repositórios remotos, PRs e configuração de ambiente.
• Permissões, sandboxes e secrets: limites de segurança e configuração.
• Comparativo de três ferramentas: Codex vs Claude Code vs Cursor em projetos reais.
• Automação com codex exec: chamadas de CI e scripts.

Artigos relacionados da BetterLink:

• Panorama 2026 de AI coding tools
• Guia de produtividade com Claude Code CLI
• Prática de workflow com Cursor
• Codex gateway e harness