Instalação e Login (Mac / Windows / Linux)

📚 Navegação da Série: O artigo anterior 02 · Visão Geral dos Conceitos Essenciais explicou os conceitos centrais do Codex (Agente, Sandbox, Aprovação, Execução local/nuvem). Este artigo guiará o processo prático de instalação em sua máquina local — cobrindo as linhas de aplicativo desktop e CLI, autorizações de login, particularidades de cada sistema operacional e diagnóstico de problemas comuns. No próximo artigo 04 · Assinatura e Tarifação, detalharemos os custos associados.

A OpenAI estruturou o Codex em quatro interfaces de acesso: versão web, aplicativo desktop, terminal CLI e extensões de IDEs. A experiência prática mostra que as orientações de instalação oficiais frequentemente divergem de tutoriais antigos disponíveis na internet.

Na verdade, o processo de instalação do Codex é simples; a dificuldade reside em filtrar os guias desatualizados das rotas recomendadas atualmente. Este artigo detalha o caminho ideal para cada plataforma de modo a evitar retrabalhos.

Ao terminar de ler este artigo, você terá:

• O passo a passo para instalar o aplicativo desktop e o terminal CLI no macOS, Windows e Linux (com as saídas esperadas para validação)
• Uma comparação entre os três métodos de instalação da CLI (script oficial, Homebrew e NPM), ajudando a escolher a melhor opção
• A diferença entre os dois métodos de autenticação (conta ChatGPT e chave de API) e a resolução padrão para falhas de login em servidores remotos
• Um guia de referência rápida para mensagens de erro comuns e suas respectivas soluções

---

01 Três pontos importantes antes de iniciar

Antes de executar comandos no terminal, valide estes três pontos fundamentais para evitar interrupções no fluxo.

1. Defina a interface de acesso preferencial

Embora o Codex ofereça quatro interfaces, a etapa de instalação se divide em dois caminhos principais:

• Aplicativo Desktop: Interface visual recomendada para desenvolvedores que preferem interagir fora do console. Disponível apenas para macOS e Windows; usuários Linux devem utilizar a CLI.
• Terminal CLI: Assistente executado diretamente no terminal, compatível com os três sistemas operacionais e preferido pela maioria dos programadores.

Recomendação: Desenvolvedores devem priorizar a CLI pela flexibilidade e compatibilidade entre plataformas. Este artigo foca na CLI, com uma seção dedicada ao aplicativo desktop. O status de autenticação é compartilhado entre a CLI e as extensões de IDEs (o aplicativo desktop requer login independente, conforme detalhado na Seção 06).

2. Certifique-se de possuir uma conta ativa

Atenção: O Codex consome as cotas associadas ao plano do ChatGPT.

Planos como Plus, Pro, Business, Edu e Enterprise do ChatGPT já incluem o acesso ao Codex. Também é possível utilizar chaves de API (OpenAI API key) no modelo pague-pelo-que-usar — porém, a autenticação por chave de API desabilita recursos integrados ao espaço de trabalho do ChatGPT (como o Codex em nuvem).

A execução local da CLI com chaves de API funciona normalmente, sendo tarifada de acordo com as regras de consumo de tokens da plataforma de desenvolvedores da OpenAI, de forma independente de planos do ChatGPT.

Detalharemos as regras tarifárias no artigo 04 · Assinatura e Tarifação. Este manual pressupõe que você já possua acesso a uma assinatura do ChatGPT ou a uma chave de API válida.

3. Conexão estável com os servidores da OpenAI

O Codex exige conectividade constante com a infraestrutura da OpenAI. Caso sua rede local possua restrições geográficas ou de firewall para acessar domínios como chatgpt.com ou platform.openai.com, configure as permissões ou proxies necessários de antemão para evitar erros de timeout de download ou falhas de callback de login.

💡 Resumo em uma frase: Antes de instalar, valide: interface CLI (compatibilidade universal), acesso à assinatura ChatGPT ou chave de API e rede estável com os domínios da OpenAI.

---

02 Método 1: Aplicativo Desktop (macOS / Windows)

O aplicativo desktop oferece uma experiência visual ideal para fluxos de trabalho fora do console.

Analogia: uma versão do ChatGPT com suporte a pastas locais. A interface de conversa assemelha-se ao portal web; a diferença reside na capacidade de mapear um diretório da sua máquina para ler códigos, realizar alterações e rodar testes locais — integrando chat, workspace e persistência de dados.

Exemplos de uso prático:

• Gerentes de produto ou designers revisando implementações de layouts diretamente nos arquivos sem usar IDEs.
• Executar tarefas paralelas em diferentes repositórios sem misturar os fluxos do terminal.
• Visualizar diffs de forma interativa por meio de uma interface gráfica de auditoria.

Download e Instalação

Acesse https://chatgpt.com/codex e selecione a versão apropriada:

Sistema Operacional	Download recomendado
macOS (Apple Silicon)	Versão padrão recomendada
macOS (Processadores Intel)	Selecione o pacote Intel build especificamente
Windows	Executável padrão oficial de instalação
Linux	Aplicativo indisponível; use a CLI local

Usuários de macOS: caso tenha dúvidas sobre a arquitetura da CPU, clique no menu da Maçã → "Sobre Este Mac". Processadores da série Apple M indicam arquitetura Apple Silicon; modelos que listam processadores Intel exigem o pacote Intel build.

Login Inicial e Mapeamento de Pastas

Execute os três passos de inicialização:

1. Autenticação: Faça login com suas credenciais do ChatGPT ou chave de API.
2. Diretório: Indique a pasta de trabalho local. Projetos acessados anteriormente pela CLI ou extensões de IDEs constarão no histórico de conexões.
3. Mensagem inicial: Certifique-se de que a opção Local esteja ativa no canto inferior esquerdo para permitir edições locais, e envie a instrução inicial.

Ao abrir o aplicativo pela primeira vez, concentre-se nas abas de conversa e na pasta mapeada: o chat opera como a interface tradicional da OpenAI, enquanto as modificações de arquivos ocorrem estritamente no escopo da pasta indicada.

Configurações de localização podem ser ajustadas no menu do aplicativo. A barra lateral e o console inferior são expansíveis pelos controles visuais superiores. Interface geral do sistema:

💡 Resumo em uma frase: O aplicativo desktop é compatível apenas com macOS e Windows (atenção ao selecionar a arquitetura de chip no macOS). Mapeie a pasta de trabalho e valide o status Local antes de enviar prompts.

---

03 Método 2: Terminal CLI (Instalação via Shell)

Recomendação de instalação: utilize o script oficial de instalação independente (standalone installer). Esse formato instala binários nativos que não exigem a presença do runtime Node.js na máquina.

Analogia: instaladores de pacotes nativos. O instalador oficial baixa, configura os caminhos e roda o binário de forma isolada; gerenciar a ferramenta via pacotes globais de NPM exige ter o ecossistema Node.js instalado e atualizado, adicionando pontos de falhas na manutenção.

macOS / Linux

Execute no terminal:

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

Nota sobre redes com restrições: garanta que proxies ou rotas de rede estejam ativos se houver dificuldades locais em alcançar domínios da OpenAI para evitar falhas de conexão.

Para instalações silenciosas em pipelines de integração contínua (CI/CD) sem avisos manuais, use a flag de ambiente oficial:

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

Windows nativo (sem WSL)

Execute no console do PowerShell:

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

Instalação silenciosa em lote para scripts/CI:

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

A flag -ExecutionPolicy ByPass suspende temporariamente a verificação de assinatura da sessão sem expor as diretivas do sistema local; irm (Invoke-RestMethod) faz o download do script e iex (Invoke-Expression) o executa. Caso retorne erros de comandos não reconhecidos, garanta que esteja executando a instrução em uma janela de PowerShell, não no Prompt de Comando (CMD).

Outros caminhos: Homebrew e NPM

Comparação dos pacotes de gerenciadores alternativos para a CLI:

Gerenciador	Instrução de instalação	Pré-requisito	Recomendação de uso
Script Oficial	curl ... | sh (PowerShell no Windows)	Nenhum	Recomendado por padrão; binário compilado isolado
Homebrew (macOS)	brew install --cask codex	Homebrew ativo	Recomendado se você gerencia as ferramentas locais via Homebrew; as compilações podem ter leve atraso de build
NPM	npm install -g @openai/codex	Node.js instalado	Recomendado se o seu ambiente de desenvolvimento for baseado em NPM global

As atualizações via Homebrew passam por revisões manuais da comunidade, o que pode atrasar a distribuição em relação ao script principal, mas oferece estabilidade para desenvolvedores que evitam compilações do mesmo dia.

Homebrew (macOS):

brew install --cask codex

NPM (qualquer SO, exige Node.js):

npm install -g @openai/codex

Pontos de atenção para instalações alternativas:

• Uso de permissões privilegiadas com sudo no NPM: Evite rodar instalações globais de pacotes com sudo para evitar problemas de permissões no diretório do usuário local. Recomenda-se gerenciar o runtime de Node.js via gerenciadores como nvm ou Volta no escopo do usuário. Se enfrentar falhas de permissão de gravação, priorize o script standalone oficial.
• Sintaxe do Homebrew: Garanta a inclusão do parâmetro --cask na chamada de instalação no macOS; o pacote está registrado com o identificador codex.

💡 Resumo em uma frase: Dê preferência ao script oficial para a CLI (macOS/Linux via curl, Windows via irm). Evite instalações NPM com sudo.

O fluxo abaixo contrasta as etapas de configuração dos dois caminhos de instalação:

O diagrama resume: a rota gráfica (desktop) consome o download do instalador padrão, login via App e conexão local; a rota de linha de comando instala o binário CLI e roda o codex login. Ambas autenticam chaves ou contas e liberam a execução do agente.

---

04 Windows: Execução Nativa versus WSL

O ambiente Windows possui regras específicas para a inicialização dos containers de sandbox.

O Codex oferece três perfis de execução locais no Windows:

• Windows Nativo com Sandbox elevated: Recomendado. Utiliza contas dedicadas de baixa permissão no Windows, contenções do sistema de arquivos e regras ativas de firewall para isolar o Codex na pasta ativa.
• Windows Nativo com Sandbox unelevated: Alternativa de contingência. Indicado caso políticas corporativas de TI bloqueiem credenciais administrativas, oferecendo segurança reduzida mas mantendo a contenção.
• WSL2 (Windows Subsystem for Linux 2): Execução no ambiente virtual de Linux, utilizando sandboxes bubblewrap nativas. Recomendado para repositórios mapeados no WSL2 ou projetos baseados em ferramentas Linux.

Tabela técnica comparativa:

Ambiente	Requisitos técnicos	Cenário de aplicação
Nativo + elevated	Autorização administrativa para criação de perfis de sandbox	Padrão recomendado; melhor performance e segurança local
Nativo + unelevated	Sem exigência de privilégios de administrador	Contingência para restrições de segurança de rede corporativa
WSL2	Ativação do subsistema WSL2 local	Projetos dependentes de runtimes baseados em Linux ou repositórios já localizados no WSL2

Requisitos importantes do sistema:

• Sistemas operacionais: Recomendado o Windows 11. Suporte experimental no Windows 10 a partir da versão 1809 (exigido suporte a componentes modernos de console ConPTY); versões desatualizadas não são homologadas.
• winget: O utilitário nativo de instalação do Windows deve estar configurado no sistema.
• WSL1: Descontinuado a partir da versão 0.115 do Codex devido à adoção do bubblewrap como backend do sandbox de Linux. A compatibilidade é restrita ao WSL2.

Para rodar o Codex no WSL2, inicialize a instalação da distribuição no PowerShell administrativo e instale a CLI dentro da sessão do subsistema:

wsl --install
wsl

Após inicializar a sessão do WSL (terminal Linux):

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

Dica de performance no WSL2: evite mapear repositórios localizados em diretórios nativos do Windows (como /mnt/c/...). O fluxo de I/O em pastas montadas causa lentidão e incompatibilidades de permissões de caminhos de arquivos. Aloje os projetos na home da VM Linux (ex: ~/code/my-app). Acesse os diretórios pelo Windows Explorer usando o atalho \\wsl$.

O fluxo de decisão abaixo auxilia na escolha do perfil no Windows:

O pipeline de escolha é direto: use nativo com perfil elevated; adote unelevated sob restrições administrativas; selecione WSL2 se necessitar da infraestrutura de Linux.

💡 Resumo em uma frase: Windows prioriza execução nativa com sandbox elevated. Adote unelevated em máquinas corporativas travadas ou WSL2 para ferramentas de Linux. O WSL1 não é suportado.

---

05 Validação de Instalação

Concluídas as instalações, abra uma nova janela de terminal para certificar a configuração do binário no sistema:

codex --version

Saída esperada (a numeração do patch varia conforme novas versões globais):

codex-cli 0.139.0

A visualização do status confirma a configuração. Retornos de erros como command not found: codex (ou 'codex' is not recognized no console do Windows) sinalizam falha no mapeamento das variáveis do sistema (PATH), cuja resolução está descrita na Seção 08.

Instruções detalhadas de atualização e consulta de flags estão acessíveis no manual interativo do binário via codex --help. A OpenAI atualiza as ferramentas de linha de comando continuamente; consulte a ajuda da CLI instalada.

A versão do aplicativo desktop consta nos menus visuais de status. Divergências acentuadas entre a build da CLI e do aplicativo desktop podem causar instabilidades em projetos compartilhados.

💡 Resumo em uma frase: Verifique a versão do binário via codex --version. Consulte parâmetros operacionais atualizados rodando codex --help.

---

06 Autenticação e Login

O binário da CLI exige vinculação de contas para inicializar o processamento. Acesse o diretório do repositório e chame o binário:

codex

Na ausência de tokens de login ativos, a CLI iniciará o assistente de login direcionando o fluxo para autenticação no navegador via ChatGPT. O callback retornará os tokens de login diretamente para o console.

Comparativo das opções de autenticação

Opção de Login	Método de autenticação	Cenário indicado	Observações
Conta ChatGPT (Recomendado)	Escolha "Sign in with ChatGPT" e confirme os privilégios no navegador	Desenvolvimento local e consumo do ecossistema em nuvem	Consome as cotas inclusas nos planos ativos do ChatGPT
Chave de API (API Key)	Informe o token de acesso gerado no portal de desenvolvedores da OpenAI	Execução automatizada e scripts de CI/CD	Tarifado sob demanda; desabilita recursos integrados ao workspace do ChatGPT

Para desenvolvimento interativo comum, a autenticação por conta do ChatGPT aproveita as cotas padrão do plano e integra o histórico do workspace. As chaves de API são indicadas para testes automatizados ou scripts executados em terminais sem navegadores locais. Evite expor chaves de API em sistemas de logs públicos.

Armazenamento de credenciais locais

A autenticação persistirá em sua máquina para inicializações diretas subsequentes. Dois pontos a observar:

• Compartilhamento de sessões: A CLI e as extensões de IDEs compartilham a mesma pasta global de credenciais de login. Encerrar a sessão em uma interface desautorizará a outra.
• Local de salvamento: Salvo por padrão no arquivo ~/.codex/auth.json ou no gerenciador de credenciais nativo do sistema operacional (Keychain no macOS). Ajuste pelo parâmetro cli_auth_credentials_store (opções file, keyring ou auto, detalhado no capítulo 18).

⚠️ O arquivo ~/.codex/auth.json aloja os tokens de acesso ativos da sua conta. Trate-o com o mesmo rigor de segurança de senhas: não versione esse arquivo no git ou compartilhe logs desse diretório.

Sessões ativas do ChatGPT contam com atualizações de tokens em segundo plano conduzidas pelo assistente, mitigando a necessidade de reautenticação contínua.

Login em servidores remotos ou ambientes headless

Em ambientes de servidores remotos, sessões SSH sem interface gráfica (headless) ou redes locais com redirecionamentos bloqueados, o login convencional do navegador falhará pela impossibilidade de retornar o callback para o localhost. O caminho recomendado para esses cenários é o login por código de dispositivo (Device Code Login).

Selecione "Sign in with Device Code" na janela interativa ou force pelo comando:

codex login --device-auth

Esse recurso experimental exibe um endereço de autenticação web e um código de verificação temporário. Acesse o endereço em qualquer dispositivo conectado (ex: seu celular ou computador principal) para autorizar a CLI sem necessitar de navegadores no servidor.

O login por código de dispositivo exige habilitação prévia nas configurações da conta. Se o recurso estiver indisponível no perfil, use uma das alternativas a seguir:

1. Migração do arquivo de credenciais: Realize a autenticação codex login em sua máquina de uso diário, copie o arquivo gerado em ~/.codex/auth.json e envie-o ao servidor via SSH no mesmo diretório:

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

2. Redirecionamento de porta via SSH: Mapeie a porta padrão de escuta do callback de login do Codex (porta 1455 por padrão) do servidor remoto para sua máquina local:

ssh -L 1455:localhost:1455 user@remote

Execute a chamada codex login na janela SSH ativa e conclua a autorização no navegador da sua máquina local.

💡 Resumo em uma frase: A autenticação padrão usa a conta do ChatGPT salvando credenciais no arquivo ~/.codex/auth.json. Para servidores, utilize o comando codex login --device-auth ou redirecione a porta 1455 via SSH.

---

07 Prática: Criando o primeiro arquivo com o Codex

Faremos um teste simples em um diretório temporário para validar a comunicação e a escrita de arquivos local.

Passo 1: Crie o diretório de testes e chame o binário:

mkdir codex-test && cd codex-test
codex

A CLI solicitará autenticação na inicialização (conclua conforme a Seção 06). O prompt interativo será exibido após o login.

Passo 2: Envie uma instrução em linguagem natural para criação de código:

在 test.py 里写一个打印 hello world 的函数

Comportamento esperado: por padrão, o Codex opera sob confirmação obrigatória — antes de gravar arquivos ou chamar interpretadores, ele lista as ações propostas no terminal aguardando sua aprovação (opção Yes). Trata-se do fluxo padrão de auditoria do sandbox.

Ao autorizar, o arquivo test.py será gerado. Finalize a sessão usando o atalho Ctrl + C ou digitando o comando /exit.

Passo 3: Estabeleça pontos de controle com Git no diretório de trabalho. Crie a rotina de arquivar o status antes e depois de interações de escrita para reverter alterações caso necessário:

git init
git add -A && git commit -m "codex 动手前的检查点"

Esse teste cobre o fluxo completo de inicialização, prompt, validação de regras de segurança e gravação física. A interrupção no terminal exibindo o plano proposto de modificações dá maior controle e segurança nas execuções.

O diagrama resume as fases do teste inicial:

O ponto central reside no fluxo de aprovação das ações de escrita do sandbox: alterações ocorrem apenas sob confirmação do usuário.

💡 Resumo em uma frase: Inicie o teste criando um diretório vazio, rode codex, envie a instrução e confirme as ações de gravação. Sempre controle os arquivos locais via Git para manter backups seguros.

---

08 Resolução de Problemas Comuns

Caso encontre erros no processo de configuração, consulte a tabela a seguir antes de reinstalar a ferramenta:

Ocorrência no console	Causa técnica do erro	Resolução recomendada
command not found: codex	Pasta do binário não está inclusa nas variáveis globais (PATH)	Adicione o caminho de instalação às variáveis do sistema
'codex' is not recognized (Windows)	O console do Windows não localizou o binário nas variáveis de sistema (PATH)	Configure as variáveis do sistema e reinicie o terminal
irm is not recognized	Comandos do PowerShell executados no Prompt do CMD tradicional	Inicialize uma sessão do PowerShell antes de colar as chamadas
Navegador de login inativo ou falhas de callback	Ambientes remotos, servidores headless ou restrições de proxy local bloqueando a porta 1455	Autentique via comando codex login --device-auth (detalhado na Seção 06)
Timeout no download de scripts de instalação	Conexão de rede bloqueada com a OpenAI	Ative conexões de proxy de rede estáveis ou tente caminhos alternativos como Homebrew
Recursos do ChatGPT desativados com login por chave de API	Restrições estruturais de conformidade para chaves brutas de desenvolvedor	Conclua a autenticação por perfil ativo do ChatGPT
Erros de sandbox 1385 no Windows	Diretivas locais de segurança negando privilégios à conta de sandbox do Codex	Contate a TI para liberar permissões ou alterne para Sandbox unelevated temporariamente
Presença do binário mesmo após desinstalação	Múltiplas builds instaladas em conflito	Identifique as rotas de sistema via which -a codex e delete binários obsoletos

Detalhamento de duas ocorrências frequentes:

1. Comando não encontrado (command not found)

Caso o terminal retorne erros de localização do binário, a causa usual é a ausência da pasta de instalação na variável de ambiente PATH.

Analogia: rotas de endereços de sistema. A instalação física do binário foi concluída, mas o shell local pesquisa executáveis apenas nas rotas cadastradas em suas variáveis globais. Mapear o diretório de destino no PATH indica ao shell onde pesquisar o comando.

Resolução no macOS (utilizando o shell Zsh padrão): identifique a pasta onde o binário foi instalado e cadastre no arquivo de perfil:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

O exemplo pressupõe a instalação no diretório padrão ~/.local/bin. Mapeie o caminho físico indicado pela saída do instalador local. Se estiver no Linux rodando Bash, altere o arquivo de escrita para ~/.bashrc. No Windows, adicione o diretório nas configurações de variáveis de ambiente do usuário e reinicie a sessão de terminal.

Valide novamente:

codex --version

A exibição da versão confirma que o mapeamento funcionou.

2. Conflito entre múltiplas instalações

A instalação simultânea de pacotes globais de NPM e scripts locais standalone pode gerar instabilidades ou inconsistências de versão nas chamadas do console. Verifique as builds instaladas no PATH:

which -a codex

Caso o comando retorne mais de um diretório, mantenha apenas a build recomendada (standalone). Remova as demais. Exemplo para desinstalação do pacote NPM global:

npm uninstall -g @openai/codex

Remover referências antigas do gerenciador global garante que as chamadas mapeiem o executável correto nas variáveis globais, eliminando comportamentos inesperados do console.

💡 Resumo em uma frase: Valide a causa do erro na tabela de diagnósticos antes de reinstalar. Erros de execução inicial costumam ser causados por variáveis de PATH ou conflito de múltiplos pacotes locais. Identifique os binários com which -a codex.

---

09 Resumo

As etapas essenciais deste guia cobriram:

• Verificações Iniciais: Escolha da interface CLI pela compatibilidade universal, plano do ChatGPT ativo ou chave de API, e rede estável com os domínios da OpenAI.
• Métodos de Instalação: Aplicativo desktop apenas no macOS e Windows (identifique a arquitetura do chip no macOS). Script independente recomendado para a CLI (via curl ou irm). Homebrew e NPM são rotas alternativas.
• Particularidades do Windows: Recomendado o modo nativo com sandbox elevated; use unelevated sob restrições corporativas de TI ou configure o WSL2. O suporte ao WSL1 foi descontinuado.
• Autenticação: Login por padrão via conta do ChatGPT salvando credenciais no arquivo ~/.codex/auth.json. Utilize codex login --device-auth para acessos headless ou servidores remotos.
• Diagnóstico de Erros: Erros comuns de console derivam de configurações de PATH ou múltiplas instalações em conflito.

Com essas etapas consolidadas, você está pronto para configurar a ferramenta, validar as permissões locais de sistema, gerenciar chaves e realizar as interações de escrita.

O próximo artigo 04 · Assinatura e Tarifação detalhará o modelo comercial: o volume de cotas em cada plano do ChatGPT, precificação do consumo por chaves de API e custos comparativos com o Claude Code. Conhecer as políticas tarifárias ajuda a otimizar o uso do seu plano.

Para reflexão: A escolha entre login de conta ou chave de API regula não apenas a autenticação, mas a precificação e a disponibilidade de recursos. Esse será o gancho do próximo artigo.

---

Validada a instalação, alinhe os custos e os limites de consumo antes de processar tarefas complexas. Até o próximo capítulo!

---

Leituras Recomendadas

• Regras e Hooks (Rules & Hooks): Inserindo interceptores e triggers no Codex
• Particularidades do Windows: Configuração nativa e via WSL
• Agent Skills: Automatizando rotinas complexas no Codex