xAI Grok OAuth (SuperGrok / X Premium+)

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

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

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

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

Обзор

Требования

• Python 3.9+
• Установленный Hermes Agent
• Активная подписка SuperGrok на вашем аккаунте xAI, либо подписка X Premium+ на аккаунте X, через который вы входите (xAI привязывает подписку автоматически)
• Браузер, доступный там, где можно открыть выведенную ссылку для подтверждения

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

# Запускаем выбор провайдера и модели
hermes model
# → Выберите «xAI Grok OAuth (SuperGrok / X Premium+)» из списка провайдеров
# → Hermes откроет браузер или выведет ссылку для подтверждения на accounts.x.ai
# → Если появится запрос — введите показанный код, затем подтвердите доступ в браузере
# → Выберите модель (grok-4.6 — в начале списка)
# → Начинайте общение

hermes

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

Вход вручную

Запустить вход можно и без выбора модели:

hermes auth add xai-oauth

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

На серверах, в контейнерах, консолях без локального браузера (Cloud Shell, Codespaces, EC2 Instance Connect) или в SSH-сессиях, где Hermes не может открыть браузер на месте, он выводит ссылку для подтверждения xAI и код пользователя. Откройте эту ссылку в любом браузере — на ноутбуке или прямо в облачной консоли, — при необходимости введите код, и Hermes будет опрашивать сервер, пока xAI не подтвердит вход. SSH-туннель или локальный callback-listener для этого не нужны.

hermes auth add xai-oauth --no-browser
# Откройте в браузере выведенную ссылку для подтверждения.

Тот же device-code flow применяется и при входе через веб-дашборд или десктопное приложение: Hermes показывает ссылку для подтверждения и код пользователя, а затем опрашивает сервер в фоне, пока вы не подтвердите доступ.

Как устроен вход

1. Hermes запрашивает device-код у auth.x.ai.
2. Вы открываете ссылку для подтверждения, входите в аккаунт, при необходимости вводите показанный код и подтверждаете доступ.
3. Hermes опрашивает xAI до получения подтверждения, а затем сохраняет токены в ~/.hermes/auth.json.
4. Дальше Hermes обновляет access-токен в фоне — вы остаётесь авторизованы, пока не выполните hermes auth logout xai-oauth или не отзовёте доступ в настройках аккаунта xAI.

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

hermes doctor

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

Переключение моделей

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

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

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

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

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

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

Алиасы провайдера

Все перечисленные ниже варианты указывают на xai-oauth:

hermes --provider xai-oauth        # каноническое имя
hermes --provider grok-oauth       # алиас
hermes --provider x-ai-oauth       # алиас
hermes --provider xai-grok-oauth   # алиас

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

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

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

hermes tools
# → Синтез речи (Text-to-Speech)  → «xAI TTS»
# → Генерация изображений         → «xAI Grok Imagine (image)»
# → Генерация видео               → «xAI Grok Imagine»
# → Поиск по X (Twitter)          → «xAI Grok OAuth (SuperGrok / X Premium+)»

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

Модели

Каталог чат-моделей формируется на лету из локального кэша models.dev; новые релизы xAI появляются автоматически после обновления этого кэша. Модель grok-4.6 всегда закреплена в начале списка.

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

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

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

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

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

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

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

Истекло время ожидания авторизации

У подтверждения device-кода есть ограниченное окно действия (xAI задаёт expires_in в ответе на запрос device-кода — обычно порядка десятков минут). Если не успеть подтвердить вход, Hermes выдаёт ошибку тайм-аута.

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

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

В SSH-сессиях или контейнерах Hermes вместо открытия браузера выводит ссылку для подтверждения и код пользователя. Откройте эту ссылку в браузере на ноутбуке или в облачной консоли — для xAI Grok OAuth проброс SSH-порта не требуется.

hermes auth add xai-oauth --no-browser

Для провайдеров с loopback-редиректом (Spotify, MCP-серверы) см. 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

Либо, если нужен именно путь через OAuth, повысьте уровень подписки на x.ai/grok.

Ошибка «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 / удалённые хосты — SSH-туннели для провайдеров с loopback-редиректом (Spotify, MCP); xAI использует device code, и туннель не нужен
• Справочник по AI-провайдерам
• Переменные окружения
• Конфигурация
• Голос и TTS