OpenAI Codex OAuth

Visão geral

O OAuth do OpenAI Codex permite que você use sua subscription ChatGPT Plus, Pro, Team ou Enterprise para conectar seu agente aos modelos GPT (incluindo GPT-5.4) no QuickClaw, sem precisar de uma API key separada.

O consumo é debitado do rate limit da sua subscription ChatGPT — não dos créditos da API paga.

Quando usar?

Use o OAuth do Codex se você:

• Já assina ChatGPT Plus, Pro, Team ou Enterprise
• Quer aproveitar o rate limit da subscription em vez de pagar a API por token
• Prefere usar GPT-5.4 via Codex (endpoint otimizado para assistentes)

Prefira a API Key tradicional se você:

• Não tem subscription ChatGPT ativa
• Precisa de controle fino sobre gastos (billing por token)
• Usa modelos fora do catálogo Codex (ex: embeddings, legacy)

Pré-requisitos importantes

1. Desabilitar 2FA (temporariamente)

O fluxo OAuth do Codex não é compatível com verificação em duas etapas (2FA / Two-Factor Authentication) da OpenAI no momento. Enquanto o 2FA estiver ativo, você ficará travado na tela de MFA sem conseguir completar o login.

1. Acesse chatgpt.com → Configurações → Segurança
2. Localize a seção "Verificação em duas etapas"
3. Desabilite o toggle (você pode reabilitar depois do login OAuth ser concluído)

2. Habilitar "Autorização por código de aparelho"

Esse é o mecanismo que o QuickClaw usa para autorizar sem depender de servidor local (como o CLI faz no seu terminal). Precisa estar ligado na sua conta.

1. Ainda em Configurações → Segurança
2. Role até a seção "Habilitar autorização por código de aparelho para o Codex"
3. Ligue o toggle (ele fica azul quando ativado)

A seção é próxima ao fim da página, junto com "Entrada segura com o ChatGPT". Se você não encontrar, seu plano ChatGPT pode não ter acesso ao Codex ainda — entre em contato com o suporte do ChatGPT.

Habilitar autorização por código de aparelho para o Codex   [ ON ]
Usar o início de sessão com código de aparelho para
ambientes remotos, sem uma interface gráfica, em que
o fluxo normal pelo navegador não está disponível.

Modelos compatíveis

Modelos OpenAI suportados via OAuth Codex no QuickClaw:

• gpt-5.4 — flagship atual
• gpt-5.4-pro, gpt-5.4-mini, gpt-5.4-nano
• gpt-5.3-codex, gpt-5.3-chat
• gpt-5.2, gpt-5.2-pro, gpt-5.2-codex, gpt-5.2-chat
• gpt-5, gpt-5-mini, gpt-5-nano
• gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
• gpt-4o, gpt-4o-mini
• o4-mini

Método A — Device Code (recomendado)

Login direto pelo dashboard do QuickClaw, sem instalar nada. Você vê um código curto (ex: HWIR-FHBDD), digita na página oficial da OpenAI e pronto — o modal detecta automaticamente a autorização.

Método B — Codex CLI manual (avançado)

Se preferir gerar o token via terminal (útil para automações ou ambientes corporativos com browser restrito), você pode usar o Codex CLI oficial da OpenAI e extrair o refresh_token manualmente.

npm install -g @openai/codex

npm install -g @openai/codex

codex login

{
  "tokens": {
    "access_token": "eyJ...",
    "refresh_token": "rt_7dTlrArz3...",  // ← copie este valor
    "id_token": "eyJ..."
  }
}

Problemas comuns

Página "Iniciar sessão" trava ou não aceita digitar

Provavelmente sua conta tem 2FA ativo. Desabilite temporariamente:

1. Vá em chatgpt.com → Settings → Security
2. Desligue "Two-factor authentication"
3. Refaça o fluxo OAuth no QuickClaw
4. (Opcional) Reabilite o 2FA depois do OAuth funcionar

Erro 404 "device code não habilitado"

Sua conta não tem o toggle de autorização por código de aparelho ativo. Vá em chatgpt.com → Settings → Security e ligue a opção "Habilitar autorização por código de aparelho para o Codex".

Código "ABCD-12345" dá "inválido" na página da OpenAI

O código tem validade de 15 minutos. Se você demorou para digitar, expirou. Feche o modal no QuickClaw e clique em "Conectar com OpenAI" de novo — um código novo é gerado.

Modal fica em "Aguardando..." para sempre

Pode ser que você autorizou em uma conta diferente da que pensou, ou o polling parou por algum motivo. Feche o modal e tente de novo. Se persistir, verifique se está logado na conta correta em chatgpt.com.

Codex CLI não funciona / arquivo auth.json não existe

Se o codex login falhar ou não criar o arquivo, verifique:

• Sua conta ChatGPT precisa ter acesso ao Codex CLI (geralmente Plus+)
• Node.js 18+ instalado (node --version)
• Sem bloqueio de firewall para auth.openai.com

Se nada resolver, use o método A (Device Code) pelo dashboard — mais simples.

Como o QuickClaw usa o token

O QuickClaw armazena o access_token + refresh_token + chatgpt_account_id criptografados no banco. Quando o agente precisa chamar um modelo GPT:

1. O Agent Manager injeta o token em auth-profiles.json dentro do container
2. O pi-ai (engine do OpenClaw) lê o arquivo e adiciona os headers corretos (Authorization: Bearer, chatgpt-account-id, OpenAI-Beta: responses=experimental, etc)
3. A request vai direto para chatgpt.com/backend-api/codex — sem passar pelo proxy
4. Quando o access_token expira (~1h), o pi-ai usa o refresh_token para gerar novo automaticamente
5. O refresh_token é rotacionado (cada refresh gera novo par)
6. O QuickClaw sincroniza o novo refresh_token de volta ao banco via reconcile (5min)

Renovação

Como o refresh_token é rotacionado automaticamente, você geralmente não precisa fazer renovações manuais. Situações em que precisa reconectar:

• Logout manual no ChatGPT ou mudança de senha → refresh_token revogado
• Subscription ChatGPT expirada → token para de funcionar
• OpenAI revoga o token por política → precisa autorizar novamente

Para renovar: clique em Conectar com OpenAI novamente no dashboard. Novo device code é gerado, você autoriza na OpenAI e pronto.