⌨️ Terminal e Interface Gráfica

🟢 O que é

Antes do Codex você precisa de Node.js v18 ou superior (que inclui npm) e Git. Versões antigas do Node causam erros silenciosos durante a instalação do Codex.

💡 Por que aprender

O npm é o gerenciador de pacotes que instala o Codex globalmente. Sem Node.js v18+, mesmo o comando de instalação falha com mensagens confusas.

🔑 Instalação por sistema

# Instalar Git
winget install --id Git.Git -e --source winget

# Instalar Node.js (baixe de nodejs.org → LTS)
# Verificar depois:
node -v    # deve ser v18+
npm -v     # deve ser 9+

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git
node -v && npm -v

brew install node git
node -v && npm -v

🟢 O que é

O Codex CLI é distribuído como pacote npm: @openai/codex. A flag -g instala globalmente — disponível em qualquer diretório.

💡 Por que aprender

Instalação global vs local faz diferença: global permite chamar codex de qualquer pasta. Local só funciona dentro do projeto com npx.

🔑 Comandos de instalação

npm install -g @openai/codex
# Verificar instalação:
codex --version

npm update -g @openai/codex

# Se erro EACCES, configure npm prefix:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

⚠️ Erros comuns na primeira execução — e a solução

codex : O arquivo codex.ps1 não pode ser carregado porque a
execução de scripts foi desabilitada neste sistema.
    + FullyQualifiedErrorId : UnauthorizedAccess

# No PowerShell, rode uma vez e confirme com "S":
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# Teste de novo:
codex --version

# Rode o Codex pelo Prompt de Comando (cmd), que
# não passa pela política de execução do PowerShell:
codex --version

# Conferir a política atual, se quiser:
Get-ExecutionPolicy -List

git add skills/minha-skill
git commit -m "Add skill"
git push -u origin main   # ...e nada aparece no GitHub

git status     # 1. os arquivos estão "staged" (verdes)?
git remote -v  # 2. existe 'origin' e a URL está certa?
git branch     # 3. seu branch é 'main' ou 'master'?

# Se ainda não houver remote:
git remote add origin https://github.com/usuario/repo.git

git add .
git commit -m "Add automatic climate dashboard update skill"

# Se o push for rejeitado (remoto à frente):
git pull --rebase origin main
git push -u origin main

# ~/.codex/config.toml — fixa o padrão e evita repetir flags:
approval_policy = "on-request"      # untrusted | on-failure | on-request | never
sandbox_mode    = "workspace-write" # read-only | workspace-write | danger-full-access

🟢 O que é

O login usa device auth: o terminal exibe um código + link. Você abre o link no browser, digita o código e está autenticado. Sem expor API keys no terminal.

💡 Por que aprender

Device auth é seguro mesmo em ambientes compartilhados. O código expira em 15 minutos — abra o link imediatamente.

🔑 Passo a passo

codex login --device-auth

# Saída esperada:
# Abra: https://auth.openai.com/codex/device
# Código: XXXX-XXXX (expira em 15 min)
# ⚠️ NUNCA compartilhe este código
# ✓ Successfully logged in

export OPENAI_API_KEY="sk-..."
codex auth login

🟢 O que é

Após instalar e fazer login, o Codex funciona no terminal com dois modos: interativo (codex) e direto (codex "prompt").

💡 Por que aprender

Modo interativo é ideal para tarefas longas e iterativas. Modo direto é ótimo para scripts e automações em CI/CD.

🔑 Referência rápida

codex                      # modo interativo
codex "crie testes"        # prompt direto
codex chat                 # modo conversa
codex --full-auto "..."    # sem confirmação
codex --model gpt-5 "..."  # modelo específico
codex generate --prompt "..."|# gerar código

🟢 O que é

O Codex App para Windows é a interface gráfica completa: skills com UI, plugins externos, previews inline, múltiplas threads paralelas, aba de Automations e browser integrado.

💡 Por que aprender

A interface gráfica é superior ao CLI para tarefas que envolvem várias threads simultâneas, automações agendadas e uso de browser para computer use.

🔑 Recursos principais

🟢 O que é

O Codex funciona em Docker via device auth. O arquivo ~/.codex/config.toml persiste configurações globais como approval policy e sandbox mode.

💡 Por que aprender

Containers são ideais para usar --dangerously-bypass-approvals com segurança — o sistema host fica protegido. Config.toml evita repetir flags a cada sessão.

🔑 Config.toml e Docker

# Configuração equilibrada (recomendada)
approval_policy = "never"
sandbox_mode = "workspace-write"
model = "gpt-5"

docker run --rm -it \
  -v "$PWD:/app" -w /app \
  node:20 bash
# dentro do container:
npm install -g @openai/codex
codex login --device-auth