# Como usar o Codex CLI: guia passo a passo URL: https://agentvera.dev/pt/blog/how-to-use-codex-cli/ · Publicado: 2026-10-25 Como usar o Codex CLI: instale, entre com o ChatGPT, escolha os modos de sandbox e aprovação, escreva o AGENTS.md, configure o config.toml e MCP, e retome sessões. **Resumo:** - Instale o Codex CLI com o script oficial, npm ou Homebrew, rode codex na pasta do projeto e entre com sua conta do ChatGPT ou uma chave de API. - O modo Auto padrão deixa o Codex editar e rodar comandos dentro do workspace e pergunta antes de tocar em algo fora dele ou na rede; /permissions troca para somente leitura. - As regras do projeto ficam no AGENTS.md, as configurações em ~/.codex/config.toml, servidores MCP entram com codex mcp add e codex resume retoma uma sessão anterior. Para usar o Codex CLI, instale com um comando, rode `codex` dentro da pasta de um projeto, entre com sua conta do ChatGPT e descreva a mudança que você quer em linguagem natural. O Codex lê o código, edita arquivos e roda comandos dentro do projeto, e pergunta antes de sair da pasta ou acessar a rede. Esse é o ciclo básico. Este guia cobre o resto: modos de aprovação e sandbox, um arquivo `AGENTS.md`, o `config.toml`, servidores MCP, os comandos que você vai usar todo dia, retomar sessões e alguns hábitos que deixam o Codex mais confiável. Tudo aqui segue a documentação oficial do Codex da OpenAI em outubro de 2026. ## O que é o Codex CLI O Codex CLI é o agente de código da OpenAI para o terminal. Ele roda localmente, trabalha na pasta de onde você o inicia e pode rodar seus testes, linters e o git. O mesmo Codex também existe como extensão de IDE, app desktop e versão na nuvem, e todos compartilham o seu login. Se você está escolhendo entre agentes, [Claude Code vs Codex](/pt/blog/claude-code-vs-codex/ "Claude Code vs Codex") e [Codex vs Gemini CLI](/pt/blog/codex-vs-gemini-cli/ "Codex vs Gemini CLI") comparam os dois em detalhes. Em resumo, o Codex é um [agente de código](/pt/glossary/coding-agent/ "O que é um agente de código"), não um autocomplete: você dá uma tarefa, ele planeja e executa. ## Passo 1: instale o Codex CLI A OpenAI oferece um script de instalação para cada plataforma, e a CLI também está no npm e no Homebrew. | Plataforma | Comando | | --- | --- | | macOS, Linux | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | | Windows PowerShell | `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` | | Qualquer plataforma com Node.js | `npm install -g @openai/codex` | | macOS (Homebrew) | `brew install --cask codex` | Para atualizar, rode o mesmo script de instalação de novo, rode `codex update` ou use o seu gerenciador de pacotes (`brew upgrade --cask codex`). Confira se funcionou: ```bash codex --version ``` ## Passo 2: faça login Entre em um projeto e inicie o Codex: ```bash cd my-project codex ``` Na primeira execução, o Codex pergunta como você quer entrar: - **Sign in with ChatGPT (entrar com o ChatGPT):** usa o seu plano do ChatGPT. O uso conta nos limites do plano. É a escolha mais comum, e a única que também libera o Codex na nuvem. - **API key (chave de API):** usa uma chave de API da OpenAI e é cobrada por token. Útil para CI ou quando você quer cobrança por uso. Você também pode gerenciar isso pelo shell. `codex login` abre o login no navegador, `codex login --device-auth` dá um código de dispositivo para uma máquina remota ou sem interface gráfica, `codex login status` diz se você está logado e `codex logout` apaga as credenciais salvas. Para entrar com uma chave sem digitá-la, mande por pipe: `printenv OPENAI_API_KEY | codex login --with-api-key`. No momento em que escrevo, o Codex está incluído no ChatGPT Free, Go, Plus, Pro, Business, Edu e Enterprise. Planos maiores dão limites maiores; confira a [página de preços do Codex da OpenAI](https://learn.chatgpt.com/docs/pricing "Preços do Codex") para os números atuais. Você vê onde está a qualquer momento com `/status` ou `/usage` dentro de uma sessão. ## Passo 3: sua primeira tarefa Comece com algo pequeno e real para ver como o Codex trabalha: ```text Explain how authentication works in this project, then add a test for the password reset flow. Run the test suite when you're done. ``` O Codex lê os arquivos relevantes, diz o que planeja fazer, edita o código e roda os testes. Algumas coisas deixam isso mais fluido: - Digite `@` para buscar um arquivo e anexá-lo ao prompt. - Comece uma linha com `!` para rodar você mesmo um comando de shell, por exemplo `!git status`. - Enquanto o Codex trabalha, aperte **Enter** para adicionar instruções ao turno atual, ou **Tab** para enfileirar uma mensagem para depois que ele terminar. - Aperte **Esc** duas vezes com o campo vazio para editar a mensagem anterior e continuar dali. - `/diff` mostra o que mudou, incluindo arquivos não rastreados. Para capturas de tela ou mockups de design, anexe imagens com `codex --image path/to/file.png` ou cole no prompt. ## Passo 4: modos de aprovação e sandbox Vale entender esta parte antes de dar trabalhos maiores ao Codex. O Codex combina duas configurações: um **sandbox** que limita o que os comandos podem fazer tecnicamente, e uma **política de aprovação** que decide quando o Codex para e pergunta a você. | Modo | Flags | O que o Codex pode fazer | | --- | --- | --- | | Auto (padrão) | `--sandbox workspace-write --ask-for-approval on-request` | Ler, editar e rodar comandos dentro do projeto; pergunta antes de sair dele ou usar a rede | | Somente leitura | `--sandbox read-only --ask-for-approval on-request` | Ler e responder; pergunta antes de qualquer edição ou comando que mude estado | | Não interativo, somente leitura | `--sandbox read-only --ask-for-approval never` | Nunca pergunta; útil para checagens de CI que não devem mudar nada | | Acesso total | `--sandbox danger-full-access` | Sem sandbox; só em uma máquina que você aceita perder | Dentro de uma sessão, `/permissions` alterna entre Auto e Read Only. O acesso à rede vem desligado no sandbox workspace-write; você pode ligá-lo no `config.toml` (veja abaixo) se os seus testes precisarem. Se o Codex precisa escrever em uma segunda pasta, como uma biblioteca compartilhada ao lado do projeto, use `--add-dir` em vez de passar para acesso total. A OpenAI desaconselha explicitamente o `--dangerously-bypass-approvals-and-sandbox` (apelido `--yolo`) fora de uma VM dedicada e isolada. O sandbox é um isolamento real no nível do sistema operacional: Seatbelt no macOS, bubblewrap com seccomp no Linux e um sandbox nativo no Windows. Dentro do WSL2, o Codex usa o sandbox do Linux. Para uma visão mais ampla do que pode dar errado com agentes e como limitar, veja [segurança de agentes de código com IA](/pt/blog/ai-coding-agent-security/ "Segurança de agentes de código com IA"). ## Passo 5: escreva um AGENTS.md O `AGENTS.md` é um arquivo Markdown de instruções que o Codex lê antes de começar a trabalhar. É onde você coloca o que repetiria em todo prompt: como fazer build e testar, estilo de código, pastas que não devem ser tocadas. Rode `/init` em uma sessão e o Codex gera uma primeira versão para você. Um bom arquivo é curto e específico: ```markdown # AGENTS.md ## Commands - Install: pnpm install - Test: pnpm test (run before saying a task is done) - Lint: pnpm lint ## Conventions - TypeScript strict mode, no any. - New API routes go in src/routes and need a test. ## Don't - Don't edit files in src/generated. - Don't add dependencies without asking. ``` O Codex procura esses arquivos em uma ordem definida: 1. **Global:** `~/.codex/AGENTS.md` (ou `AGENTS.override.md` para substituí-lo temporariamente). Use para as suas preferências pessoais. 2. **Projeto:** da raiz do git até a pasta em que você está, o Codex pega no máximo um arquivo por diretório, checando primeiro `AGENTS.override.md` e depois `AGENTS.md`. Os arquivos são juntados da raiz para baixo, então as instruções de uma subpasta vêm depois e prevalecem sobre as gerais. O tamanho combinado tem limite de 32 KiB por padrão (`project_doc_max_bytes`), mais um motivo para mantê-los enxutos. Como o `AGENTS.md` é um formato compartilhado, outros agentes também o leem; [CLAUDE.md vs AGENTS.md](/pt/blog/claude-md-agents-md/ "CLAUDE.md e AGENTS.md") explica como manter um só conjunto de regras para várias ferramentas. ## Passo 6: config.toml As configurações do Codex ficam em arquivos TOML: - `~/.codex/config.toml` para as suas configurações de usuário; - `.codex/config.toml` dentro de um projeto, que o Codex só carrega depois que você marca o projeto como confiável. Um exemplo pequeno: ```toml model_reasoning_effort = "medium" web_search = "cached" sandbox_mode = "workspace-write" approval_policy = "on-request" [sandbox_workspace_write] network_access = true ``` `model` define o modelo padrão (rode `/model` em uma sessão para ver o que a sua conta oferece). `model_reasoning_effort` controla quanto tempo o modelo pensa. `web_search` pode ser `cached` (o padrão), `live` ou `disabled`; a flag `--search` liga a busca ao vivo em uma execução. As configurações são aplicadas nesta ordem, da maior prioridade para a menor: flags de linha de comando e `-c key=value`, a configuração do projeto, um perfil nomeado escolhido com `--profile`, a configuração do usuário e, por fim, a configuração do sistema. Então `codex -c model_reasoning_effort="high"` muda o esforço em uma execução sem mexer nos seus arquivos. Se não tiver certeza de qual valor venceu, `/debug-config` mostra as camadas. ## Passo 7: conecte servidores MCP O [MCP](/pt/glossary/mcp/ "O que é MCP") permite ao Codex usar ferramentas externas: busca em documentação, um navegador, o seu issue tracker, um banco de dados. Adicione um servidor com um comando: ```bash codex mcp add context7 -- npx -y @upstash/context7-mcp ``` Tudo depois de `--` é o comando que inicia o servidor. Passe variáveis de ambiente com `--env VAR=value`. Para um servidor remoto, use `codex mcp add --url https://...` e, se ele usa OAuth, entre com `codex mcp login `. `codex mcp list` mostra o que está configurado. Os mesmos servidores podem ser escritos à mão no `config.toml`: ```toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] ``` Dentro de uma sessão, `/mcp` lista os servidores ativos e as ferramentas deles. Se a ideia é nova para você, [o que é um servidor MCP](/pt/blog/what-is-mcp-server/ "O que é um servidor MCP") é uma boa introdução. Mantenha a lista curta: cada servidor adiciona descrições de ferramentas à [janela de contexto](/pt/glossary/context-window/ "O que é uma janela de contexto"). ## Passo 8: os comandos que vale conhecer Os comandos de barra funcionam dentro de uma sessão: | Comando | O que faz | | --- | --- | | `/init` | Gera um `AGENTS.md` para o projeto | | `/model` | Escolhe o modelo e o esforço de raciocínio | | `/permissions` | Alterna entre Auto e Read Only | | `/plan` | Planeja primeiro, depois implementa | | `/status`, `/usage` | Detalhes da sessão e limites restantes | | `/compact` | Resume a conversa para liberar contexto | | `/diff` | Mostra o git diff atual | | `/review` | Pede ao Codex para revisar a sua árvore de trabalho | | `/mcp` | Lista servidores MCP e ferramentas | | `/new`, `/clear` | Começa uma conversa nova | | `/resume`, `/fork` | Continua ou ramifica uma sessão anterior | | `/copy` | Copia a última resposta | E alguns subcomandos pelo shell: | Comando | O que faz | | --- | --- | | `codex exec "..."` | Roda uma tarefa sem a interface interativa, para scripts e CI | | `codex review --uncommitted` | Revisa mudanças sem commit (também `--base ` ou `--commit `) | | `codex resume` | Escolhe uma sessão recente para continuar | | `codex fork --last` | Ramifica a sessão mais recente | | `codex -C path/to/dir` | Inicia em outra pasta | | `codex doctor` | Confere a sua instalação | O `codex exec` é o que vale lembrar para automação. Ele imprime o resultado e sai, aceita `--json` para saída legível por máquina e `--output-last-message` para salvar a resposta final em um arquivo. No CI, combine com um sandbox, por exemplo `codex exec --sandbox workspace-write "fix the failing lint errors"`. ## Passo 9: retome e ramifique sessões O Codex guarda as conversas localmente, então fechar o terminal não faz você perder trabalho: - `codex resume` abre um seletor de sessões anteriores. - `codex resume --last` vai direto à mais recente da pasta atual; adicione `--all` para procurar em todas as pastas. - `codex fork` (ou `/fork` em uma sessão) copia uma conversa para uma nova, para você tentar outra abordagem sem perder a original. - Em execuções não interativas, `codex exec resume --last` continua a última sessão de `exec`. Ramificar é útil quando o Codex já montou um bom contexto sobre um problema e você quer testar duas soluções a partir do mesmo ponto. ## Dicas para resultados melhores - **Faça commit antes e depois.** O próprio conselho da OpenAI é criar um checkpoint no git antes e depois de uma tarefa. Se uma mudança der errado, `git restore` é mais rápido do que discutir com o agente. - **Diga como verificar.** “Rode `pnpm test` e corrija as falhas” dá resultados melhores do que “faça funcionar”. - **Planeje mudanças maiores.** Use `/plan` para qualquer coisa que toque mais do que alguns arquivos, e leia o plano antes de o Codex começar a editar. - **Uma tarefa por conversa.** Comece do zero com `/new` entre tarefas sem relação; contexto antigo custa tokens e confunde o modelo. - **Compacte sessões longas.** `/compact` mantém as partes importantes e descarta o resto. - **Use um worktree para trabalho em paralelo.** Dois agentes na mesma pasta sobrescrevem um ao outro. [Git worktrees](/pt/blog/git-worktree-parallel-agents/ "Git worktree para agentes em paralelo") dão a cada um a sua própria cópia. ## Quando um terminal não basta Quando o Codex vira parte do seu dia, você vai querer mais de uma sessão rodando: uma corrigindo um bug, outra escrevendo testes, talvez uma segunda conta quando a primeira bater no limite. É aí que um único terminal fica desajeitado. O AgentVera é um app desktop para macOS, Windows e Linux que roda o Codex (e outros agentes de CLI) em terminais de verdade, lado a lado. Ele usa o login do Codex que você já tem. Veja a página [Codex no AgentVera](/pt/agents/codex/ "Codex no AgentVera") para os detalhes. - **[Workspace](/pt/features/workspace/ "Workspace"):** uma grade de agentes por projeto, de 1×1 a 5×4. Escolha o modelo e o esforço por agente; a lista é lida ao vivo do Codex. Os agentes retomam a conversa depois de reabrir o app. - **Permissões por agente:** escolha Ask, Auto ou Full access ao criar um agente, em vez de lembrar de flags. - **Worktrees:** crie um worktree pelo [painel Git](/pt/features/git-and-github/ "Git e GitHub") e inicie um agente nele com um clique. - **[Troca de conta](/pt/features/account-switching/ "Troca de conta"):** cada conta do Codex tem a própria pasta home, os limites restantes aparecem na barra de status e, no Pro e no Team, uma cadeia de contas passa para a próxima conta quando o limite de 5 horas ou o semanal acaba. - **[Gerenciador de MCP](/pt/features/mcp-manager/ "Gerenciador de MCP"):** configure os servidores MCP uma vez; eles se conectam ao Codex em toda inicialização. - **[Revisão de código](/pt/features/code-review/ "Revisão de código"):** peça a outro agente para revisar o que o Codex mudou antes do merge. A grade, os worktrees, a revisão de código e o gerenciador de MCP estão no plano gratuito. [Baixe o AgentVera](/pt/download/ "Baixar o AgentVera") e teste no seu próprio repositório. ## Conclusão Instale o Codex, rode `codex`, entre com o ChatGPT e comece com uma tarefa pequena e real. Deixe no modo Auto e troque para somente leitura com `/permissions` quando quiser só respostas. Coloque as regras do projeto no `AGENTS.md`, os seus padrões no `config.toml` e adicione servidores MCP só quando precisar. Faça commit antes e depois de cada tarefa, e use `codex resume` para continuar de onde parou. Se você também quer testar o agente do Google, leia [como usar o Gemini CLI](/pt/blog/how-to-use-gemini-cli/ "Como usar o Gemini CLI"). ## Perguntas frequentes **O Codex CLI é gratuito?** Instalar a CLI não custa nada. Para usar, você entra com uma conta do ChatGPT ou uma chave de API da OpenAI. No momento em que escrevo (outubro de 2026), o Codex está incluído no ChatGPT Free, Go, Plus, Pro, Business, Edu e Enterprise, com limites de uso que crescem com o plano. Chaves de API são cobradas por token. **O Codex CLI funciona no Windows?** Sim. Instale pelo PowerShell com o script oficial ou com o npm. No Windows, o Codex usa um sandbox próprio, e dentro do WSL2 usa o sandbox do Linux. Modos de aprovação, AGENTS.md e config.toml funcionam igual em todas as plataformas. **Como impeço o Codex de alterar arquivos?** Rode /permissions e escolha Read Only, ou inicie o Codex com --sandbox read-only. O Codex então pode ler arquivos e responder perguntas, mas pergunta antes de editar qualquer coisa ou rodar comandos que mudam estado. **Onde o Codex CLI guarda as configurações?** As configurações do usuário ficam em ~/.codex/config.toml. Um projeto pode ter o próprio .codex/config.toml, que o Codex só carrega em projetos confiáveis. Flags de linha de comando e -c key=value sobrescrevem os dois em uma única execução. **Como continuo uma sessão anterior do Codex?** Rode codex resume para escolher em uma lista de sessões recentes, ou codex resume --last para ir direto à mais recente na pasta atual. Dentro de uma sessão, /resume faz o mesmo e /fork cria um novo ramo a partir da conversa atual. --- **Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/