O Codex é o agente de programação da OpenAI: ele lê o seu repositório, edita arquivos, roda comandos e testes e devolve as mudanças para você revisar. Para começar no terminal, instale a Codex CLI (por exemplo, com npm install -g @openai/codex), entre na pasta do projeto, rode codex e faça login com a conta do ChatGPT. No GitHub, conecte o repositório ao Codex e escreva @codex review num pull request para receber uma revisão automática.
O mesmo agente aparece em vários lugares: no terminal, em editores como VS Code e Cursor, no app desktop do ChatGPT, na nuvem e dentro do GitHub. Os planos pagos do ChatGPT a partir do Plus liberam esses acessos, e o Free e o Go têm uma versão limitada no app desktop. Este guia mostra o passo a passo de instalação, as permissões que mantêm o agente sob controle, a integração com GitHub e GitHub Actions e quanto cada plano inclui.
Resumo rápido
- A Codex CLI é de código aberto (licença Apache-2.0) e roda localmente no macOS, Linux e Windows.
- Instale com o script oficial, npm ou Homebrew, rode
codexe escolha “Sign in with ChatGPT” ou uma chave de API.- Por padrão, o agente roda sem acesso à rede e só escreve na pasta do projeto; o comando
/permissionsajusta esses limites.- No GitHub,
@codex reviewpede uma revisão do PR, e a revisão automática pode rodar em todo PR novo.- O Plus (US$ 20 por mês) inclui CLI, extensão de IDE, web e revisão de código; com chave de API não há recursos de nuvem.
Onde o Codex roda
O Codex é um agente de IA: em vez de só sugerir a próxima linha, ele recebe uma tarefa, planeja, executa passos e mostra o resultado. A OpenAI oferece o agente em cinco superfícies, que compartilham a mesma conta e o mesmo limite de uso.
| Superfície | Onde roda | Melhor para |
|---|---|---|
| Codex CLI | No terminal, no seu computador | Explorar código, editar, rodar testes, automação com scripts e CI |
| Extensão de IDE | VS Code, Cursor, Windsurf; Xcode e JetBrains têm integração própria | Edições focadas usando os arquivos já abertos no editor |
| App desktop do ChatGPT | macOS, Windows e Linux, selecionando Codex | Projetos locais e tarefas longas com interface gráfica |
| Codex Cloud | Ambientes da OpenAI, acessados pela web, celular ou app | Tarefas que rodam sozinhas e terminam em commit ou pull request |
| GitHub | Comentários em PRs e GitHub Actions | Revisão de código e tarefas disparadas pelo repositório |
Se você ainda está decidindo entre Codex, GitHub Copilot, Cursor ou Claude Code, o comparativo geral está no nosso guia de ferramentas de IA para programar. Aqui o foco é colocar o Codex para funcionar.
Como instalar a Codex CLI
A documentação oficial lista quatro formas de instalação. Escolha uma:
# macOS e Linux (instalador oficial)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Windows (em uma nova janela do PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
# npm (qualquer sistema com Node.js)
npm install -g @openai/codex
# Homebrew
brew install --cask codex
Para atualizar, rode de novo o mesmo instalador ou o mesmo comando do npm; no Homebrew, use brew upgrade --cask codex. Também é possível baixar o binário direto da página de releases do repositório openai/codex no GitHub.
Primeiro login e primeira tarefa
- Abra o terminal na pasta do projeto e rode
codex. - Escolha Sign in with ChatGPT para usar o Codex dentro do seu plano. A alternativa é uma chave de API, cobrada pelo preço da API.
- Peça algo simples para começar, como “explique a estrutura deste projeto”.
- Antes de pedir mudanças, crie um ponto de controle no Git (um commit ou um branch). A própria OpenAI recomenda isso para poder desfazer o trabalho do agente.
Comandos que você vai usar no dia a dia
/init: gera um arquivo AGENTS.md inicial na pasta atual./model: troca o modelo e o nível de raciocínio./permissions: define quando o Codex pode editar arquivos ou rodar comandos sem perguntar./review: pede uma revisão das mudanças locais, sem alterar a árvore de trabalho./status: mostra modelo ativo, política de aprovação e uso restante.codex --search: ativa busca na web quando a tarefa depende de documentação atual.codex mcp: conecta servidores MCP, como explicado no nosso guia de Model Context Protocol.
Permissões, sandbox e AGENTS.md
Um agente que roda comandos no seu computador precisa de limites claros. O Codex trabalha com duas camadas. A primeira é o sandbox, que define o que ele consegue fazer tecnicamente: na CLI e na extensão de IDE, o padrão é sem acesso à rede e com escrita apenas na pasta ativa, imposto por mecanismos do próprio sistema operacional. A segunda é a política de aprovação, que define quando ele precisa parar e pedir sua autorização.
No modo Auto (equivalente a --sandbox workspace-write --ask-for-approval on-request), o Codex lê, edita e roda comandos dentro da pasta do projeto, mas pede aprovação para mexer fora dela ou para usar a rede. Para só conversar e planejar, mude para o modo somente leitura pelo /permissions ou rode codex --sandbox read-only --ask-for-approval on-request. Chamadas a ferramentas externas marcadas como destrutivas sempre pedem aprovação.
Regras do projeto no AGENTS.md
Antes de qualquer tarefa, o Codex lê arquivos AGENTS.md. Primeiro o global, em ~/.codex/AGENTS.md, depois os do projeto, da raiz do repositório até a pasta atual. Os arquivos mais próximos da pasta em que você está prevalecem, e o total lido tem limite padrão de 32 KiB. Use o arquivo para registrar o que um colega novo precisaria saber:
## Regras de trabalho
- Rode `npm test` depois de alterar arquivos JavaScript.
- Use pnpm para instalar dependências.
- Peça confirmação antes de adicionar dependência de produção.
- Nunca altere arquivos em /migrations já aplicadas.
Codex no GitHub: revisão de PRs e tarefas
A integração com o GitHub faz o Codex agir como um revisor do time. A configuração tem três passos: conectar o repositório ao Codex, abrir as configurações de revisão de código em chatgpt.com e ativar Automatic review para o repositório. Para isso, você precisa de permissão de push ou de administrador no repositório.
Depois disso, há três formas de usar:
- Revisão sob demanda: comente
@codex reviewno pull request. O Codex reage e publica uma revisão comum do GitHub. Ele sinaliza só problemas de prioridade P0 e P1, para não encher o PR de comentários menores. Dá para focar:@codex review for issues in the database migration. - Revisão automática: com a opção ativada, todo PR elegível recebe revisão sem precisar do comentário.
- Correções e outras tarefas:
@codex fix the P1 issueou@codex fix the CI failuresabrem uma tarefa na nuvem com o PR como contexto, e o Codex pode enviar a correção para o branch quando tiver permissão.
Para orientar o revisor, crie uma seção ## Code Review Rules no AGENTS.md mais próximo do código que a regra cobre. A OpenAI sugere começar com duas ou três regras específicas do seu sistema e deixar formatação e lint para o CI. Existe ainda a Security Review, em research preview, acionada com @codex security review, que faz uma análise mais funda de riscos de segurança no PR. As regras de revisão orientam o agente, mas não substituem testes, proteção de branch e aprovações obrigatórias.
GitHub Actions com o Codex
Para rodar o Codex dentro de um pipeline, a OpenAI publica a action openai/codex-action@v1. Ela instala a CLI e executa codex exec, o modo não interativo, com as permissões que você definir. Os requisitos são guardar a chave da API como segredo do repositório (por exemplo, OPENAI_API_KEY), rodar em runner Linux ou macOS e fazer o checkout do código antes. Um passo mínimo fica assim:
- name: Run Codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt-file: .github/codex/prompts/review.md
sandbox: read-only
Fora do GitHub, o codex exec funciona em qualquer script: codex exec "gere notas de versão dos últimos 10 commits" | tee notas.md. O progresso vai para o stderr e só a resposta final sai no stdout, o que facilita encadear com outras ferramentas.
Codex na IDE e na nuvem
A extensão oficial para VS Code, Cursor e Windsurf está no Visual Studio Marketplace com o identificador openai.chatgpt. Depois de instalar, clique no ícone do Codex ou rode Codex: Open Codex Sidebar na paleta de comandos. No Xcode, escolha o Codex como agente no assistente de código; nos IDEs da JetBrains, abra o AI Chat e selecione Codex. A vantagem da extensão é usar os arquivos e trechos já abertos como contexto e revisar o diff ao lado do código.
O Codex Cloud serve para tarefas que não precisam do seu computador ligado. Você cria um ambiente escolhendo os repositórios do GitHub; o Codex inspeciona o projeto, instala dependências, testa o fluxo e pede o que faltar. Depois de publicar o ambiente, cada tarefa ganha um espaço de trabalho próprio e termina com as mudanças prontas para commit ou pull request. Da CLI, codex cloud envia trabalho para a nuvem e traz o resultado de volta para o repositório local.
Planos e limites de uso
O Codex está incluído nos planos do ChatGPT, com limites diferentes. Os valores abaixo estão na página de preços da documentação da OpenAI, em dólares; a empresa não publica ali preços em reais.
| Plano | Preço | O que inclui no Codex |
|---|---|---|
| Free | US$ 0 | GPT-6 Luna em velocidade padrão no app desktop, conforme liberação |
| Go | US$ 8/mês | O mesmo do Free, para tarefas leves |
| Plus | US$ 20/mês | Codex na web, CLI, extensão de IDE e iOS; revisão automática de código e Slack; GPT-6.1 Sol e GPT-6 Luna; créditos extras opcionais |
| Pro | A partir de US$ 100/mês | Tudo do Plus, com opções de US$ 100, 200 ou 500 e mais uso |
| Business | US$ 20 por usuário/mês no anual (US$ 25 no mensal) | Workspace com controles de administração, SSO e sem treino com dados da empresa por padrão |
| Chave de API | Preço da API | CLI, SDK e extensão de IDE, sem recursos de nuvem como revisão no GitHub e Slack |
O limite não é um número fixo de mensagens. A OpenAI estima, para o Plus, entre 15 e 160 mensagens locais a cada cinco horas com o GPT-6.1 Sol, e muito mais com o GPT-6 Luna, que é mais leve. Tarefas na nuvem consomem mais, e pode haver limite semanal. O uso é compartilhado com o ChatGPT Work e outros recursos agênticos, como o ChatGPT para Excel. Acompanhe pelo /status ou pelo painel de uso. Desde 14 de outubro de 2026, o GPT-5.5 não está mais disponível no Codex com login do ChatGPT; quem usa chave de API não foi afetado.
Exemplo: loja virtual de cafés em Belo Horizonte
Uma loja virtual de cafés especiais tem um desenvolvedor só, que cuida do site em Node.js hospedado num repositório do GitHub. Ele assina o Plus e montou o fluxo assim:
- AGENTS.md na raiz: regras como “rode os testes antes de concluir”, “não mexa na integração de pagamento sem pedir” e uma seção Code Review Rules dizendo que qualquer mudança no cálculo de frete precisa de teste.
- Terminal: num branch novo, pede ao Codex “adicione um filtro por tipo de torra na página de produtos e escreva os testes”. O agente trabalha no modo Auto e pede aprovação quando precisa instalar uma dependência pela rede.
- Revisão local: antes do commit, roda
/reviewe lê os apontamentos. - GitHub: abre o PR, e a revisão automática do Codex comenta um caso de frete sem teste. Ele comenta
@codex fix the P1 issue, confere o commit enviado e faz o merge só depois dos testes passarem no CI.
Os dados de clientes ficam fora do repositório, e as chaves do gateway de pagamento estão em variáveis de ambiente, nunca no código que o agente lê.
Erros comuns
- Trabalhar sem ponto de controle no Git. Sem commit ou branch antes da tarefa, desfazer uma edição ruim vira trabalho manual.
- Liberar acesso total para “ir mais rápido”. O modo
danger-full-accessremove o sandbox. Use só em ambiente isolado. - Não escrever o AGENTS.md. Sem as regras do projeto, o agente adivinha comandos de teste, gerenciador de pacotes e convenções.
- Tratar a revisão do Codex como aprovação final. Ela é mais um par de olhos. Mantenha testes, proteção de branch e revisão humana.
- Usar chave de API esperando os recursos de nuvem. Com chave de API não há revisão no GitHub nem Slack.
- Deixar segredos no repositório. Tudo que está nos arquivos pode entrar no contexto do agente.
Perguntas frequentes
O Codex é gratuito?
A CLI é de código aberto, mas o uso do modelo depende de um plano ou de uma chave de API. No Free e no Go, a OpenAI oferece o GPT-6 Luna no app desktop, conforme liberação. CLI, IDE, web e revisão no GitHub entram a partir do Plus.
Funciona no Windows?
Sim. Há instalador oficial para PowerShell, e a documentação tem guias para o sandbox nativo do Windows e para o WSL. O app desktop do ChatGPT também tem versão para Windows.
Qual a diferença entre a Codex CLI e o Codex Cloud?
A CLI roda no seu computador, sobre os arquivos locais. O Codex Cloud roda em ambientes da OpenAI conectados aos seus repositórios do GitHub e continua trabalhando mesmo com o computador desligado.
Posso usar o Codex com outros modelos?
Com login do ChatGPT, você escolhe entre os modelos do seu plano pelo /model. Com chave de API, os modelos disponíveis seguem os liberados para a sua chave.
O Codex está disponível no Brasil?
O Brasil está na lista de países atendidos pela API da OpenAI. A documentação do Codex não traz restrição ou menção específica ao país, e a página de preços mostra valores apenas em dólares. Mais detalhes sobre os produtos da empresa estão na nossa página de integrações da OpenAI e do ChatGPT.
