Como Usar o Google Gemini 2.5 Pro com Open Codex CLI (Open Codex CLI)

Open Codex CLI é uma ferramenta de código aberto que traz o poder de grandes modelos de linguagem (LLMs) diretamente para o seu fluxo de trabalho no terminal. Este guia foca especificamente em aproveitar um dos modelos mais avançados disponíveis hoje – Google's Gemini 2.5 Pro – dentro do ambiente Open Codex CLI.

Open Codex CLI é um fork do original OpenAI Codex CLI, mantendo sua funcionalidade central, mas expandindo significativamente suas capacidades ao adicionar suporte a vários provedores de IA, incluindo Google Gemini. Isso permite que os desenvolvedores escolham o melhor modelo para sua tarefa, enquanto permanecem dentro de sua interface de terminal familiar. Imagine fazer perguntas complexas sobre codificação, gerar código padrão, refatorar funções existentes, explicar scripts complexos ou até mesmo orquestrar comandos de build, tudo alimentado pela inteligência do Gemini sem sair da sua linha de comando.

Este artigo fornece um guia abrangente, passo a passo, para instalar, configurar e usar o Open Codex CLI especificamente com Google Gemini 2.5 Pro (referindo-se à versão gemini-2.5-pro-preview-03-25 do modelo disponível no momento da escrita, conforme especificado na configuração do Open Codex CLI) e seus modelos semelhantes, como gemini-2.0-flash. Quer você seja um desenvolvedor experiente buscando otimizar seu fluxo de trabalho ou esteja novo no uso de assistentes de codificação em IA, você aprenderá a aproveitar essa poderosa combinação.

Por que Open Codex CLI com Gemini?

Isso é incrível. Em apenas algumas horas, meu amigo fez um fork do Open AI Codex para funcionar com Gemini 2.5 Pro 🤯 pic.twitter.com/gENT01q82P

— Sawyer Hood (@sawyerhood) 17 de abril de 2025

Combinar Open Codex CLI com Gemini 2.5 Pro oferece um conjunto atraente de benefícios:

• Fluxo de Trabalho Nativo do Terminal: Para desenvolvedores que preferem a linha de comando, o Open Codex CLI oferece uma integração perfeita. Não é necessário alternar entre seu editor, terminal e uma janela separada do navegador para assistência de IA. Isso leva a iterações mais rápidas e menos interrupções.
• Código Aberto e Flexível: Sendo uma ferramenta de código aberto (open-codex no npm), oferece transparência e a possibilidade de contribuições da comunidade. Seu suporte a múltiplos provedores (Gemini, OpenAI, OpenRouter, Ollama) dá a flexibilidade de trocar modelos ou provedores conforme necessário, sem alterar suas ferramentas principais.
• Capacidades Poderosas de IA: Gemini 2.5 Pro traz raciocínio, geração de código e capacidades de compreensão de ponta. Isso permite tarefas mais complexas, melhores sugestões de qualidade de código e análise mais profunda diretamente dentro do CLI.
• Orientado à Ação: Ao contrário de simples chatbots, o Open Codex CLI é projetado para ação. Ele pode ler seus arquivos locais para contexto, propor modificações em arquivos (patches) e executar comandos de shell dentro de um sandbox seguro, possibilitando um verdadeiro desenvolvimento orientado a chat.
• Foco em Segurança: O CLI incorpora mecanismos de sandboxing (Apple Seatbelt no macOS, Docker recomendado no Linux) para executar operações potencialmente arriscadas, como comandos de shell de forma segura, especialmente ao usar modos de auto-aprovação. Ele executa comandos sem rede e em um diretório de sandbox por padrão em modos de maior autonomia.
• Integração com Controle de Versão: A ferramenta é projetada para funcionar ao lado do Git. Por padrão, requer aprovação antes de modificar arquivos, permitindo que você revise as alterações antes que afetem seu diretório de trabalho, garantindo que você sempre tenha uma rede de segurança.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

1. Sistema Operacional: macOS 12 ou mais recente, uma distribuição Linux moderna (como Ubuntu 20.04+, Debian 10+) ou Windows 10/11 usando o Subsistema Windows para Linux (WSL2). O suporte direto ao Windows não está disponível.
2. Node.js: Versão 22 ou mais recente é necessária. Versões LTS (Suporte de Longo Prazo) são geralmente recomendadas. Você pode verificar sua versão executando node -v em seu terminal. Baixe o Node.js de nodejs.org.
3. Conta do Google Cloud & Chave de API do Gemini: Você precisará de uma chave de API para autenticar solicitações aos modelos Gemini. Você pode obter uma através do Google AI Studio ou do Google Cloud Console. Mantenha essa chave segura, pois está vinculada à sua conta.
4. Familiaridade com o Terminal: Conhecimento básico sobre como usar a interface de linha de comando do seu sistema (Terminal, iTerm, Bash, Zsh, etc.) é assumido.

Passo 1: Instalando Open Codex CLI

A maneira recomendada de instalar o Open Codex CLI é globalmente via npm (Node Package Manager), que vem incluído com o Node.js. Abra seu terminal e execute:

npm install -g open-codex

Alternativamente, se você usar o Yarn como seu gerenciador de pacotes, pode executar:

yarn global add open-codex

Este comando baixa o pacote open-codex e torna o comando open-codex acessível de qualquer lugar no seu terminal. Evite usar sudo para instalações globais do npm; se você encontrar problemas de permissão, é melhor corrigir as permissões do npm.

Você pode verificar a instalação executando open-codex --version ou open-codex --help.

Passo 2: Configurando Acesso ao Gemini

Para usar os modelos Gemini, o Open Codex CLI precisa da sua chave de API e precisa saber que você deseja usar o provedor gemini. Existem duas maneiras principais de configurar isso:

Método 1: Variável de Ambiente (Recomendado para Início Rápido/Testes)

A maneira mais simples de fornecer sua chave de API é através de uma variável de ambiente. O Open Codex CLI procura especificamente por GOOGLE_GENERATIVE_AI_API_KEY quando o provedor gemini é selecionado.

No seu terminal, execute o seguinte comando, substituindo "YOUR_API_KEY_HERE" pela sua chave real da API do Gemini:

export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE"

Importante: Este comando define a variável de ambiente somente para a sessão de terminal atual. Se você fechar o terminal ou abrir um novo, precisará executar o comando novamente.

Para tornar a chave de API disponível permanentemente, você precisa adicionar a linha export ao arquivo de configuração do seu shell. Arquivos comuns incluem:

• ~/.zshrc (para Zsh, o padrão no macOS recente)
• ~/.bashrc ou ~/.bash_profile (para Bash)

Adicione a linha export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE" ao arquivo apropriado, salve-o e, em seguida, reinicie seu terminal ou execute source ~/.zshrc (ou o caminho do arquivo relevante) para aplicar as alterações.

Você pode então especificar o Gemini como o provedor em cada invocação usando a flag --provider:

open-codex --provider gemini "Qual é a capital da França?"

Método 2: Arquivo de Configuração (Recomendado para Configuração Persistente)

Para uma configuração mais permanente, especialmente se você planeja usar o Gemini de forma consistente, pode usar o arquivo de configuração do Open Codex CLI. O CLI procura um arquivo de configuração em ~/.codex/config.json.

Crie o diretório se ele não existir: mkdir -p ~/.codex

Crie e abra o arquivo de configuração: nano ~/.codex/config.json (ou use seu editor de texto preferido).

Adicione o seguinte conteúdo JSON para especificar o Gemini como o provedor padrão:

{
  "provider": "gemini"
}

Você também pode opcionalmente definir um modelo Gemini padrão. O Open Codex CLI define gemini-2.5-pro-preview-03-25 como o modelo "agente" padrão e gemini-2.0-flash como o modelo "contexto completo" padrão para o Gemini. Para definir explicitamente o poderoso modelo 2.5 Pro como padrão para a maioria das interações, use:

{
  "provider": "gemini",
  "model": "gemini-2.5-pro-preview-03-25"
}

Salve o arquivo e saia do editor.

Crucialmente, mesmo ao usar o arquivo de configuração para definir o provedor e o modelo, você ainda precisa definir a variável de ambiente GOOGLE_GENERATIVE_AI_API_KEY conforme descrito no Método 1. O arquivo de configuração diz ao CLI qual provedor usar, enquanto a variável de ambiente fornece as credenciais para esse provedor.

Com o arquivo de configuração definido, você pode agora simplesmente executar open-codex e ele usará por padrão o provedor Gemini especificado:

open-codex "Qual é a capital da França?"

Passo 3: Uso Básico com Gemini

Agora que o Open Codex CLI está instalado e configurado para o Gemini, vamos explorar como interagir com ele.

Modo Interativo (REPL)

Para uma experiência semelhante a um chat, execute o CLI sem um prompt específico:

open-codex
# Ou se você não definiu o provedor padrão em config.json:
# open-codex --provider gemini

Isso inicia um Read-Eval-Print Loop (REPL) onde você pode digitar prompts, obter respostas e ter uma conversa contínua com o Gemini.

❯ open-codex --provider gemini
Bem-vindo ao Open Codex CLI! Digite seu pedido e, em seguida, pressione Enter duas vezes para enviar.
> Fale-me sobre o modelo Gemini 2.5 Pro.

Pressione Enter duas vezes para enviar o prompt. O Gemini responderá dentro do terminal. Você pode continuar a conversa digitando perguntas de acompanhamento.

Prompt Direto

Para solicitações únicas, você pode passar o prompt diretamente como um argumento. Se você não definiu padrões em config.json, precisará da flag do provedor. Você também pode especificar o modelo exato usando a flag --model ou -m:

• Usando o modelo Gemini padrão (se definido em config):

open-codex "Explique o conceito de closures em Python."

• Especificando explicitamente provedor e modelo:

open-codex --provider gemini --model gemini-2.5-pro-preview-03-25 "Escreva um script bash para encontrar todos os arquivos maiores que 10MB no diretório atual e suas subdiretórios."

• Usando um modelo Gemini diferente (por exemplo, Flash para tarefas potencialmente mais rápidas/baratas):

open-codex --provider gemini --model gemini-2.0-flash "Resuma os pontos principais da documentação do React sobre hooks."

O CLI processará a solicitação com o Gemini e imprimirá a resposta diretamente na saída padrão.

Passo 4: Aproveitando os Recursos do Open Codex com Gemini

O verdadeiro poder do Open Codex CLI reside em sua capacidade de interagir com seu ambiente de desenvolvimento local, guiado pelo Gemini.

Interação com o Sistema de Arquivos

O Gemini, via Open Codex CLI, pode ler arquivos em seu projeto atual para ganhar contexto para suas solicitações. Ele também pode propor alterações (escritas ou patches) em seus arquivos.

• Lendo Arquivos: Quando você menciona nomes de arquivos em seu prompt, o CLI muitas vezes os lê automaticamente para fornecer contexto ao Gemini.

# Supondo que você tenha um arquivo chamado 'calculate.js'
open-codex --provider gemini "Leia 'calculate.js' e sugira melhorias para a legibilidade."

• Escrevendo/Patchando Arquivos: Se você pedir ao Gemini para modificar um arquivo, o CLI gerará um diff (um resumo das alterações propostas) e pedirá sua aprovação antes de aplicar qualquer coisa.

open-codex --provider gemini "Adicione uma nova função chamada 'subtract' ao 'calculate.js' que aceita dois argumentos e retorna sua diferença."

O CLI mostrará as alterações propostas e solicitará: Aplicar patch? [y/N]. Pressione y para aceitar ou n para rejeitar.

Executando Comandos

O Open Codex CLI também pode executar comandos de shell sugeridos pelo Gemini. Isso é poderoso, mas requer cautela.

• Modos de Aprovação: A flag --approval-mode (ou -a) controla o nível de autonomia:
• suggest (padrão): Exige aprovação explícita para todas as alterações em arquivos e todos os comandos de shell. Recomendado para começar.
• auto-edit: Aplica automaticamente alterações em arquivos, mas ainda pede aprovação para comandos de shell.
• full-auto: Aplica automaticamente alterações em arquivos E executa comandos de shell (dentro do sandbox). Use com extrema cautela, especialmente em repositórios não confiáveis.
• Sandboxing: Nos modos auto-edit e full-auto, os comandos são executados sem rede e confinados ao diretório de trabalho atual e arquivos temporários por motivos de segurança.
• Exemplo (com modo padrão 'suggest'):

open-codex --provider gemini "Instale a biblioteca 'requests' usando pip."

O Gemini pode propor o comando pip install requests. O CLI mostrará o comando e perguntará: Executar comando? [y/N].

Contexto do Projeto (codex.md)

Você pode fornecer instruções ou contexto persistente sobre seu projeto ao Gemini criando arquivos codex.md. O CLI lê esses arquivos na seguinte ordem:

1. ~/.codex/instructions.md (Instruções pessoais e globais)
2. codex.md na raiz do seu repositório (Notas para todo o projeto)
3. codex.md no diretório de trabalho atual (Notas específicas do subdiretório)

Isso permite que você guie o comportamento do Gemini ou forneça informações sobre padrões do projeto, bibliotecas utilizadas, etc., sem precisar repetir isso em cada prompt.

Solução de Problemas & Dicas

• Erros de Chave de API: Certifique-se de que GOOGLE_GENERATIVE_AI_API_KEY está corretamente definido, exportado e acessível na sua sessão atual do terminal. Verifique se há erros de digitação.
• Modelo Não Encontrado: Verifique se o nome do modelo (gemini-2.5-pro-preview-03-25, gemini-2.0-flash, etc.) corresponde aos suportados ou configurados. Verifique o ~/.codex/config.json ou use a flag --model corretamente.
• Erros de Provedor: Certifique-se de que o provedor está definido como gemini através de config.json ou a flag --provider gemini.
• Log Verboso: Para depuração, execute comandos com a variável de ambiente DEBUG=true precedida: DEBUG=true open-codex --provider gemini "Meu prompt". Isso imprimirá informações detalhadas sobre a solicitação/resposta.
• Comece Simples: Comece com prompts diretos e aumente gradualmente a complexidade à medida que você se sentir confortável com como o Gemini e o CLI interagem.
• Revise Aprovações Cuidadosamente: Especialmente ao lidar com modificações em arquivos ou execução de comandos, sempre revise as alterações ou comandos propostos antes de aproválos (respondendo y).

Conclusão

O Open Codex CLI, potencializado pelo Gemini 2.5 Pro do Google, transforma seu terminal em um assistente inteligente de codificação. Ao seguir os passos descritos neste guia, você pode integrar perfeitamente capacidades avançadas de IA em seu fluxo de trabalho de desenvolvimento diário, diretamente da linha de comando.

Desde trechos rápidos de código e explicações até refatorações complexas e execução de scripts, essa combinação oferece um potencial significativo para aumentar a produtividade e agilizar tarefas. O foco da ferramenta em segurança através do sandboxing e aprovação do usuário, combinado com a flexibilidade do suporte a múltiplos provedores e sua natureza de código aberto, tornam o Open Codex CLI uma escolha atraente para desenvolvedores que buscam aproveitar a IA dentro de seu terminal.

Experimente diferentes prompts, explore os vários modos de aprovação (com cautela!) e descubra como o Gemini e o Open Codex CLI podem aprimorar sua experiência de codificação.