Autenticação OAuth

O ChatCLI suporta autenticação via OAuth 2.0 com PKCE e Device Flow (RFC 8628) para provedores que oferecem essas opções. Isso permite que você use seu plano existente (como ChatGPT Plus, Codex, Claude Pro ou GitHub Copilot) diretamente no terminal, sem precisar gerar ou colar chaves de API.

Métodos de Autenticação

Método	Descrição	Quando Usar
Chave de API	Variável de ambiente no `.env` (ex: `OPENAI_API_KEY`)	Acesso programático, CI/CD, API Keys da plataforma
OAuth (login interativo)	Comando `/auth login` no terminal	Planos ChatGPT Plus/Codex, Claude Pro, sem gerenciar keys

Os dois métodos podem coexistir. O ChatCLI prioriza credenciais OAuth quando ambas estão disponíveis.

Suporte OAuth por provedor:

Com suporte a OAuth: OpenAI (ChatGPT Plus/Codex), Anthropic (Claude Pro) e GitHub Copilot (Device Flow).
Apenas chave de API: GoogleAI, xAI, ZAI, MiniMax, Moonshot (Kimi), StackSpot e Ollama. Para esses provedores, configure a chave via variável de ambiente no .env ou use /auth set.

Comandos `/auth`

Todos os comandos de autenticação possuem auto-completação — basta digitar /auth e pressionar Tab.

Ver Status

/auth status

Exibe o status de autenticação de todos os provedores configurados, incluindo tipo de credencial (API Key vs OAuth), validade do token e origem.

/auth login openai-codex
/auth login anthropic
/auth login github-copilot
/auth login github-models

Navegador abre automaticamente

O navegador abre na página de login do provedor.

Autorize o acesso

OpenAI: um servidor HTTP local captura o callback automaticamente (porta 1455).Anthropic: um servidor HTTP local em localhost:<porta-aleatória>/callback captura o código automaticamente. Após autorizar, o navegador é redirecionado para a página de sucesso oficial do Anthropic e o terminal completa o login. Se o servidor local não puder iniciar (porta indisponível, firewall) ou se CHATCLI_ANTHROPIC_LEGACY_OAUTH=1 estiver definido, o ChatCLI cai automaticamente no fluxo legado de copiar e colar o código.GitHub Copilot: insira o código do dispositivo exibido no terminal na página do GitHub.

Provedor disponível imediatamente

O provedor aparece imediatamente no /switch — sem reiniciar o app.

Provedores Suportados

Provedor	Comando	Planos Compatíveis
OpenAI	`/auth login openai-codex`	ChatGPT Plus, Codex, Team, Enterprise
Anthropic	`/auth login anthropic`	Claude Pro, Team
GitHub Copilot	`/auth login github-copilot`	Copilot Individual, Business, Enterprise
GitHub Models	`/auth login github-models`	Qualquer conta GitHub (PAT) — detalhes

Logout

/auth logout openai-codex
/auth logout anthropic
/auth logout github-copilot

Remove as credenciais OAuth armazenadas para o provedor específicado.

Detalhes Técnicos dos Fluxos OAuth

Esta seção descreve como cada fluxo OAuth funciona internamente, incluindo URLs, parâmetros e comportamento do ChatCLI.

Anthropic OAuth (PKCE + Callback Localhost, com fallback para paste)

O fluxo da Anthropic usa OAuth 2.0 com PKCE (Proof Key for Code Exchange) e um servidor HTTP local em localhost:<porta-aleatória>/callback para capturar o código de autorização — o mesmo padrão usado pelo Claude Code CLI. O fluxo legado de copiar e colar o código permanece disponível como fallback automático.

Fluxo primário (callback local)

Geração do PKCE e início do servidor local

O ChatCLI gera um code_verifier aleatório, calcula o code_challenge usando SHA-256 (método S256), e sobe um servidor HTTP em uma porta aleatória de localhost. Um state de 32 bytes (base64url, 43 caracteres) é gerado para proteção CSRF.

Abertura do navegador

O navegador abre na URL de autorização da Anthropic com code=true, o PKCE challenge, o state e o redirect_uri apontando para o servidor local.

Usuário autoriza no navegador

O usuário faz login no Claude e autoriza o acesso. O navegador é redirecionado para http://localhost:<porta>/callback?code=...&state=....

Validação CSRF e troca de tokens

O servidor local valida o state recebido contra o gerado, troca o código por tokens via platform.claude.com/v1/oauth/token e encerra o servidor. O navegador é redirecionado para a página de sucesso oficial do Anthropic (platform.claude.com/oauth/code/success).

Fluxo de fallback (copiar e colar)

Acionado automaticamente quando o servidor local não consegue se vincular à porta (firewall, porta em uso) ou quando CHATCLI_ANTHROPIC_LEGACY_OAUTH=1 é definido explicitamente.

Abertura do navegador no fluxo legado

O ChatCLI abre a URL de autorização legada (console.anthropic.com como redirect_uri).

Usuário copia o código

Após autorizar, a página do console exibe um código no formato código#state. O usuário cola o texto completo no terminal — o ChatCLI separa código e state automaticamente.

Troca do código por tokens

O ChatCLI envia código, state e code_verifier para o endpoint de tokens e recebe access_token + refresh_token.

Parâmetro	Valor
Auth URL (primário)	`https://claude.com/cai/oauth/authorize`
Auth URL (fallback)	`https://claude.ai/oauth/authorize`
Token URL (primário)	`https://platform.claude.com/v1/oauth/token`
Token URL (fallback)	`https://console.anthropic.com/v1/oauth/token`
Redirect URI (primário)	`http://localhost:<porta-aleatória>/callback`
Redirect URI (fallback)	`https://console.anthropic.com/oauth/code/callback`
Página de sucesso	`https://platform.claude.com/oauth/code/success?app=claude-code`
Client ID	`9d1c250a-e61b-44d9-88ed-5944d1962f5e`
Scopes	`org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload`
PKCE Method	`S256` (SHA-256 code challenge)
Tamanho do `state`	32 bytes (base64url, 43 caracteres)

Validações silenciosas do claude.ai — o fluxo primário só funciona se três parâmetros estiverem corretos. Caso contrário, a página de autorização retorna apenas “Invalid request format” sem código de erro:

code=true deve estar presente na query string
state deve ter exatamente 32 bytes (43 caracteres base64url) — state de 16 bytes é silenciosamente rejeitado
A URL de autorização deve ser claude.com/cai/oauth/authorize (faz 307 para claude.ai/oauth/authorize, e o redirect define cookies que a SPA precisa)

A troca e o refresh de tokens usam um http.Client puro (sem transporte customizado) com header User-Agent: claude-cli/2.1.2 (external, cli) para evitar fingerprinting TLS pelo Cloudflare. Usar um HTTP client com LoggingTransport causa rejeição pela CDN da Anthropic.

O refresh tenta primeiro platform.claude.com e cai automaticamente para console.anthropic.com/v1/oauth/token se o token tiver sido emitido pelo fluxo legado de paste.

OpenAI Codex OAuth (PKCE + Callback Localhost)

O fluxo da OpenAI usa OAuth 2.0 com PKCE e um servidor HTTP local para capturar o callback automaticamente.

Servidor local inicia na porta 1455

O ChatCLI inicia um servidor HTTP em http://localhost:1455 para receber o callback OAuth.

Navegador abre na página de autorização

O navegador abre na URL de autorização da OpenAI com o PKCE challenge e um parâmetro state para validação CSRF.

Usuário autoriza no navegador

Após login e autorização, o navegador redireciona para http://localhost:1455/auth/callback com o código de autorização.

Validação CSRF e troca de tokens

O servidor local válida o parâmetro state contra o valor gerado originalmente (proteção CSRF), troca o código por tokens e encerra o servidor.

Parâmetro	Valor
Auth URL	`https://auth.openai.com/oauth/authorize`
Token URL	`https://auth.openai.com/oauth/token`
Redirect URI	`http://localhost:1455/auth/callback`
Client ID	`app_EMoamEEZ73f0CkXaXp7hrann` (sobrescrevível via `CHATCLI_OPENAI_CLIENT_ID`)
Scopes	`openid profile email offline_access`
PKCE Method	`S256`

O refresh de tokens é automático e utiliza o HTTP client padrão com logging.

GitHub Copilot Device Flow (RFC 8628)

O GitHub Copilot usa o Device Authorization Grant (RFC 8628), um fluxo projetado para dispositivos sem navegador integrado, como terminais CLI.

Requisição do device code

O ChatCLI solicita um device_code e um user_code ao endpoint do GitHub.

Exibição do código no terminal

O ChatCLI exibe o user_code e a URL de verificação (https://github.com/login/device) para o usuário.

Usuário autoriza no navegador

O usuário acessa a URL, insere o user_code e autoriza o acesso do ChatCLI.

Polling até autorização

O ChatCLI faz polling no endpoint de tokens a cada 5 segundos até receber o access token ou um erro terminal.

Parâmetro	Valor
Device Code URL	`https://github.com/login/device/code`
Token Polling URL	`https://github.com/login/oauth/access_token`
Client ID	`Ov23lifEydOk2Non90tJ` (sobrescrevível via `CHATCLI_COPILOT_CLIENT_ID`)
Scope	`read:user`
Timeout máximo	15 minutos

Respostas do polling:

Resposta	Ação
`authorization_pending`	Continua polling normalmente
`slow_down`	Aumenta o intervalo em +5 segundos
`expired_token`	Falha — o device code expirou
`access_denied`	Falha — o usuário negou acesso

Tokens do GitHub Copilot são não-expirantes e não possuem refresh token. São persistentes até revogação manual na página de configurações do GitHub.

Fluxo Completo: Do Zero ao Primeiro Prompt

Se você está começando sem nenhuma credencial configurada, siga estes passos:

Inicie o ChatCLI

Funciona mesmo sem credenciais configuradas.

chatcli

Faça login via OAuth

/auth login openai-codex

Autorize no navegador

O navegador abre automaticamente na página de login do provedor.

Troque para o provedor

/switch

Envie seu primeiro prompt

Olá, como você está?

Roteamento Automático de Endpoints (OpenAI)

O ChatCLI detecta automaticamente o tipo de credencial e roteia as requisições para o endpoint correto:

Credencial	Endpoint	API Format
`OPENAI_API_KEY`	`api.openai.com/v1/responses`	Responses API (padrão)
`OPENAI_API_KEY`	`api.openai.com/v1/chat/completions`	Chat Completions (modelos legados)
OAuth (`/auth login`)	`chatgpt.com/backend-api/codex/responses`	Responses API (streaming SSE)

Você não precisa configurar nada — o roteamento é automático baseado no tipo de token.

Armazenamento de Credenciais

As credenciais OAuth são salvas com criptografia AES-256-GCM em:

~/.chatcli/auth-profiles.json

Detalhes de Criptografia

Aspecto	Detalhe
Algoritmo	AES-256-GCM (authenticated encryption)
Arquivo da chave	`~/.chatcli/.auth-key` (32 bytes aleatórios)
Permissão da chave	`0o600` (somente leitura/escrita pelo dono)
Formato criptografado	`chatcli-enc:v1:` + Base64(nonce + ciphertext)
Geração da chave	Automática na primeira utilização

A chave de criptografia é gerada automaticamente e armazenada em ~/.chatcli/.auth-key. Dados não-criptografados de versões anteriores são detectados automaticamente (ausência do prefixo chatcli-enc:v1:) e migrados para o formato criptografado na próxima gravação. Cada perfil armazenado contém:

Access token (criptografado)
Refresh token (criptografado, quando aplicável)
Expiry (timestamp em milissegundos)
Account ID e email do provedor
Tipo de provedor (anthropic, openai-codex, github-copilot)

Para personalizar o diretório de armazenamento, defina a variável de ambiente:

export CHATCLI_AUTH_DIR="~/.config/chatcli/auth"

Validação de Tokens

O ChatCLI implementa validação rigorosa de tokens OAuth para prevenir uso de credenciais inválidas ou expiradas:

Validação de Access Token

Rejeição de tokens vazios — Tokens com access token vazio são rejeitados imediatamente, sem tentar fazer requests. Isso previne erros confusos de “unauthorized” quando as credenciais estão corrompidas.
Validação de expiração — O campo expiry é verificado antes de cada request. Tokens expirados disparam o fluxo de refresh automaticamente.

Tempo de Vida Máximo de Token (CHATCLI_MAX_TOKEN_LIFETIME)

Para ambientes de produção com requisitos de conformidade, você pode limitar o tempo de vida máximo de tokens:

# Limitar tokens a 24 horas (padrão: 720h / 30 dias)
export CHATCLI_MAX_TOKEN_LIFETIME=24h

Quando o tempo de vida máximo é atingido, o token é invalidado e o usuário precisa fazer login novamente via /auth login. Isso garante rotação periódica de credenciais mesmo quando o refresh token ainda é válido.

Variável	Descrição	Padrão
`CHATCLI_MAX_TOKEN_LIFETIME`	Tempo de vida máximo de tokens OAuth/JWT. Aceita durações Go (ex: `24h`, `168h`).	`720h` (30 dias)

Renovação Automática de Tokens

O ChatCLI renova tokens expirados automaticamente em duas camadas:

Renovação Proativa

Ao resolver credenciais para um request, o ChatCLI verifica se o token está expirado (IsExpired()) ou prestes a expirar (IsExpiringSoon() com margem de 5 minutos). Se sim, o refresh é executado antes do request.

Renovação Reativa

Se um request retornar erro HTTP 401, o ChatCLI invalida o cache de credenciais, executa o refresh do token, recria o cliente HTTP e retenta o request automaticamente — tudo transparente para o usuário.

A margem de segurança de 5 minutos antes da expiração real evita race conditions em que o token expira entre a verificação e o envio do request.

Tokens do GitHub Copilot (Device Flow) não expiram e não possuem refresh token — são persistentes até revogação manual.

Sincronização com CLIs Externos

O ChatCLI pode importar credenciais de CLIs externos via SyncExternalCliCreds():

CLI Externo	Caminhos Verificados	Perfil Importado
Claude Code	`~/.claude/credentials.json` ou `~/.claude.json`	`anthropic-oauth-sync`
OpenAI Codex CLI	`~/.codex/credentials.json` ou `~/.codex/auth.json`	`openai-codex-sync`

A importação só ocorre se as credenciais externas forem mais recentes que as já armazenadas. Isso garante que um login feito diretamente no ChatCLI não seja sobrescrito por dados antigos de outro CLI.

Prioridade de Resolução de Credenciais

Ao determinar qual credencial usar para um provedor, o ChatCLI segue está ordem de prioridade:

Auth-profiles store (OAuth/Token)

Credenciais OAuth armazenadas em auth-profiles.json, incluindo perfis sincronizados de CLIs externos. O refresh automático é aplicado nesta camada.

Variáveis de ambiente

Variáveis como ANTHROPIC_OAUTH_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY e GITHUB_COPILOT_TOKEN.

Sistema de prefixos: o valor das credenciais pode incluir prefixos que indicam o tipo ao provedor:

Prefixo	Significado
`oauth:`	Token obtido via fluxo OAuth
`apikey:`	Chave de API tradicional
`token:`	Token genérico (ex: Copilot)

Configuração Avançada

Variável	Descrição
`CHATCLI_OPENAI_CLIENT_ID`	Permite sobrescrever o client ID do OAuth da OpenAI
`CHATCLI_COPILOT_CLIENT_ID`	Permite sobrescrever o client ID do Device Flow do GitHub Copilot (padrão: `Ov23lifEydOk2Non90tJ`)
`COPILOT_API_BASE_URL`	URL base da API do Copilot para ambientes enterprise (padrão: `https://api.githubcopilot.com`)
`CHATCLI_ANTHROPIC_LEGACY_OAUTH`	Quando definido como `1`, força o fluxo legado de copiar e colar o código no `/auth login anthropic`, ignorando o callback local. Útil em ambientes onde o `localhost` não é acessível (containers, SSH sem port-forward, firewall restritivo).

Solução de Problemas

Erro de autenticação ao clicar no link OAuth (OpenAI)

Verifique se a porta de callback não está em uso por outra aplicação. O servidor de callback da OpenAI precisa da porta 1455 para capturar o retorno.

Anthropic: callback local não funciona ou navegador trava em localhost

O fluxo primário usa um servidor HTTP local em localhost:<porta-aleatória>/callback. Se sua porta estiver bloqueada por firewall ou se você estiver em um ambiente sem localhost acessível (containers, sessões SSH sem port-forward), force o fluxo legado de paste:

export CHATCLI_ANTHROPIC_LEGACY_OAUTH=1
/auth login anthropic

No fluxo legado, o navegador abre na página do console que exibe o código no formato código#state. Copie o texto completo (incluindo a parte após o #) e cole no terminal — o ChatCLI separa código e state automaticamente.

Anthropic: página de autorização retorna "Invalid request format"

O claude.ai valida silenciosamente três parâmetros do fluxo primário e retorna apenas “Invalid request format” se algum estiver errado:

code=true ausente na query string
state com tamanho diferente de 32 bytes (43 caracteres base64url)
URL de autorização diferente de claude.com/cai/oauth/authorize

Se você modificou o código da função loginAnthropicLocalhost, verifique esses três pontos antes de qualquer outra coisa.

Anthropic: erro 403 ou conexão recusada na troca de tokens

Isso geralmente ocorre quando um HTTP client customizado (com LoggingTransport) é usado. O ChatCLI usa um http.Client puro para a troca de tokens da Anthropic, evitando fingerprinting TLS pelo Cloudflare. Se você estiver desenvolvendo, certifique-se de que a função exchangeAnthropicToken usa um client sem transporte customizado.

Provedor não aparece no /switch após login

GitHub Copilot: authorization denied by user

Certifique-se de que sua conta GitHub possui uma assinatura ativa do Copilot (Individual, Business ou Enterprise). Verifique em https://github.com/settings/copilot se o Copilot está habilitado.

GitHub Copilot: device code expirado

O device code tem validade limitada. Se o polling exceder 15 minutos sem autorização, o código expira. Execute /auth login github-copilot novamente para gerar um novo código.

Token expirado

Os tokens OAuth são renovados automaticamente de duas formas:

Proativamente: ao resolver credenciais, se o token estiver expirado ou dentro da margem de 5 minutos, o refresh é tentado antes do request.
Reativamente: se um request retornar erro 401, o ChatCLI invalida o cache de credenciais, tenta renovar o token OAuth, recria o cliente e retenta o request automaticamente.

Se ambas as tentativas falharem (ex: refresh token também expirado), faça login novamente com /auth login.Tokens do GitHub Copilot (Device Flow) não expiram e não possuem refresh token — são persistentes até revogação manual.

Próximos Passos

Referência de Comandos

Lista completa de todos os comandos disponíveis.

Configuração (.env)

Todas as variáveis de ambiente disponíveis.

Uso Básico

Aprenda os fundamentos do ChatCLI.

​Métodos de Autenticação

​Comandos /auth

​Ver Status

​Login via OAuth

​Provedores Suportados

​Logout

​Detalhes Técnicos dos Fluxos OAuth

​Anthropic OAuth (PKCE + Callback Localhost, com fallback para paste)

​Fluxo primário (callback local)

​Fluxo de fallback (copiar e colar)

​OpenAI Codex OAuth (PKCE + Callback Localhost)

​GitHub Copilot Device Flow (RFC 8628)

​Fluxo Completo: Do Zero ao Primeiro Prompt

​Roteamento Automático de Endpoints (OpenAI)

​Armazenamento de Credenciais

​Detalhes de Criptografia

​Validação de Tokens

​Validação de Access Token

​Tempo de Vida Máximo de Token (CHATCLI_MAX_TOKEN_LIFETIME)

​Renovação Automática de Tokens

Renovação Proativa

Renovação Reativa

​Sincronização com CLIs Externos

​Prioridade de Resolução de Credenciais

​Configuração Avançada

​Solução de Problemas

​Próximos Passos

Referência de Comandos

Configuração (.env)

Uso Básico

Métodos de Autenticação

Comandos `/auth`

Ver Status

Login via OAuth

Provedores Suportados

Logout

Detalhes Técnicos dos Fluxos OAuth

Anthropic OAuth (PKCE + Callback Localhost, com fallback para paste)

Fluxo primário (callback local)

Fluxo de fallback (copiar e colar)

OpenAI Codex OAuth (PKCE + Callback Localhost)

GitHub Copilot Device Flow (RFC 8628)

Fluxo Completo: Do Zero ao Primeiro Prompt

Roteamento Automático de Endpoints (OpenAI)

Armazenamento de Credenciais

Detalhes de Criptografia

Validação de Tokens

Validação de Access Token

Tempo de Vida Máximo de Token (CHATCLI_MAX_TOKEN_LIFETIME)

Renovação Automática de Tokens

Sincronização com CLIs Externos

Prioridade de Resolução de Credenciais

Configuração Avançada

Solução de Problemas

Próximos Passos