Ao final deste capítulo você terá o Codex CLI instalado e autenticado no seu computador, a extensão do Codex funcionando no seu editor e um arquivo de configuração próprio, com modelo, nível de raciocínio e perfis definidos por você. No capítulo anterior vimos o que o Codex é e quais são as três formas de uso. Agora vamos colocar duas delas para funcionar: o terminal e o editor.
O que você precisa antes de instalar
A lista é curta. Primeiro, uma conta da OpenAI com plano pago do ChatGPT ou uma chave de API com crédito. Segundo, o Git instalado, porque o Codex trabalha melhor dentro de repositórios e usa o histórico para entender o que mudou. Terceiro, um terminal que você já saiba abrir: Terminal ou iTerm no macOS, qualquer emulador no Linux, e no Windows o PowerShell ou o Subsistema Windows para Linux, conhecido pela sigla WSL.
Se você for instalar pelo npm, que é o gerenciador de pacotes do Node, precisa também do Node.js em versão recente, versão vinte e dois ou superior. Para conferir, rode no terminal o comando node --version. Se aparecer algo abaixo disso, instale uma versão mais nova antes de continuar.
Instalando o Codex CLI
Existem três caminhos. Escolha um só.
O primeiro é o npm, que funciona igual nos três sistemas operacionais:
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
npm install -g @openai/codexO segundo é o Homebrew, gerenciador de pacotes muito usado no macOS e disponível também no Linux:
brew install codexO terceiro é baixar o binário pronto da página de lançamentos do projeto no GitHub, escolher o arquivo do seu sistema e da sua arquitetura, descompactar e colocar o executável em uma pasta que esteja no PATH. O PATH é a lista de diretórios onde o sistema procura programas quando você digita um nome no terminal. No macOS e no Linux, uma escolha comum é a pasta /usr/local/bin, e nesse caso você precisa dar permissão de execução ao arquivo com o comando chmod +x. Lembre que copiar algo para essa pasta costuma exigir permissão de administrador, com sudo, e que o arquivo descompactado traz o nome do sistema e da arquitetura, então renomeie-o para codex antes de usar. Esse caminho é útil em servidores e em máquinas onde você não quer instalar o Node.
Terminada a instalação, verifique com um comando simples:
codex --versionSe o número da versão aparecer, está tudo certo. Se aparecer uma mensagem de comando não encontrado, o problema é quase sempre de PATH, e vamos tratar disso mais adiante.
Fazendo login
Com o programa instalado, falta autenticar. O jeito mais simples é entrar com a conta do ChatGPT. Rode:
codex loginO Codex abre uma página no seu navegador para você confirmar a conta e volta ao terminal com a sessão pronta. Se você estiver em uma máquina remota sem navegador, o próprio comando oferece um endereço para abrir em outro computador.
A alternativa é usar uma chave de API, cobrada por uso. Nesse caso você pode fazer:
codex login --api-key SUA_CHAVE_AQUITrate a chave como uma senha. Não a cole em arquivos que vão para o repositório e prefira guardá-la em uma variável de ambiente chamada OPENAI_API_KEY. E atenção: uma chave digitada direto na linha de comando fica registrada no histórico do terminal, então o mais seguro é defini-la na variável de ambiente, ou apagar essa linha do histórico depois e revogar a chave no painel da OpenAI se houver qualquer dúvida. As credenciais autenticadas ficam em um arquivo dentro da pasta oculta .codex, no seu diretório de usuário. Para sair da conta, existe o comando codex logout.
Primeiro comando de teste
Não teste em um projeto importante. Crie uma pasta vazia, entre nela e inicie um repositório Git:
mkdir teste-codex
cd teste-codex
git initAgora inicie o Codex e faça um pedido pequeno:
codexQuando a interface abrir, digite algo como: crie um arquivo chamado ola.py que imprima a mensagem olá mundo e explique o que você fez. O agente vai propor a criação do arquivo, mostrar o diff e pedir sua confirmação. Aceite, e confira depois com ls e cat ola.py que o arquivo realmente existe. Esse teste confirma três coisas ao mesmo tempo: instalação, autenticação e permissão de escrita na pasta.
Vale conhecer também a forma de uma linha só, útil para pedidos rápidos. Ela abre a sessão já com o pedido enviado; se você quiser a resposta impressa direto no terminal, sem interface e sem interação, use o subcomando codex exec com o mesmo texto:
codex "resuma em três linhas o que este projeto faz"A extensão para o editor
A extensão dá acesso ao mesmo agente sem sair do editor, com os diffs aparecendo lado a lado com o seu código. A instalação no VS Code segue o caminho de sempre: abra o painel de extensões, procure por Codex da OpenAI, clique em instalar. Editores derivados do VS Code, como Cursor e Windsurf, aceitam a mesma extensão pela loja compatível deles.
Depois de instalar, abra o painel do Codex na barra lateral e clique para entrar. Use exatamente a mesma conta que você usou no terminal. A extensão e a CLI compartilham a autenticação e a maior parte da configuração, então você não precisa manter duas contas nem dois conjuntos de preferências. Para conferir, abra uma pasta de projeto no editor e peça no painel uma explicação de qualquer arquivo. Se a resposta citar nomes reais do seu código, a conexão está funcionando.
O arquivo de configuração
O comportamento padrão do Codex vem de um arquivo chamado config.toml, guardado na pasta .codex do seu diretório de usuário. TOML é um formato de configuração simples, feito de chaves e valores. Se o arquivo não existir, crie-o. Quatro ajustes cobrem quase tudo o que um iniciante precisa.
O primeiro é o modelo, que define qual modelo de raciocínio será usado. O segundo é o nível de raciocínio, ou esforço de raciocínio, que regula quanto o modelo pensa antes de responder. Níveis baixos são rápidos e baratos, bons para perguntas simples. Níveis altos demoram mais e custam mais, e compensam em tarefas difíceis de arquitetura ou depuração. O terceiro é a política de aprovação, que determina se o agente pergunta antes de agir. O quarto é o modo de sandbox, que define o que ele pode tocar. Esses dois últimos são o assunto inteiro do capítulo quatro, então aqui apenas os registramos no arquivo.
model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"Os nomes dos modelos mudam com o tempo. Para ver os valores aceitos na sua versão, use o comando /model dentro de uma sessão, que mostra as opções disponíveis e troca o modelo na hora sem editar arquivo nenhum, ou consulte a documentação oficial do Codex.
A seguir vêm os perfis. Um perfil é um conjunto nomeado de configurações que você ativa quando quer. Isso evita ficar reescrevendo o arquivo para cada tipo de tarefa.
[profiles.leitura]
model_reasoning_effort = "low"
sandbox_mode = "read-only"
[profiles.profundo]
model_reasoning_effort = "high"
approval_policy = "on-request"Para usar um deles, basta chamar o Codex assim:
codex --profile leituraNa prática, um perfil de leitura barato e sem permissão de escrita serve para explorar repositórios, e um perfil profundo serve para bugs cabeludos. Vale saber que o Codex lê a configuração apenas do config.toml que fica na pasta .codex do seu diretório de usuário: não existe um config.toml por projeto. Quando a equipe quiser padronizar algo, use um arquivo AGENTS.md no repositório para as instruções e passe as preferências na própria chamada, com --profile ou com opções de configuração na linha de comando.
Problemas comuns de instalação
Os tropeços são quase sempre os mesmos e todos têm solução simples.
| Sistema | Sintoma | Causa e solução |
|---|---|---|
| Windows | Comando não reconhecido no PowerShell | A pasta global do npm não está no PATH. Reabra o terminal depois de instalar e, se persistir, adicione a pasta de pacotes globais do npm às variáveis de ambiente. Se algo travar por política de execução de scripts, prefira rodar o Codex dentro do WSL. |
| macOS | Erro de permissão negada durante a instalação | Evite instalar pacotes globais com sudo. Use o Homebrew ou um gerenciador de versões do Node, como o nvm, que instala tudo na sua própria pasta de usuário. |
| Linux | Versão do Node muito antiga ou binário que não executa | Os repositórios oficiais costumam trazer versões velhas. Instale pelo nvm. No caso do binário baixado à mão, falta permissão de execução, resolvida com chmod mais x. |
Duas dicas fecham a lista. No Windows, o Codex funciona melhor no WSL, porque muitos comandos que o agente quer executar são comandos de Linux; se você trabalha com projetos que dependem de ferramentas de linha de comando, essa escolha poupa horas. E no macOS com processador da linha Apple, confira se a pasta de binários do Homebrew, em opt barra homebrew barra bin, está no PATH, porque em instalações antigas ela não entra sozinha.
Recapitulando
Você instalou o Codex CLI por npm, Homebrew ou binário, verificou a versão, autenticou com a conta do ChatGPT ou com uma chave de API e rodou um primeiro pedido em uma pasta de teste. Instalou a extensão no VS Code ou em um editor compatível e ligou a mesma conta, aproveitando a autenticação compartilhada. Criou o config.toml com modelo, nível de raciocínio, política de aprovação e modo de sandbox, e aprendeu a separar preferências em perfis chamados pela opção --profile. Por fim, viu que a maioria dos erros de instalação se resume a PATH, permissões e versão do Node, e que no Windows o WSL é o caminho mais tranquilo.
