Codex CLI: como começar e configurar o uso em equipe

Reserve os primeiros 15 minutos para a configuração, supondo que você já tenha um projeto funcionando e uma conta com acesso. A instalação, o login ou uma suíte de testes lenta podem levar mais tempo. Um bom primeiro resultado é uma pequena alteração verificada ou uma explicação precisa do que impede sua conclusão. Comandos conferidos em 11 de outubro de 2026.

Codex CLI: da instalação à primeira tarefa útil

O Codex trabalha dentro do seu projeto: ele pode examinar arquivos, editá-los e executar ferramentas instaladas na sua máquina. Pense nele como alguém da equipe trabalhando em uma bancada separada. Você define a tarefa e os limites; a decisão de incorporar o resultado ao produto continua sendo sua. Guia da CLI da OpenAI

Do minuto 0 ao 3: escolha uma forma de instalar

No macOS ou Linux, este é o comando do instalador independente:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Se outra opção se encaixar melhor no seu ambiente, use-a. Escolha um único método para saber como atualizar depois.

No Windows, a documentação fornece este comando exato para executar em uma nova janela do PowerShell: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex".

Essas são as opções de instalação da documentação atual da CLI e do repositório oficial. Antes de iniciar o Codex, abra a pasta do projeto no terminal.

Do minuto 3 ao 5: entre com ChatGPT ou chave de API

Na primeira sessão interativa, use o login com ChatGPT se o seu plano e workspace oferecerem acesso. Execute codex login e conclua as etapas no navegador. Ao iniciar codex sem um login existente, a opção Sign in with ChatGPT também aparece.

Escolha a autenticação por chave de API quando quiser usar sua conta da OpenAI Platform, por exemplo, em fluxos programáticos. Com OPENAI_API_KEY já definida no ambiente do shell, o comando documentado para macOS/Linux é printenv OPENAI_API_KEY | codex login --with-api-key. Não coloque a chave nos arquivos do repositório.

Execute codex login status para confirmar qual método está ativo. Isso faz diferença no uso em equipe: a autenticação pelo ChatGPT segue os controles do workspace do ChatGPT; a autenticação por API segue os controles da organização na API. Guia de autenticação

Custo: o login com ChatGPT usa o acesso incluído no seu plano elegível; o uso por chave de API é cobrado separadamente pela OpenAI Platform, conforme as tarifas da API. Consulte nosso guia de preços do Codex para comparar os planos. Em um teste com a equipe, compare o tempo de execução manual da tarefa com o tempo gasto em prompts, revisão e correções. Depois, desconte o custo adicional de uso do valor do tempo efetivamente economizado. Uma primeira versão mais rápida só compensa quando diminui o trabalho total necessário para aprová-la. Como a OpenAI diferencia autenticação e cobrança

Do minuto 5 ao 8: examine o projeto antes de editar

Primeiro, crie um ponto de restauração no Git. No shell, dentro do projeto, inicie uma sessão de análise com o comando documentado codex --sandbox read-only --ask-for-approval on-request.

Peça uma investigação com escopo definido. Por exemplo, adapte este prompt ao seu projeto:

Esse prompt é uma sugestão de fluxo de trabalho, não um comando especial do Codex. Leia a resposta e confirme se ele encontrou a parte certa da aplicação. A sandbox de somente leitura permite examinar arquivos e executar comandos dentro dos seus limites; ações fora desses limites podem exigir aprovação. Guia de aprovações e sandbox

Do minuto 8 ao 12: autorize uma pequena alteração

Quando estiver pronto, use /permissions para habilitar a edição no workspace. Para uma nova sessão, a combinação documentada é codex --sandbox workspace-write --ask-for-approval on-request.

Em seguida, defina um critério de aceitação:

Comece por algo que você consiga avaliar rapidamente. Um teste de comportamento conhecido é uma primeira tarefa melhor do que um pedido aberto para melhorar a arquitetura.

Do minuto 12 ao 15: confira o diff e as evidências

Use /diff para examinar a alteração e /review para solicitar uma revisão. Confira a saída real dos testes, os arquivos modificados e se a mudança atende ao critério de aceitação. Só faça o commit depois da sua própria revisão. Esses comandos com barra devem ser usados dentro da sessão do Codex, não no shell. Referência de comandos da CLI

Crie uma referência inicial antes de trocar de modelo

Comece com o modelo disponível na sessão. Depois, use /model para escolher outro modelo ou ajustar o esforço de raciocínio. O exemplo atual da OpenAI para iniciar uma sessão é codex --model gpt-6.1-sol.

A recomendação atual é GPT-6.1 Sol para programação complexa, quando sua conta e seu cliente tiverem acesso, e GPT-6 Luna para tarefas específicas e repetíveis. Um esforço de raciocínio maior pode ajudar em análises difíceis, mas também demora mais e consome mais tokens. Ao comparar resultados, mantenha a mesma tarefa inicial e a mesma configuração de esforço. Orientações sobre modelos do Codex

Durante a adoção pela equipe, registre o modelo usado junto com a tarefa e o resultado dos testes. Selecionar o nome de um modelo não libera o acesso a ele na conta.

Configure o acesso da sandbox e as aprovações separadamente

A sandbox define o que os comandos podem acessar. A política de aprovação define quando o Codex precisa pedir autorização antes de agir. Pense na sandbox como as paredes de uma sala de trabalho e na política de aprovação como a autorização para abrir uma porta.

Use on-request no trabalho interativo: ações permitidas dentro da sandbox podem prosseguir, enquanto ações que precisam de acesso mais amplo podem gerar um pedido de aprovação. never significa que o Codex não pode pedir aprovação; isso não remove a sandbox. Uma ação bloqueada pode continuar bloqueada.

Um limite de escrita não garante um pedido de autorização antes de cada edição. Com workspace-write e on-request, o Codex pode alterar arquivos do workspace e executar comandos permitidos automaticamente. Consulte as configurações ativas com /permissions. Como funcionam a sandbox e as aprovações da OpenAI

Se um modelo antigo de configuração da equipe definir approval_policy = "untrusted", atualize-o: a OpenAI descontinuou essa configuração explícita e informa que ela pode impedir a inicialização. O antigo caminho codex exec --full-auto também está obsoleto. Use as configurações documentadas de sandbox e aprovação. Orientações atuais de migração

Registre os acordos de trabalho no AGENTS.md

Use AGENTS.md para não precisar repetir como o repositório funciona. O Codex lê essas instruções no início de cada execução. O comando /init pode gerar uma estrutura inicial, que um mantenedor deve revisar antes de a equipe passar a usá-la como referência.

Um arquivo útil para o repositório responde a quatro perguntas:

• Como instalar as dependências e executar o projeto?
• Quais testes e verificações se aplicam a cada alteração?
• Quais diretórios contêm arquivos gerados ou exigem cuidado especial?
• O que deve constar no relatório de conclusão, como mudanças de comportamento, testes executados e falhas ainda não resolvidas?

Registre os comandos e as convenções reais do projeto, não uma lista genérica de desejos. Mantenha as preferências pessoais em ~/.codex/AGENTS.md e versione as orientações compartilhadas na raiz do projeto.

O Codex carrega as orientações globais e depois percorre o caminho da raiz do projeto até o diretório atual. As instruções mais locais têm precedência sobre as anteriores; no mesmo diretório, AGENTS.override.md tem prioridade sobre AGENTS.md. Reinicie a sessão depois de alterar as instruções e peça ao Codex um resumo das orientações que ele carregou. Regras de descoberta do AGENTS.md

Trate esse arquivo como um manual para quem contribui com o projeto. Para impor restrições técnicas, use a configuração e os requisitos gerenciados.

Mantenha o config.toml enxuto e fácil de revisar

Guarde suas configurações pessoais padrão em ~/.codex/config.toml. Coloque os padrões compartilhados do projeto em .codex/config.toml, que o Codex só carrega em projetos confiáveis. Esses arquivos usam TOML, um formato de texto que associa nomes a valores de configuração.

Este exemplo inicial reúne os valores apresentados no guia de configuração da OpenAI. Inclua a linha do modelo apenas se ele estiver disponível para sua conta:

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

As flags da CLI e os valores definidos por --config têm precedência sobre a configuração do projeto. As configurações de um projeto confiável têm prioridade sobre os perfis selecionados e seus padrões de usuário. Os requisitos da organização podem limitar o que é permitido, independentemente desses padrões. Noções básicas de configuração

web_search = "cached" seleciona resultados de busca na web em cache. Essa configuração é independente do acesso à rede pelos comandos do shell. O download de uma dependência pode precisar de aprovação mesmo quando o Codex tem uma ferramenta de busca na web. Deixe essa distinção clara nas orientações de entrada na equipe, em vez de ampliar as permissões sempre que um comando falhar.

Adicione um servidor MCP quando houver uma necessidade concreta

MCP, sigla de Model Context Protocol, conecta o Codex a ferramentas e contextos externos. Um servidor local roda como um processo; um servidor remoto é acessado por um endereço HTTP. Adicione um quando a tarefa precisar de informações ou ações que o repositório não oferece.

O exemplo da documentação da OpenAI é codex mcp add context7 -- npx -y @upstash/context7-mcp. Ele inicia um servidor de documentação por meio do npx, que precisa estar disponível. Execute codex mcp list para ver os servidores configurados e, dentro de uma sessão, use /mcp para examinar as conexões ativas. Para um servidor compatível com OAuth, use codex mcp login <server-name>, substituindo o marcador pelo nome configurado.

A configuração do servidor fica em [mcp_servers.<server-name>], no mesmo sistema de configuração TOML. A equipe pode restringir as ferramentas expostas com enabled_tools e disabled_tools; a lista de bloqueio é aplicada depois da lista de permissões. Comece com o menor conjunto de ferramentas que seja útil. Configuração e ajustes de MCP

Para a questão específica de respostas muito grandes das ferramentas, leia nosso guia sobre limites de saída de MCP no Codex CLI. Conectar um servidor e controlar o volume de saída que ele retorna são decisões diferentes de configuração.

Use worktrees quando as tarefas precisarem de checkouts separados

Uma worktree do Git dá à tarefa um checkout separado do repositório. Ela é útil quando você quer manter as alterações de um experimento separadas dos arquivos em que está trabalhando.

A versão 0.154.0 da OpenAI adicionou worktrees gerenciadas para tarefas da CLI, sessões interativas e forks. Na implementação, elas dependem do recurso experimental worktrees e ficam restritas a sessões locais. Habilite esse recurso com codex features enable worktrees, usando o comando documentado da CLI para ativar recursos, e depois inicie com codex --worktree. Notas da versão, implementação de worktrees interativas, comandos de recursos

Dentro de uma sessão compatível, /worktree permite iniciar uma conversa ou criar um fork em um checkout gerenciado. O fork leva consigo o histórico da conversa; uma nova conversa começa do zero. Essas opções exigem que o recurso esteja habilitado e que haja um repositório Git local. Comandos de sessão para worktrees

Planeje fazer a revisão, a integração e a limpeza por conta própria. A implementação da CLI mantém desativada a limpeza automática dos checkouts que gerencia. Um checkout separado também não substitui as configurações de sandbox nem a revisão antes do merge. Ciclo de vida dos checkouts gerenciados

Consulte nosso guia de worktrees no Codex CLI quando estiver pronto para trabalhar com tarefas em paralelo. Para a primeira tarefa de criação de testes, um único checkout basta.

Seis tarefas úteis para uma equipe pequena, em ordem de prioridade

Estas são sugestões de tarefas, não resultados medidos de produtividade. Comece por aquela cujo critério de aceitação seja mais fácil de conferir.

O Codex não preenche lacunas nas decisões de produto nem prova que uma suíte de testes aprovada cobre todos os riscos. Seus critérios de aceitação e sua revisão continuam fazendo parte do trabalho. Para uma avaliação mais ampla, leia nossa análise do Codex; para comparar opções de compra, consulte Codex vs Claude Code.

Duas ferramentas de escopo definido que um fundador técnico pode criar

A oportunidade mais promissora é um serviço de testes de regressão para uma única stack. Venda alterações de testes já revisadas para equipes pequenas com bugs conhecidos e baixa cobertura. A menor versão útil recebe um caso reproduzível, executa uma tarefa delimitada do Codex em um checkout separado e devolve a alteração com evidências dos testes. A estimativa de palavras-chave do DataForSEO para os EUA, consultada em 11 de outubro de 2026, é de 880 buscas mensais por “automated software testing services.” Isso mede o interesse nesse tipo de serviço, não a disposição de comprar esse produto. A parte difícil está nas fixtures confiáveis e nas asserções relevantes; um teste que apenas repete a implementação agrega pouco valor.

A segunda opção é um assistente de revisão específico para um repositório. Uma liderança de engenharia poderia pagar por revisões que apliquem as convenções documentadas da equipe e entreguem uma lista curta de problemas verificáveis. Comece com um repositório, seu AGENTS.md e uma execução de revisão que possa ser repetida. A mesma consulta de demanda estima 1,300 buscas mensais nos EUA por “ai code review.” O desafio está na diferenciação: o Codex já revisa código, então o produto precisa tornar os apontamentos mais pertinentes e reduzir os falsos alarmes. A geração de testes oferece uma entrega inicial mais clara, porque quem compra pode examinar e executar o que recebe.

Dúvidas frequentes na configuração

Na segunda-feira, peça a um mantenedor que execute a mesma tarefa pequena com duas pessoas da equipe, registre o esforço de revisão e correção e ajuste as instruções compartilhadas nos pontos em que a passagem do trabalho falhar. Amplie o uso só depois que a equipe conseguir repetir esse ciclo com confiança.

Se você quer um fluxo de trabalho para o repositório baseado nesses controles, criamos sistemas de IA para produção.