Codex CLI: como instalar, autenticar e rodar o Codex no terminal

Fala aí, beleza? O agente de código da OpenAI saiu do navegador e foi morar onde o dev já passa o dia inteiro: o terminal, dentro da pasta do projeto

O Codex CLI é exatamente isso: um agente de código que roda no terminal, com repositório público em openai/codex, onde ele é descrito como "lightweight coding agent that runs in your terminal"

A implementação é em Rust (fica no diretório codex-rs do repositório) e a licença é Apache-2.0

A ideia deste post é bem prática: até o final tu vai ter o Codex instalado, autenticado e rodando a primeira tarefa no teu repositório local, seguindo a documentação oficial

Bora? 🙂

O que você precisa antes de instalar o Codex CLI

Antes de sair rodando comando, vale conferir quatro coisas

• Node.js 22 ou superior, se tu for pelo caminho do npm (nas outras vias de instalação isso não pesa)
• Um sistema suportado: macOS, Windows e Linux
• Uma conta ChatGPT para o login recomendado, ou uma chave de API se preferires esse caminho
• Um repositório local aberto, porque a primeira tarefa acontece dentro de um projeto de verdade, não no vazio

E no Windows, precisa de WSL?

Não precisa mais

Desde 13 de maio de 2026 o Codex roda nativamente no Windows, com sandbox do Windows, sem exigir WSL

O caminho por WSL 2 segue documentado pra quem precisa de ferramental Linux do lado, e aqui vai o aviso: WSL 1 não é suportado

Se tu tem uma instalação antiga do WSL parada num canto, confere a versão antes de perder tempo

Passo a passo: instalar, autenticar e rodar a primeira tarefa

1. Instale o Codex CLI

O caminho mais comum é o pacote com escopo no npm:

npm install -g @openai/codex

No macOS, dá pra ir de Homebrew:

brew install codex

E existe ainda o instalador standalone servido pela própria OpenAI para macOS e Linux, em https://chatgpt.com/codex/install.sh (a variante install.ps1 atende o Windows)

Pra instalação não interativa, tipo dentro de um Dockerfile ou de um script de setup de máquina, o instalador aceita a variável CODEX_NON_INTERACTIVE=1

O erro comum deste passo: Node abaixo de 22 no caminho do npm

2. Autentique com a tua conta

O login padrão é pelo ChatGPT, no navegador:

codex login

Sem flags, esse comando abre o navegador no fluxo OAuth do ChatGPT

Se tu preferir chave de API:

codex login --api-key "$OPENAI_API_KEY"

Os métodos suportados são OAuth do ChatGPT, device auth, chave de API e access token

E se tu pular esse passo e chamar o codex direto, tudo bem: na primeira execução ele mesmo pergunta o método de login, com a opção "Sign in with ChatGPT" na frente

Depois de logar, as credenciais ficam guardadas localmente, em ~/.codex/auth.json ou no cofre de credenciais do sistema operacional, ou seja: não precisa logar a cada sessão

E pra sair, codex logout remove as credenciais salvas

O erro comum deste passo: tentar concluir o OAuth numa máquina sem navegador (servidor, container, sessão SSH pelada)

3. Abra a pasta do projeto e chame o agente

cd meu-projeto
codex

Com o login já resolvido no passo anterior, ele abre a sessão interativa direto

Repara numa coisa: o Codex trabalha a partir do diretório em que tu chamou ele

Então abrir o terminal na raiz do repositório certo já é metade do resultado bom 😀

4. Rode a primeira tarefa com os padrões do CLI

Pede algo pequeno e verificável, tipo explicar um módulo, mapear onde uma função é usada ou corrigir um detalhe num arquivo só

O CLI já vem restritivo de propósito, e a documentação descreve os padrões assim: sem acesso à rede e escrita limitada ao workspace ativo

Guarda esse ponto, porque ele é a base sobre a qual os modos de sandbox trabalham, e os três modos eu destrincho na seção mais pra frente

Na prática, a primeira tarefa não vai sair instalando dependência nem batendo em endpoint externo, e isso é bom

O erro comum deste passo: achar que o agente travou quando na verdade foi o sandbox segurando um comando

5. Crie o AGENTS.md do projeto

Dentro da sessão interativa, digite / pra abrir a lista de comandos de barra e rode /init

Esse comando cria um AGENTS.md, que é onde moram as instruções do teu projeto pro agente

E tem uma mecânica importante aqui: o Codex procura primeiro AGENTS.override.md, depois AGENTS.md, subindo do diretório de trabalho até a raiz do projeto

Ou seja, dá pra ter instrução geral lá em cima e instrução específica dentro de um subprojeto

6. Ajuste modelo e configuração

O modelo pode ser escolhido de três jeitos: a flag --model (alias -m) na hora de iniciar, o comando /model dentro da sessão (que também mexe no esforço de raciocínio) ou a entrada model no arquivo de configuração

A configuração pessoal fica em ~/.codex/config.toml

O projeto pode sobrescrever com um .codex/config.toml dele

E se tu quiser mudar a pasta home do Codex, a variável CODEX_HOME faz esse trabalho

Sem escolha explícita, o Codex usa um modelo recomendado

Erros comuns na instalação e no login do Codex CLI

Agora a parte que economiza teu tempo

Sintoma: a instalação por npm falha

Causa provável: Node.js abaixo da versão 22

Solução: atualizar pro Node.js 22 ou superior, ou pular o npm e ir de brew install codex (macOS) ou do instalador standalone da OpenAI

Como prevenir: checar a versão do Node antes de instalar qualquer coisa global, principalmente em máquina que tu não formata há tempo

Sintoma: o login abre o navegador e não conclui

Causa provável: a máquina não tem navegador utilizável, o clássico servidor acessado por SSH

Solução: usar device auth, ou logar por chave de API com codex login --api-key "$OPENAI_API_KEY"

Como prevenir: decidir o método de autenticação ANTES de provisionar a máquina remota

Sintoma: o Codex não roda no ambiente WSL

Causa provável: o ambiente é WSL 1, que não é suportado

Solução: migrar pro WSL 2, ou usar o caminho nativo do Windows, que dispensa WSL

Como prevenir: conferir a versão do WSL logo de cara

Sintoma: um comando é bloqueado ou a tarefa fica sem rede

Causa provável: não é bug, é o padrão restritivo do CLI (sem rede, escrita limitada ao workspace)

Solução: escolher o modo de sandbox adequado à tarefa, coisa que a próxima seção destrincha

Como prevenir: já iniciar a sessão com o modo que combina com o que tu pretende fazer, em vez de descobrir no meio do caminho

Sandbox, aprovação e modo não interativo: como controlar o que o Codex faz

O controle de autonomia do Codex anda em dois eixos: o sandbox e a política de aprovação

Se tu conhece permissão de container, a analogia serve bem: um eixo diz o que o processo alcança, o outro diz quando ele te pergunta antes de agir

A flag --sandbox (atalho -s) tem três modos

E lembra do que eu falei no passo 4: os padrões do CLI já são sem acesso à rede e com escrita limitada ao workspace ativo

Essa é a base restritiva de fábrica, e a flag --sandbox é o que tu usa pra mexer nesse nível de acesso conforme a tarefa

O outro eixo é a flag --ask-for-approval, que controla os pedidos de aprovação (por exemplo --ask-for-approval never)

Revisar código sem risco nenhum

Pra soltar o agente num repositório que tu não conhece, o read-only é o modo óbvio

Ele lê e responde, e qualquer coisa além disso vira pedido de aprovação

É o modo pra fazer pergunta sobre arquitetura, entender um fluxo, mapear dependência

Deixar ele botar a mão no código

Quando a tarefa é editar mesmo, o workspace-write é o meio termo: edita e roda comando dentro do workspace, e escala pra ti quando precisa

codex -s workspace-write

Automatizar em script ou pipeline

Pra rodar sem sessão interativa existe o codex exec:

codex exec "corrija os imports não usados em src/"

E pra continuar de onde a rodada anterior parou:

codex exec resume --last "agora rode os testes e ajuste o que quebrar"

O resume também aceita ID de sessão, e o --all considera sessões de qualquer diretório

Esse é o formato que encaixa numa etapa de CI ou num fluxo de automação que tu já mantém, do mesmo jeito que dá pra pendurar tarefas em automações com n8n numa VPS e chamar cada peça de fora

Na sessão interativa a lógica é a mesma: o subcomando resume retoma uma conversa anterior, com o ID da sessão ou com --last pra pegar a mais recente

Plugar ferramentas via MCP

O Codex CLI suporta MCP (Model Context Protocol) com comando próprio:

codex mcp add meu-servidor -- comando-do-servidor
codex mcp list
codex mcp --help

Os transportes suportados são stdio e streamable HTTP, e a configuração é gravada no config.toml

É o caminho de dar ao agente acesso a ferramenta que ele não teria sozinho, sem escrever integração na mão

Planos, limites e modelos: o que saber antes de usar todo dia

Agora o lado chato mas necessário: quanto isso pesa

O Codex está incluído nos planos do ChatGPT, inclusive Free e Go, com limites de uso variando por plano

A documentação aponta o login com a conta ChatGPT como o caminho recomendado pra quem tem Plus, Pro, Business, Edu ou Enterprise

O ChatGPT Plus custa US$ 20 por mês

Uma mudança importante: em 2 de abril de 2026 a OpenAI passou a cobrar o Codex acompanhando o uso de tokens da API, no lugar do preço por mensagem

Isso valeu para planos Plus, Pro, ChatGPT Business novos e existentes, e Enterprise novos

Quem estoura o limite incluído não é obrigado a trocar de plano: Plus e Pro podem adicionar créditos pra continuar usando o Codex

Esses créditos valem 12 meses a partir da compra e são compartilhados com outros recursos suportados da conta

E os modelos, mudam?

Mudam, e tem data marcada

O gpt-5.4 e o gpt-5.4-mini saem do Codex com login ChatGPT em 31 de agosto de 2026

Os substitutos indicados são o gpt-5.6-terra no lugar do gpt-5.4 e o gpt-5.6-luna no lugar do gpt-5.4-mini

Se tu deixou o nome do modelo cravado no config.toml ou num script de pipeline, anota essa data agora, senão vira surpresa no dia

Conclusão

O caminho mínimo do Codex CLI cabe em três movimentos: instalar (npm install -g @openai/codex, brew install codex ou o instalador standalone), autenticar com codex login e abrir a pasta do projeto pra rodar codex

O resto é calibragem

O próximo passo concreto é rodar /init pra criar o AGENTS.md do teu repositório, escolher o modo de sandbox que combina com ele (read-only pra explorar, workspace-write pra deixar editar) e testar um codex exec numa tarefa pequena antes de plugar o agente em qualquer automação séria

Começa pequeno, olha o diff, aí sim solta a rédea

até o próximo post! 😀