xAI Grok OAuth (SuperGrok / X Premium+)

Hermes Agent поддерживает xAI Grok через браузерный OAuth-вход на accounts.x.ai — с подпиской SuperGrok (grok.com) или X Premium+ (привязанный X-аккаунт). XAI_API_KEY не нужен: войдите один раз, и Hermes будет автоматически обновлять сессию в фоне.

Если вы входите с X-аккаунтом на Premium+, xAI автоматически привязывает статус подписки к xAI-сессии — OAuth-поток работает так же, как и для прямых подписчиков SuperGrok.

Транспорт использует адаптер codex_responses (xAI предоставляет Responses-style эндпоинт), поэтому рассуждения, вызов инструментов, стриминг и кэширование промптов работают без изменений в адаптере.

Тот же OAuth bearer token переиспользуется всеми прямыми инструментами xAI в Hermes — TTS, генерацией изображений, генерацией видео и транскрипцией. Один вход покрывает все четыре.

Обзор

Параметр	Значение
Provider ID	`xai-oauth`
Отображаемое имя	xAI Grok OAuth (SuperGrok / X Premium+)
Тип аутентификации	Browser OAuth 2.0 PKCE (loopback callback)
Транспорт	xAI Responses API (`codex_responses`)
Модель по умолчанию	`grok-build-0.1`
Эндпоинт	`https://api.x.ai/v1`
Сервер авторизации	`https://accounts.x.ai`
Требует переменной окружения	Нет (`XAI_API_KEY` для этого провайдера не используется)
Подписка	SuperGrok или X Premium+ — см. примечание ниже

Требования

Python 3.9+
Установленный Hermes Agent
Активная подписка SuperGrok на xAI-аккаунте или подписка X Premium+ на X-аккаунте (xAI привязывает её автоматически)
Браузер на локальной машине (или флаг --no-browser для удалённых сессий)

внимание

xAI может ограничивать OAuth API-доступ по тарифу

Бэкенд xAI применяет собственный белый список для OAuth API и блокировал стандартных подписчиков SuperGrok с ошибкой HTTP 403 (см. issue #26847) — даже при активной подписке в приложении. Если OAuth-вход прошёл успешно, а инференс возвращает 403 — задайте XAI_API_KEY и переключитесь на путь через API-ключ (provider: xai): это ограничение его пока не касается.

Быстрый старт

# Открыть выбор провайдера и модели
hermes model
# → Выбрать "xAI Grok OAuth (SuperGrok / X Premium+)" из списка
# → Hermes откроет браузер на accounts.x.ai
# → Подтвердить доступ в браузере
# → Выбрать модель (grok-build-0.1 вверху списка)
# → Начать чат

hermes

После первого входа учётные данные сохраняются в ~/.hermes/auth.json и обновляются автоматически до истечения срока.

Ручной вход

Можно запустить вход без использования списка моделей:

hermes auth add xai-oauth

Удалённые / headless-сессии

На серверах, в контейнерах или SSH-сессиях без браузера Hermes определяет удалённую среду и выводит URL авторизации вместо открытия браузера.

Важно: loopback-листенер по-прежнему запускается на удалённой машине по адресу 127.0.0.1:56121. Редирект xAI должен попасть именно на этот листенер — открытие URL на ноутбуке завершится ошибкой (Could not establish connection. We couldn't reach your app.) без проброса порта:

# В отдельном терминале на локальной машине:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Затем в SSH-сессии на удалённой машине:
hermes auth add xai-oauth --no-browser
# Откройте выведенный URL авторизации в локальном браузере.

Через jump box / бастион добавьте -J jump-user@jump-host.

Полное пошаговое руководство — включая цепочки ProxyJump, mosh/tmux и подводные камни ControlMaster — смотрите в OAuth через SSH / удалённые хосты.

Браузерные удалённые среды (Cloud Shell, Codespaces, EC2 Instance Connect)

Если обычного SSH-клиента нет (GCP Cloud Shell, GitHub Codespaces, AWS EC2 Instance Connect, Gitpod или другая браузерная консоль), рецепт ssh -L недоступен. Используйте --manual-paste — Hermes пропустит loopback-листенер и даст вам вставить URL упавшего callback прямо из браузера:

hermes auth add xai-oauth --manual-paste
# Или через список моделей:
hermes model --manual-paste

Полное описание — в OAuth через SSH / удалённые хосты. Фикс регрессии #26923.

Если страница согласия отображает код авторизации прямо на странице (текущее поведение xAI в браузерных консолях) вместо редиректа на 127.0.0.1:56121/callback — вставьте только голый код в промпт Callback URL:. Hermes принимает полный URL, фрагмент ?code=...&state=... и голый код взаимозаменяемо.

Как работает вход

Hermes открывает браузер на accounts.x.ai.
Вы входите (или подтверждаете существующую сессию) и разрешаете доступ.
xAI перенаправляет обратно в Hermes, токены сохраняются в ~/.hermes/auth.json.
Дальше Hermes обновляет access_token в фоне — вы остаётесь авторизованными, пока не выполните hermes auth remove xai-oauth или не отзовёте доступ в настройках xAI-аккаунта.

Проверка статуса входа

hermes doctor

Раздел ◆ Auth Providers покажет текущее состояние каждого провайдера, в том числе xai-oauth.

Смена модели

hermes model
# → Выбрать "xAI Grok OAuth (SuperGrok / X Premium+)"
# → Выбрать модель из списка (grok-build-0.1 закреплён вверху)

Или задать модель напрямую:

hermes config set model.default grok-build-0.1
hermes config set model.provider xai-oauth

Справочник по конфигурации

После входа ~/.hermes/config.yaml будет содержать:

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

Псевдонимы провайдера

Все варианты ниже ведут к xai-oauth:

hermes --provider xai-oauth        # canonical
hermes --provider grok-oauth       # alias
hermes --provider x-ai-oauth       # alias
hermes --provider xai-grok-oauth   # alias

Прямые инструменты xAI (TTS / изображения / видео / транскрипция / X Search)

После входа через OAuth каждый прямой инструмент xAI автоматически переиспользует тот же bearer token — отдельная настройка не нужна, если только вы не предпочитаете API-ключ.

Чтобы выбрать бэкенд для каждого инструмента:

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+)"

Если OAuth-токены уже сохранены, список моделей подтвердит это и пропустит запрос учётных данных. Если ни OAuth, ни XAI_API_KEY не настроены, список предложит три варианта: войти через OAuth, вставить API-ключ или пропустить.

заметка

Генерация видео отключена по умолчанию

Набор инструментов video_gen выключен по умолчанию. Включите его в hermes tools → 🎬 Video Generation (пробел), прежде чем агент сможет вызвать video_generate. В противном случае агент может переключиться на встроенный ComfyUI-навык, который тоже помечен для генерации видео.

заметка

X Search включается автоматически при наличии xAI-учётных данных

Набор инструментов x_search включается автоматически, когда настроены учётные данные xAI (SuperGrok / X Premium+ OAuth-токен или XAI_API_KEY). Отключите явно через hermes tools → 🐦 X (Twitter) Search (пробел), если не хотите этого. Инструмент использует встроенный x_search Responses API от xAI — работает с OAuth-входом SuperGrok/X Premium+ или платным XAI_API_KEY, при наличии обоих предпочитает OAuth (расходует квоту подписки, а не API-бюджет). Схема инструмента скрыта от модели, если xAI-учётные данные не настроены, — независимо от того, включён ли набор.

Модели

Инструмент	Модель	Примечания
Чат	`grok-build-0.1`	По умолчанию; выбирается автоматически при входе через OAuth
Чат	`grok-4.3`	Предыдущий дефолт
Чат	`grok-4.20-0309-reasoning`	Вариант с рассуждением
Чат	`grok-4.20-0309-non-reasoning`	Вариант без рассуждения
Чат	`grok-4.20-multi-agent-0309`	Мультиагентный вариант
Изображение	`grok-imagine-image`	По умолчанию; ~5–10 с
Изображение	`grok-imagine-image-quality`	Более высокое качество; ~10–20 с
Видео	`grok-imagine-video`	Text-to-video
Видео	`grok-imagine-video-1.5-preview`	Image-to-video; датированный псевдоним `grok-imagine-video-1.5-2026-05-30`
TTS	(голос по умолчанию)	Эндпоинт xAI `/v1/tts`

Каталог моделей для чата берётся в реальном времени из кэша models.dev на диске — новые релизы xAI появляются автоматически после обновления кэша. grok-build-0.1 всегда закреплён вверху списка.

Переменные окружения

Переменная	Действие
`XAI_BASE_URL`	Переопределяет эндпоинт по умолчанию `https://api.x.ai/v1` (нужно редко).

Чтобы выбрать xAI как активный провайдер, задайте model.provider: xai-oauth в config.yaml (используйте hermes setup для пошаговой настройки) или передайте --provider xai-oauth для разового вызова.

Решение проблем

Токен истёк — автоматическое обновление не происходит

Hermes обновляет токен перед каждой сессией и повторно — реактивно — при получении 401. Если обновление завершается ошибкой invalid_grant (refresh_token был отозван или аккаунт был сброшен), Hermes выводит типизированное сообщение о повторной аутентификации вместо краша.

Когда ошибка обновления терминальная (HTTP 4xx, invalid_grant, отозванный grant и т. п.), Hermes помечает refresh_token как недействительный и локально его карантинирует — последующие вызовы пропускают обречённую попытку обновления вместо того, чтобы снова и снова воспроизводить тот же 401. Агент выведет единственное сообщение «требуется повторная аутентификация» и не будет мешать работе до следующего входа.

Решение: запустите hermes auth add xai-oauth заново для нового входа. Карантин снимается при следующем успешном обмене.

Авторизация истекла по таймауту

Loopback-листенер имеет конечное окно ожидания (по умолчанию 180 с). Если вы не успели подтвердить вход вовремя, Hermes выбросит ошибку таймаута.

Решение: повторно запустите hermes auth add xai-oauth (или hermes model). Поток начнётся с нуля.

Несовпадение state (возможный CSRF)

Hermes обнаружил, что значение state, возвращённое сервером авторизации, не совпадает с отправленным.

Решение: повторите вход. Если ошибка сохраняется, проверьте, нет ли прокси или редиректа, изменяющего OAuth-ответ.

Вход с удалённого сервера

В SSH или контейнерных сессиях Hermes выводит URL авторизации вместо открытия браузера. Loopback-листенер по-прежнему привязан к 127.0.0.1:56121 на удалённом хосте — браузер на ноутбуке не достучится до него без SSH local-forward:

# Локальная машина, отдельный терминал:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Удалённая машина:
hermes auth add xai-oauth --no-browser

Полное руководство (jump box, mosh/tmux, конфликты портов): OAuth через SSH / удалённые хосты.

HTTP 403 после успешного входа (тариф / права доступа)

OAuth прошёл в браузере, токены сохранены, но инференс или обновление токена возвращает HTTP 403 с сообщением вида «The caller does not have permission to execute the specified operation».

Это не проблема устаревшего токена — повторный запуск hermes model ничего не изменит. Бэкенд xAI ограничивал OAuth API-доступ для определённых тарифов SuperGrok, несмотря на активную подписку (issue #26847).

Решение: задайте XAI_API_KEY и переключитесь на путь через API-ключ:

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

Или обновите подписку на x.ai/grok, если OAuth-путь обязателен.

Ошибка «No xAI credentials found» во время работы

В хранилище аутентификации нет записи xai-oauth и не задан XAI_API_KEY. Вы ещё не вошли, или файл учётных данных был удалён.

Решение: запустите hermes model и выберите провайдер xAI Grok OAuth, или выполните hermes auth add xai-oauth.

Выход

Чтобы удалить все сохранённые учётные данные xAI Grok OAuth:

hermes auth logout xai-oauth

Команда очищает и единственную OAuth-запись в auth.json, и все строки из пула учётных данных для xai-oauth. Используйте hermes auth remove xai-oauth <index|id|label>, если нужно удалить только одну запись из пула (запустите hermes auth list xai-oauth, чтобы их увидеть).

Смотрите также

OAuth через SSH / удалённые хосты — обязательно к прочтению, если Hermes на другой машине, чем браузер
Справочник AI-провайдеров
Переменные окружения
Конфигурация
Голос и TTS