Como instalar o Codex CLI e executar a primeira tarefa

O Codex CLI é um agente de programação da OpenAI executado no terminal e escrito em Rust. Ele roda localmente, trabalha com o código do seu repositório e executa tarefas em um ambiente isolado. Há quatro formas de instalá-lo: instalador independente, npm, Homebrew cask ou binário do GitHub Releases.

Depois da instalação, mantenha separados os dois caminhos de conexão: o login oficial da OpenAI, por ChatGPT ou por uma chave da API da OpenAI, e um custom provider com sua própria chave de API. Ambos usam o mesmo comando codex; não existe outro cliente para instalar.

O que você precisa antes de instalar

Requisitos básicos de sistema da documentação oficial de instalação:

• macOS: 12 (Monterey) ou posterior.
• Linux: Ubuntu 20.04+ / Debian 10+.
• Windows: Windows 11 via WSL2; a execução nativa tem documentação própria.

O Node.js é necessário somente para a instalação via npm. O instalador independente, o Homebrew cask e o arquivo do GitHub Releases fornecem um executável pronto para uso.

O login oficial via ChatGPT exige uma conta ChatGPT; o acesso pela API oficial requer uma chave de platform.openai.com. Para usar um custom provider, você precisa da sua própria conta BetterToken, uma chave de API exclusiva e o Model ID atual. O Node.js só é necessário para instalar o Codex via npm ou executar o script automático de configuração do provider.

Como instalar o Codex CLI

macOS e Linux — instalador independente

É a opção mais simples e não exige Node.js:

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

Quando a instalação terminar, verifique o comando:

codex --version

Se aparecer um número de versão, o comando está disponível.

O Codex já está instalado? Conecte sua chave de API seguindo o guia atual. Consulte primeiro a documentação vigente e depois crie uma conta BetterToken caso ainda não tenha sua própria chave.

macOS — Homebrew cask

brew install --cask codex

npm — macOS, Linux e Windows

É necessário ter Node.js e npm funcionando. Confira a versão mínima do Node.js no campo engines do pacote em npmjs.com/@openai/codex.

npm install -g @openai/codex

Se o comando codex não for encontrado após a instalação, o diretório global do npm não está no seu PATH. Descubra o prefixo correto:

npm config get prefix

Compare esse diretório com o PATH do seu shell e reinicie o terminal. Não acrescente /bin sem verificar: a localização dos executáveis globais depende do sistema operacional e da forma como o Node.js foi instalado.

Linux — binário do GitHub Releases

Os arquivos prontos para Linux estão disponíveis em github.com/openai/codex/releases:

• codex-x86_64-unknown-linux-musl.tar.gz — para x86_64
• codex-aarch64-unknown-linux-musl.tar.gz — para arm64

Extraia o arquivo, renomeie o executável para codex e mova-o para um diretório do PATH no qual você tenha permissão de escrita.

Windows

O Codex CLI pode rodar nativamente no Windows ou dentro do WSL2. A documentação atual para Windows recomenda o Windows 11 para a execução nativa; uma instalação totalmente atualizada do Windows 10 tem suporte em regime de best effort.

Windows nativo (PowerShell). Instalador oficial:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Na execução nativa, o Codex isola as tarefas com o Windows Sandbox. O modo é definido em ~/.codex/config.toml:

[windows]
sandbox = "elevated"

• "elevated": recomendado; usa um usuário dedicado para o sandbox e regras de firewall.
• "unelevated": aplica restrições de ACL ao usuário atual, sem criar um usuário dedicado.

WSL2. Instale a versão Linux do Codex CLI dentro do WSL2 seguindo as instruções para Linux. Para ferramentas Linux, a OpenAI recomenda manter o projeto no sistema de arquivos do WSL, e não em /mnt/.

Como conectar o mesmo Codex CLI à API da BetterToken

A BetterToken não substitui o Codex CLI por outro aplicativo. O executável oficial codex continua sendo usado, enquanto um custom provider direciona as solicitações do Codex à OpenAI Responses pela Base URL `https://www.bettertoken.ai/v1%60.?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk

Siga estas três etapas sem misturar a autenticação oficial com a chave do custom provider.

Etapa 1. Crie sua conta e sua chave exclusiva

Crie uma conta BetterToken e sua própria API Key. Não reutilize uma chave compartilhada e não coloque o segredo no texto do artigo, em screenshots, no repositório ou na linha de comando.

Etapa 2. Consulte a documentação atual e prepare a configuração

Abra o guia atual da BetterToken para Codex, escolha a superfície que você realmente usa e copie o Model ID e os campos do provider exibidos na documentação vigente. Pare completamente qualquer processo do Codex antes de aplicar alterações.

O Model ID, os campos de autenticação e o local de armazenamento das credenciais podem mudar conforme a superfície e a versão do cliente. Por isso, este artigo não fixa um Model ID, valores booleanos de autenticação nem combina o login oficial com o custom provider no mesmo exemplo. Use os placeholders e valores mostrados no guia atual.

Etapa 3. Remova conflitos, aplique a configuração e teste

Primeiro, remova variáveis antigas da OpenAI que possam sobrescrever a configuração escolhida.

macOS e Linux:

unset OPENAI_API_KEY
unset OPENAI_BASE_URL

Windows PowerShell:

Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")

Aplique os campos e o Model ID copiados da documentação atual. Se preferir o script automático, lembre-se de que ele configura apenas o provider da BetterToken; não instala o Codex CLI. O script exige Node.js. Quando a chave ou o modelo não são fornecidos como argumentos, ele solicita os dados em um terminal interativo, portanto não coloque o segredo na linha de comando.

macOS e Linux:

curl -fsSL https://www.bettertoken.ai/install-codex-provider.sh?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk | bash

Windows PowerShell:

iwr https://www.bettertoken.ai/install-codex-provider.ps1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"

Depois de aplicar a configuração, reinicie totalmente o Codex. Execute uma tarefa pequena e somente leitura e confira no Dashboard da BetterToken se uma nova solicitação aparece com o modelo, o status e o uso de tokens de entrada, saída e cache esperados. Uma resposta normal, sozinha, não comprova qual rota processou a solicitação.

Passe segredos apenas pelo método indicado na documentação atual, nunca pelo texto do artigo ou pela linha de comando.

Autenticação oficial da OpenAI

Os comandos abaixo se aplicam à rota oficial da OpenAI. Com o custom provider da BetterToken, codex login status não verifica a API da BetterToken: execute uma tarefa de teste e confira o Dashboard.

Entrar com o ChatGPT

Execute:

codex login

O navegador será aberto. Conclua o login com sua conta ChatGPT. O Codex salva a sessão localmente, portanto não será necessário entrar novamente nas próximas execuções.

Se você executar codex sem argumentos antes de se autenticar, a interface também solicitará o login. O comando principal para iniciar esse processo é codex login.

Entrar com uma chave de API

Não passe a chave como argumento do comando nem a mostre com echo: o valor acabará no histórico do shell.

Defina OPENAI_API_KEY no ambiente atual ou por meio de um gerenciador de segredos. Não coloque o valor no artigo, no comando nem na saída. Depois de definir a variável, passe-a por stdin:

printenv OPENAI_API_KEY | codex login --with-api-key

O valor da chave não é exibido na tela nem entra no histórico de comandos.

Verificar a autenticação

Depois do login, confira o status:

codex login status

O comando mostra o método de autenticação atual ou informa que você não está conectado.

Se o status indicar que não há autenticação, repita o login pelo método adequado.

Para sair e remover as credenciais salvas:

codex logout

O arquivo ~/.codex/auth.json contém o token de acesso e deve ser tratado como uma senha. Não o exclua manualmente: use sempre codex logout para limpar as credenciais.

Documentação de autenticação: developers.openai.com/codex/auth. Referência dos subcomandos e parâmetros de login: developers.openai.com/codex/cli/reference.

Sua primeira tarefa em um repositório de teste

Comece em um repositório de teste para não afetar código de trabalho. Clone qualquer repositório público; por exemplo, o próprio Codex:

git clone https://github.com/openai/codex codex-test
cd codex-test

Execute uma tarefa somente leitura:

codex --sandbox read-only "Explain the entry point of this project"

A opção --sandbox read-only limita os comandos gerados pelo modelo a operações de leitura. Se o Codex retornar uma descrição coerente da estrutura sem alterar arquivos, a primeira execução foi concluída.

Para continuar na TUI com a mesma restrição, execute:

codex --sandbox read-only

Digite na interface: What files are in this project and what does each do?

Se você estiver usando a rota oficial da OpenAI, confirme que a autenticação continua ativa:

codex login status

Se estiver usando o provider da BetterToken, uma resposta normal não basta para confirmar a rota. Abra também o Dashboard da BetterToken e verifique se a solicitação, o modelo, o status e o uso de tokens de entrada, saída e cache aparecem no histórico depois do teste.

Solução de problemas

codex: command not found após instalar com npm

Execute npm config get prefix, compare o resultado com o PATH e reinicie o terminal. O caminho exato do executável depende do sistema operacional e da forma de instalação do Node.js, portanto não acrescente /bin sem verificar.

O navegador não abriu durante o login com ChatGPT

Em um servidor remoto sem interface gráfica, tente primeiro o fluxo oficial por código de dispositivo (beta):

codex login --device-auth

Primeiro, é necessário habilitá-lo nas configurações de segurança do ChatGPT ou nas permissões do workspace. Se ele não estiver disponível, use o login por chave de API:

printenv OPENAI_API_KEY | codex login --with-api-key

O guia oficial de autenticação explica callback, código de dispositivo e opções alternativas.

O Codex não responde após conectar a BetterToken

Confira cinco pontos: base_url é https://www.bettertoken.ai/v1%60,?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk wire_apipermaneceresponses, o Model ID foi copiado da lista atual da BetterToken, model_providercorresponde exatamente à tabela de provider indicada no guia vigente, e as variáveis antigasOPENAI_API_KEYouOPENAI_BASE_URL` não estão sobrescrevendo a configuração. Depois de editar a configuração, reinicie o Codex completamente em um novo terminal.

codex login status mostra Not logged in

• Login via ChatGPT: execute codex login novamente e conclua o acesso no navegador.
• Login por chave de API: confirme que OPENAI_API_KEY está definida no ambiente atual e repita printenv OPENAI_API_KEY | codex login --with-api-key.
• Não exclua ~/.codex/auth.json manualmente; use codex logout.

---

Documentação do Codex CLI: developers.openai.com/codex/cli. Conecte o mesmo Codex CLI à API da BetterToken: docs.bettertoken.ai/en/ai-tools/codex.