Instale o Codex CLI e faça a primeira execução segura
Guia atual para instalar o Codex CLI, escolher autenticação ou provider personalizado, validar a configuração e fazer uma primeira tarefa segura.
Conteúdo
Para a automação opcional do provider, use os scripts atuais https://www.bettertoken.ai/install-codex-provider.sh e https://www.bettertoken.ai/install-codex-provider.ps1; mantenha valores temporários em TEMP somente quando as instruções atuais exigirem.
Para continuar, use sua própria conta BetterToken e API Key. Criar uma conta BetterToken
O Codex CLI é o agente de programação da OpenAI para o terminal. Você instala um único cliente oficial, codex, e depois escolhe um caminho de acesso: login com ChatGPT, API Key da OpenAI ou um custom provider compatível. Não é preciso instalar um aplicativo Codex diferente para cada provider.
Uma primeira execução segura tem quatro passos: instalar, confirmar codex --version, concluir exatamente um caminho de autenticação ou provider e rodar uma tarefa somente leitura em um repositório de teste. Só depois abra código de produção.
Este guia foi conferido em 21 de agosto de 2026 com o repositório Codex da OpenAI e a documentação Codex da BetterToken. Comandos de instalação e campos de configuração podem mudar; use as fontes primárias vinculadas no momento da configuração.
Se você escolher um custom provider pay-as-you-go, abra o guia atual da BetterToken para Codex, crie sua própria API Key e valide a primeira requisição antes de abrir um repositório de produção. A BetterToken configura o Codex CLI oficial por um custom provider; ela não é outro cliente Codex nem uma assinatura do ChatGPT.
Escolha o método de instalação
| Método | Indicado para | Requisito |
|---|---|---|
| Instalador independente | Instalação direta em macOS, Linux ou Windows | curl ou PowerShell; não requer Node.js |
| Homebrew cask | macOS já gerenciado com Homebrew | Homebrew |
| npm | Ambiente gerenciado com Node.js | Node.js e npm funcionais |
| Binário do GitHub Releases | Instalação manual ou controlada | Gerenciar arquivo e PATH |
O Codex CLI mantido é implementado em Rust. Node.js só é necessário para a instalação por npm ou para um script de provider que o peça explicitamente.
Confira os pré-requisitos
A documentação da OpenAI lista macOS 12+, Ubuntu 20.04+/Debian 10+ e Windows 11 via WSL2 como bases suportadas. Git é recomendado para fluxos com repositórios. O suporte nativo do Windows e os detalhes do sandbox são documentados separadamente e podem evoluir.
Antes de instalar:
- Decida entre autenticação oficial da OpenAI e custom provider.
- Confirme que o terminal consegue atualizar
PATH. - Comece em um repositório de teste, não em um working tree de produção.
- Mantenha API Keys fora de argumentos, arquivos-fonte, capturas de tela e histórico do shell.
Instale o Codex CLI
macOS e Linux: instalador independente
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --versionAbra um novo terminal se o instalador tiver alterado o PATH.
macOS: Homebrew
brew install --cask codex
codex --versionnpm: macOS, Linux ou Windows
npm install -g @openai/codex
codex --versionSe codex não for encontrado, confira o prefixo global real do npm:
npm config get prefixCompare-o com PATH, corrija a configuração comum do Node.js ou do shell e abra outro terminal. Não acrescente um suposto caminho /bin sem conferir o layout real.
Windows e GitHub Releases
O instalador oficial do PowerShell é:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --versionPara desenvolvimento voltado a Linux no Windows, instale o CLI Linux dentro do WSL2 e, quando possível, mantenha projetos no sistema de arquivos do WSL em vez de sob /mnt/. Os releases do Codex também oferecem arquivos por sistema e arquitetura; extraia o binário correto em uma pasta já administrada pelo PATH e verifique a versão.
Escolha exatamente um caminho de acesso
Durante o diagnóstico, não misture estado de login da OpenAI com configuração de custom provider. Primeiro prove um caminho.
Login com ChatGPT
codex login
codex login statusConclua o fluxo no navegador. Em uma máquina sem interface gráfica, siga o procedimento atual da OpenAI para device code ou API Key, em vez de copiar tokens de navegador entre máquinas.
API Key da OpenAI
Guarde a chave em um gerenciador de segredos ou variável de ambiente, nunca como argumento visível. Siga o guia de autenticação da OpenAI para o fluxo suportado e o armazenamento de credenciais. Use codex logout para remover credenciais oficiais salvas.
Custom provider
O custom provider usa o mesmo CLI oficial; a configuração escolhe Base URL, protocolo de API, modelo e a variável de ambiente da chave. A BetterToken documenta uma integração Codex pela API OpenAI Responses. A Base URL atual é https://www.bettertoken.ai/v1; Model IDs e grupos de chaves são dinâmicos e devem ser copiados da interface ou documentação atual.
Antes do teste, remova variáveis OpenAI antigas que possam sobrescrever a configuração pretendida:
unset OPENAI_API_KEY
unset OPENAI_BASE_URLEm seguida, siga o guia atual da BetterToken para Codex. Ele informa os campos atuais de config.toml, wire_api = "responses", a variável da chave, a escolha do modelo e o comando de inicialização. Reinicie o Codex completamente depois de mudar a configuração.
Faça a primeira execução segura
Comece em um repositório não crítico:
git clone https://github.com/openai/codex codex-test
cd codex-test
codex --sandbox read-only "Explain the entry point of this project"A primeira execução está correta quando o Codex inicia pela via escolhida, identifica arquivos relevantes, não modifica arquivos e não pede permissão inesperada de escrita ou execução. Com BetterToken, uma resposta normal do modelo e o registro da requisição, modelo, status e consumo de tokens no Dashboard também confirmam a rota da API.
Faça o diagnóstico por camada
codex: command not found
Abra outro terminal, confirme a conclusão da instalação e verifique o local real. Para npm, use npm config get prefix; para um binário Release, confirme que sua pasta está em PATH.
O navegador não abre
Confirme que há navegador e que o callback não está bloqueado. Em máquina headless, use o caminho documentado de device code ou API Key. Não copie arquivos de autenticação de outra máquina.
O custom provider retorna 401, 403, 404 ou HTML
Confira a variável da chave, conta, provider, Base URL e se uma variável antiga está sobrescrevendo a configuração. Nunca imprima a chave. Para 404 ou HTML, compare a Base URL com os Docs Codex atuais; não reutilize uma Base URL do Claude Code.
model not found ou a alteração não é aplicada
Copie o Model ID da lista atual do provider, não de um artigo ou captura antigo. Pare todos os processos Codex, abra um novo terminal, confira o perfil ou arquivo de configuração ativo e repita uma única tarefa pequena somente leitura. Não altere autenticação, modelo, Base URL e sandbox ao mesmo tempo.
Checklist final
codex --versionretorna uma versão.- Apenas um caminho de autenticação ou provider está ativo no teste.
- Segredos ficam fora do código e do histórico do shell.
- Base URL, protocolo, modelo e variável da chave coincidem com a documentação atual.
- Uma tarefa somente leitura conclui em repositório de teste sem modificar arquivos.
- O uso aparece no Dashboard ou histórico de conta esperado.
Depois disso, abra um repositório real com o menor nível de permissão necessário. Revise comandos e diffs propostos antes de aumentar a autonomia.
