xAI Grok OAuth (SuperGrok / X Premium+)

O Hermes Agent suporta o xAI Grok por um fluxo de login OAuth com código de dispositivo no navegador, contra o accounts.x.ai, usando uma assinatura SuperGrok (grok.com) ou uma assinatura X Premium+ (conta do X vinculada). Nenhuma XAI_API_KEY é necessária — entre uma vez e o Hermes renova a sua sessão em segundo plano automaticamente.

Quando você entra com uma conta do X que tem Premium+, a xAI vincula automaticamente o status da assinatura à sua sessão xAI, então o fluxo OAuth funciona igual ao de quem assina o SuperGrok direto.

O transporte reaproveita o adaptador codex_responses (a xAI expõe um endpoint no estilo Responses), então raciocínio, chamada de ferramentas, streaming e cache de prompt funcionam sem nenhuma mudança no adaptador.

O mesmo token bearer do OAuth também é reaproveitado por toda interface direta com a xAI no Hermes — TTS, geração de imagem, geração de vídeo e transcrição — então um único login cobre as quatro.

Visão geral

Item	Valor
ID do provedor	xai-oauth
Nome exibido	xAI Grok OAuth (SuperGrok / X Premium+)
Tipo de autenticação	Código de dispositivo OAuth 2.0 no navegador
Transporte	API Responses da xAI (codex_responses)
Modelo padrão	grok-4.6
Endpoint	https://api.x.ai/v1
Servidor de autenticação	https://accounts.x.ai
Exige variável de ambiente	Não (XAI_API_KEY não é usada por este provedor)
Assinatura	SuperGrok ou X Premium+ — veja a nota abaixo

Pré-requisitos

• Python 3.9+
• Hermes Agent instalado
• Uma assinatura SuperGrok ativa na sua conta xAI, ou uma assinatura X Premium+ na conta do X com que você entrar (a xAI vincula a assinatura automaticamente)
• Um navegador disponível em qualquer lugar onde você consiga abrir a URL de verificação impressa

A xAI pode restringir o acesso à API por OAuth conforme a faixa

O backend da xAI aplica a própria lista de permissões na superfície de API por OAuth e já foi visto rejeitando assinantes SuperGrok comuns com HTTP 403 (veja a issue #26847) mesmo com a assinatura ativa no aplicativo. Se o login OAuth der certo no navegador mas a inferência devolver 403, defina XAI_API_KEY e mude para o caminho por chave de API (provider: xai) — essa superfície não está sujeita à mesma restrição hoje.

Início rápido

# Abra o seletor de provedor e modelo
hermes model
# → Escolha "xAI Grok OAuth (SuperGrok / X Premium+)" na lista de provedores
# → O Hermes abre ou imprime uma URL de verificação do accounts.x.ai
# → Digite o código exibido, se pedirem, e então aprove o acesso no navegador
# → Escolha um modelo (o grok-4.6 está no topo)
# → Comece a conversar

hermes

Depois do primeiro login, as credenciais ficam guardadas em ~/.hermes/auth.json e são renovadas automaticamente antes de expirar.

Fazer login na mão

Dá para disparar o login sem passar pelo seletor de modelo:

hermes auth add xai-oauth

Sessões remotas / sem interface

Em servidores, contêineres, consoles só de navegador (Cloud Shell, Codespaces, EC2 Instance Connect) ou sessões SSH em que o Hermes não consegue abrir um navegador local, o Hermes imprime a URL de verificação da xAI e o código de usuário. Abra a URL em qualquer navegador no seu notebook ou no console de nuvem, digite o código se pedirem, e o Hermes fica consultando até a xAI aprovar o login. Nenhum túnel SSH nem ouvinte de callback local é necessário.

hermes auth add xai-oauth --no-browser
# Abra no seu navegador a URL de verificação impressa.

O mesmo fluxo de código de dispositivo vale quando você entra pelo painel web ou pelo aplicativo desktop: o Hermes mostra a URL de verificação e o código de usuário, e depois consulta em segundo plano até você aprovar o acesso.

Como o login funciona

1. O Hermes pede um código de dispositivo ao auth.x.ai.
2. Você abre a URL de verificação, entra na sua conta, digita o código exibido se pedirem, e aprova o acesso.
3. O Hermes consulta a xAI até a aprovação e então salva os tokens em ~/.hermes/auth.json.
4. Daí em diante, o Hermes renova o token de acesso em segundo plano — você fica logado até rodar hermes auth logout xai-oauth ou revogar o acesso nas configurações da sua conta xAI.

Conferir o status do login

hermes doctor

A seção ◆ Auth Providers vai mostrar o estado atual de cada provedor, incluindo o xai-oauth.

Trocar de modelo

hermes model
# → Escolha "xAI Grok OAuth (SuperGrok / X Premium+)"
# → Escolha na lista de modelos (o grok-4.6 está fixado no topo)

Ou defina o modelo direto:

hermes config set model.default grok-4.6
hermes config set model.provider xai-oauth

Referência de configuração

Depois do login, o ~/.hermes/config.yaml vai conter:

model:
  default: grok-4.6
  provider: xai-oauth
  base_url: https://api.x.ai/v1

Aliases do provedor

Todos os seguintes resolvem para xai-oauth:

hermes --provider xai-oauth        # canônico
hermes --provider grok-oauth       # alias
hermes --provider x-ai-oauth       # alias
hermes --provider xai-grok-oauth   # alias

Ferramentas diretas com a xAI (TTS / Imagem / Vídeo / Transcrição / Busca no X)

Depois que você está logado por OAuth, toda ferramenta direta com a xAI reaproveita o mesmo token bearer automaticamente — não existe configuração separada, a não ser que você prefira usar uma chave de API.

Para escolher um backend para cada ferramenta:

hermes tools
# → Text-to-Speech       → "xAI TTS"
# → Image Generation     → "xAI Grok Imagine (image)"
# → Video Generation     → "xAI Grok Imagine"
# → X (Twitter) Search   → "xAI Grok OAuth (SuperGrok / X Premium+)"

Se já houver tokens OAuth guardados, o seletor confirma isso e pula o pedido de credencial. Se nem o OAuth nem a XAI_API_KEY estiverem definidos, o seletor oferece um menu de 3 opções: login por OAuth, colar chave de API ou pular.

A geração de vídeo vem desligada por padrão

O conjunto de ferramentas video_gen vem desabilitado por padrão. Habilite em hermes tools → 🎬 Video Generation (aperte espaço) antes de o agente poder chamar video_generate. Do contrário o agente pode recorrer à skill do ComfyUI que vem junto, que também está marcada para geração de vídeo.

A busca no X liga sozinha quando há credenciais da xAI

O conjunto de ferramentas x_search liga sozinho sempre que credenciais da xAI (um token OAuth de SuperGrok / X Premium+ ou uma XAI_API_KEY) estão configuradas. Desligue explicitamente por hermes tools → 🐦 X (Twitter) Search (aperte espaço) se você não quiser isso. A ferramenta passa pela API Responses x_search embutida da xAI — funciona tanto com o seu login OAuth de SuperGrok / X Premium+ quanto com uma XAI_API_KEY paga, e prefere o OAuth quando os dois estão configurados (usa a cota da sua assinatura em vez de gasto de API). O esquema da ferramenta fica escondido do modelo quando não há credenciais da xAI configuradas, independentemente de o conjunto de ferramentas estar habilitado.

Modelos

Ferramenta	Modelo	Observações
Chat	grok-4.6	Padrão; fixado no topo do seletor OAuth
Chat	grok-build-0.1	Modelo Grok Build, voltado a programação
Chat	grok-4.3	Geração anterior
Chat	grok-4.20-0309-reasoning	Variante com raciocínio
Chat	grok-4.20-0309-non-reasoning	Variante sem raciocínio
Chat	grok-4.20-multi-agent-0309	Variante multiagente
Imagem	grok-imagine-image	Padrão; ~5–10 s
Imagem	grok-imagine-image-2.0	Ciente de tipografia/layout; melhor qualidade; ~10–20 s
Imagem	grok-imagine-image-quality	Fidelidade maior; ~10–20 s
Vídeo	grok-imagine-video	Texto para vídeo
Vídeo	grok-imagine-video-1.5-preview	Imagem para vídeo; alias com data grok-imagine-video-1.5-2026-05-30
TTS	(voz padrão)	Endpoint /v1/tts da xAI

O catálogo de chat é derivado ao vivo do cache local do models.dev; lançamentos novos da xAI aparecem automaticamente assim que esse cache atualiza. O grok-4.6 fica sempre fixado no topo da lista.

Variáveis de ambiente

Variável	Efeito
XAI_BASE_URL	Sobrescreve o endpoint padrão https://api.x.ai/v1 (raramente necessário).

Para escolher a xAI como provedor ativo, defina model.provider: xai-oauth no config.yaml (use hermes setup para o fluxo guiado) ou passe --provider xai-oauth em uma invocação única.

Resolução de problemas

O token expirou — não faz login de novo automaticamente

O Hermes renova o token antes de cada sessão e de novo, reativamente, num 401. Se a renovação falhar com invalid_grant (o token de renovação foi revogado, ou a conta foi rotacionada), o Hermes exibe uma mensagem tipada de reautenticação em vez de quebrar.

Quando a falha de renovação é terminal (HTTP 4xx, invalid_grant, concessão revogada etc.), o Hermes marca o token de renovação como morto e o coloca em quarentena localmente — as chamadas seguintes pulam a tentativa de renovação condenada em vez de repetir o mesmo 401 sem parar. O agente exibe uma única mensagem de "reautenticação necessária" e sai do caminho até você entrar de novo.

Correção: rode hermes auth add xai-oauth de novo para começar um login novo. A quarentena é limpa na próxima troca bem-sucedida.

A autorização estourou o tempo

A aprovação por código de dispositivo tem uma janela de expiração finita (a xAI define expires_in na resposta do código de dispositivo, tipicamente na casa das dezenas de minutos). Se você não aprovar o login a tempo, o Hermes levanta um erro de tempo esgotado.

Correção: rode hermes auth add xai-oauth (ou hermes model) de novo. O fluxo recomeça do zero.

Fazer login de um servidor remoto

Em sessões SSH ou de contêiner, o Hermes imprime a URL de verificação e o código de usuário em vez de abrir um navegador. Abra essa URL num navegador do seu notebook ou num console de nuvem — nenhum encaminhamento de porta SSH é necessário para o xAI Grok OAuth.

hermes auth add xai-oauth --no-browser

Para provedores com redirecionamento de loopback (Spotify, servidores MCP), veja OAuth por SSH / hosts remotos.

HTTP 403 depois de um login bem-sucedido (faixa / direito de uso)

O OAuth foi concluído no navegador, os tokens estão salvos, mas a inferência ou a renovação de token devolve HTTP 403 com uma mensagem parecida com "The caller does not have permission to execute the specified operation".

Isso não é problema de token velho — rodar hermes model de novo não vai mudar nada. O backend da xAI já foi visto restringindo o acesso à API por OAuth a faixas específicas do SuperGrok, apesar de a assinatura estar ativa no aplicativo (issue #26847).

Correção: defina XAI_API_KEY e mude para o caminho por chave de API:

export XAI_API_KEY=xai-...
hermes config set model.provider xai

Ou faça upgrade da sua assinatura em x.ai/grok se a rota OAuth for obrigatória.

Erro "No xAI credentials found" em tempo de execução

O repositório de autenticação não tem entrada xai-oauth e nenhuma XAI_API_KEY está definida. Você ainda não fez login, ou o arquivo de credenciais foi apagado.

Correção: rode hermes model e escolha o provedor xAI Grok OAuth, ou rode hermes auth add xai-oauth.

Sair da conta

Para remover todas as credenciais guardadas do xAI Grok OAuth:

hermes auth logout xai-oauth

Isso limpa tanto a entrada OAuth única no auth.json quanto quaisquer linhas de pool de credenciais para xai-oauth. Use hermes auth remove xai-oauth <indice|id|rotulo> se você quiser descartar só uma entrada do pool (rode hermes auth list xai-oauth para vê-las).

Veja também

• OAuth por SSH / hosts remotos — túneis SSH para provedores com redirecionamento de loopback (Spotify, MCP); a xAI usa código de dispositivo e não precisa de túnel
• Referência de provedores de IA
• Variáveis de ambiente
• Configuração
• Voz e TTS

---