OpenAI Codex CLI - agente de programação leve executado no terminal

• OpenAI Codex é um agente de programação leve executado no terminal, permitindo que desenvolvedores usem raciocínio no nível do ChatGPT no ambiente de terminal, além de execução de código, manipulação de arquivos e recursos de controle de versão
• O Codex não exige configuração e é executado com segurança por meio de rede desativada e sandbox de diretório
• Suporta recursos multimodais, permitindo implementar funcionalidades a partir de capturas de tela ou diagramas
• O Codex é totalmente open source, com a vantagem de que desenvolvedores podem contribuir diretamente e evoluí-lo
• Pode ser executado em vários sistemas operacionais, com suporte a macOS, Linux e Windows WSL2

---

Introdução ao OpenAI Codex

• OpenAI Codex é um agente de programação leve executado no terminal
• Desenvolvedores podem usar raciocínio no nível do ChatGPT no ambiente de terminal, além de execução de código, manipulação de arquivos e recursos de controle de versão
• Não exige configuração e é executado com segurança por meio de rede desativada e sandbox de diretório
• Suporta recursos multimodais, permitindo implementar funcionalidades a partir de capturas de tela ou diagramas
• É totalmente open source, permitindo que desenvolvedores contribuam diretamente e o evoluam

Modelo de segurança e permissões do Codex

• O Codex fornece a flag --approval-mode para determinar o nível de autonomia do agente
• No modo Suggest, só é possível ler arquivos, e toda gravação/patch em arquivos e comandos de shell exigem aprovação
• No modo Auto Edit, é possível ler arquivos e gravar patches, mas comandos de shell exigem aprovação
• No modo Full Auto, é possível ler/gravar arquivos e executar comandos de shell, com a rede desativada e restrição ao diretório de trabalho atual

Detalhes do sandboxing por plataforma

• No macOS 12+, usa Apple Seatbelt para encapsular os comandos
• No Linux, usa Docker para executar o Codex dentro de uma imagem mínima de contêiner
• As duas abordagens funcionam de forma transparente no uso cotidiano

Requisitos de sistema

• Sistema operacional: macOS 12+, Ubuntu 20.04+/Debian 10+, Windows 11 (WSL2)
• Node.js: 22 ou superior (LTS recomendado)
• Git: 2.23+ (recomendado para o recurso de assistente de PR)
• RAM: mínimo de 4 GB (8 GB recomendados)

Referência da CLI

• codex: executa o REPL interativo
• codex "…": prompt inicial do REPL interativo
• codex -q "…": modo não interativo "silencioso"
• Principais flags: --model/-m, --approval-mode/-a, --quiet/-q

Memória e documentação do projeto

• O Codex mescla instruções em Markdown na seguinte ordem: ~/.codex/instructions.md, codex.md (raiz do repositório), codex.md (diretório de trabalho atual)
• Pode ser desativado com --no-project-doc ou CODEX_DISABLE_PROJECT_DOC=1

Modo não interativo / CI

• O Codex pode ser executado de forma headless em pipelines
• É possível remover o ruído da interface interativa com CODEX_QUIET_MODE=1

Receitas

• codex "Refactor the Dashboard component to React Hooks": refatora o componente de classe e executa testes
• codex "Generate SQL migrations for adding a users table": infere o ORM e cria/executa os arquivos de migração
• codex "Write unit tests for utils/date.ts": gera e executa testes
• codex "Bulk‑rename *.jpeg → *.jpg with git mv": renomeia arquivos com segurança e atualiza o uso
• codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$": explica a expressão regular
• codex "Carefully review this repo, and propose 3 high impact well-scoped PRs": propõe PRs de alto impacto
• codex "Look for vulnerabilities and create a security review report": encontra e descreve bugs de segurança

Instalação

• Instalação via npm (recomendada): npm install -g @openai/codex
• Build a partir do código-fonte: clonar o repositório, ir para o pacote CLI e instalar/buildar as dependências

Configuração

• O Codex procura arquivos de configuração em ~/.codex/
• É possível definir instruções personalizadas: ~/.codex/instructions.md

FAQ

• A OpenAI lançou um modelo chamado Codex em 2021, um sistema de IA que gera código a partir de prompts em linguagem natural
• O Codex sempre roda em sandbox e, ao sugerir comandos suspeitos ou alterações de arquivo, digitar n evita qualquer impacto na árvore de trabalho
• No Windows, ele não roda diretamente; é necessário usar o Windows Subsystem for Linux (WSL2)
• Modelos suportados: todos os modelos disponíveis via Responses API

Contribuição

• Este projeto está em desenvolvimento ativo, e o código pode mudar consideravelmente
• Contribuições são bem-vindas, com foco em confiabilidade e manutenção de longo prazo
• Há diretrizes sobre fluxo de trabalho de desenvolvimento, escrita de mudanças de código de alta qualidade, abertura de PR, processo de review, valores da comunidade e como obter ajuda

Licença

• Este repositório está sob a licença Apache-2.0

[GN⁺]

Opiniões do Hacker News

• Compararam o Codex o4-mini com o Claude Code para tentar documentar uma base de código de porte médio

  • O Claude Code escreveu uma documentação excelente
  • O Codex inventou coisas que não existiam no código e descreveu uma arquitetura incorreta
  • O problema do Codex parece ser a dificuldade em carregar o contexto correto e prestar atenção
  • Há grandes expectativas em relação aos modelos o3 e o4-mini, e a esperança é que apresentem resultados melhores em outros testes

• Colaram todo ou parte do repositório no gemini e aplicaram alterações ao código usando um script que criaram

  • Tentaram aider, copilot, continue etc., mas cada um tinha suas desvantagens

• O Claude Code é muito bom, e houve experiências anteriores de frustração com outros agentes de programação

  • Usando o Claude Code, obtiveram resultados positivos, e o custo de $15 pode ser justificável
  • Esperam que a concorrência traga bons resultados

• Há demos e vídeos de apresentação relacionados, e isso é uma resposta direta ao Claude Code

  • Não é open source, e há menção a questões relacionadas à DMCA
  • Uma entrevista sobre o Claude Code deve ser publicada em breve e tratará da importância da CLI de agentes de código
  • Estão procurando usuários avançados de Claude Code e OAI Codex

• No momento, ele tem desempenho inferior ao Claude Code, mas, por ser open source, há esperança de que melhore rapidamente

• O Codex não funciona diretamente no Windows e exige WSL2

  • Há uma tendência de redução do escopo de desenvolvimento nativo no Windows

• A experiência inicial de uso do Codex não foi boa

  • O modelo padrão não funciona, sendo necessário trocar de modelo
  • No início, ele travou por causa de um erro do NodeJS
  • Depois de resolver os problemas iniciais, estão comparando com o Claude Code

• Há uma forma de definir a chave da API da OpenAI como variável de ambiente

  • Existe preocupação com a possibilidade de outros utilitários de terceiros terem acesso à chave da API

• Tiveram bons resultados com a CLI para desenvolvedores do Amazon Q e acreditam que ela usa claude-3.7-sonnet