🗓️
Актуальность: проверено 7 сентября 2026 года по официальным руководствам Hermes Agent, репозиторию xurl и справочным страницам X API. Локальный запуск команд в рамках этой проверки не выполнялся. Интерфейсы, модели, тарифы и лимиты могут измениться.

Hermes Agent — агент с открытым исходным кодом от Nous Research, который работает в терминале и умеет вызывать внешние инструменты. Официальный CLI xurl (интерфейс командной строки) предоставляет доступ к X API: публикации постов, поиск, профили, закладки, списки, медиа и другие ресурсы.

В этом руководстве вы установите оба инструмента, подключите модель Grok, настроите OAuth 2.0 для X и проверите результат минимальными командами.

Что понадобится

  • macOS, Linux, WSL2 или Windows;
  • терминал и браузер;
  • Python 3.9 или новее для Hermes;
  • провайдер модели: Nous Portal, xAI API либо подписка SuperGrok или X Premium+ для OAuth-входа xAI Grok;
  • учётная запись разработчика X и приложение с OAuth 2.0;
  • доступ к тарифу X API с нужными конечными точками. В справочнике X API конечные точки доступны на тарифе pay-per-use (оплата по использованию), а помеченные Enterprise-only требуют плана Enterprise.
⚠️
Действия записи, например публикация постов, лайки и изменение списков, выполняются от имени вашего аккаунта. Проверяйте подготовленную команду и запрашиваемые разрешения до подтверждения.

Установка Hermes Agent

Для macOS и Windows доступен Hermes Desktop с официального сайта hermes-agent.nousresearch.com. Для установки только CLI используйте официальный установщик.

Linux, macOS и WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

После установки перезапустите оболочку. Для bash или zsh выполните:

source ~/.bashrc
# либо
source ~/.zshrc

Проверьте запуск:

hermes

Для нового терминального интерфейса также доступна команда:

hermes --tui

Настройка модели в Hermes

Быстрый путь через Nous Portal

На новой установке выполните:

hermes setup --portal

Команда авторизует пользователя через Nous Portal, выбирает Nous как провайдера и включает Tool Gateway.

На новой установке мастер hermes setup предлагает три режима:

  • Quick Setup (Nous Portal) — OAuth-вход без ручного ввода API-ключей;
  • Full Setup — последовательная настройка провайдеров, инструментов и дополнительных возможностей;
  • Blank Slate — минимальная конфигурация, где остальные инструменты и функции включаются вручную.

Подключение Grok по подписке

Откройте выбор провайдера и модели:

hermes model

Выберите xAI Grok OAuth (SuperGrok / X Premium+). Hermes покажет или откроет адрес подтверждения на accounts.x.ai и код устройства. После одобрения он сохранит OAuth-токены в ~/.hermes/auth.json и будет обновлять их автоматически.

Для ручного запуска авторизации:

hermes auth add xai-oauth

На удалённом сервере используйте поток с кодом устройства без локального обработчика обратного адреса:

hermes auth add xai-oauth --no-browser

Откройте напечатанный адрес в любом браузере и введите код. SSH-туннель для этого потока не требуется.

На дату проверки моделью по умолчанию для xai-oauth является grok-4.6. grok-4.3 остаётся в каталоге как модель предыдущего поколения. Список моделей загружается динамически и может меняться.

⚖️
OAuth-вход может завершиться успешно, но xAI ограничивает доступ к API для отдельных уровней подписки. Если запросы модели возвращают HTTP 403, используйте путь с XAI_API_KEY и переключите провайдер на xai либо проверьте уровень подписки.

Проверка конфигурации:

hermes doctor

В разделе провайдеров авторизации должен отображаться xai-oauth, а обычный запрос в hermes должен получить ответ без ошибки.

Установка xurl

xurl устанавливается отдельно от Hermes.

Homebrew:

brew install --cask xdevplatform/tap/xurl

npm:

npm install -g @xdevplatform/xurl

Официальный shell-скрипт:

curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

Go:

go install github.com/xdevplatform/xurl@latest

Shell-скрипт устанавливает бинарный файл в ~/.local/bin. Если каталог отсутствует в PATH, добавьте его согласно подсказке установщика и перезапустите оболочку.

Проверка:

xurl --help

Подключение xurl к X API

Настройка приложения X

Создайте или откройте приложение в Developer Console. В настройках пользовательской аутентификации укажите тот же URI перенаправления (redirect URI), который будет использовать xurl. Значение по умолчанию:

http://localhost:8080/callback

Скопируйте Client ID и Client Secret. Не публикуйте их и не вставляйте в примеры, логи или общедоступные файлы.

Регистрация приложения

xurl auth apps add my-app \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --redirect-uri http://localhost:8080/callback

Параметр --redirect-uri можно не указывать, если используется встроенное значение по умолчанию. xurl выбирает адрес в таком порядке: переменная REDIRECT_URI, значение приложения в ~/.xurl/auth.yml, затем http://localhost:8080/callback.

OAuth 2.0 с пользовательским контекстом

xurl auth oauth2 --app my-app

Откроется браузер. После подтверждения токен будет связан с указанным приложением.

⚠️
Всегда явно указывайте --app my-app либо сначала назначьте приложение по умолчанию. Без флага токен сохраняется для текущего приложения по умолчанию, которое может оказаться другим.

Для удалённой машины:

xurl auth oauth2 --app my-app --headless

xurl напечатает URL. Откройте его на устройстве с браузером, подтвердите доступ, затем вставьте итоговый redirect URL или значение code обратно в терминал. Ошибка загрузки страницы обратного адреса в этом режиме ожидаема.

Если X не возвращает имя пользователя через /2/users/me, его можно указать явно:

xurl auth oauth2 --app my-app YOUR_USERNAME

Назначьте приложение и проверьте состояние:

xurl auth default my-app
xurl auth status
xurl whoami

Успешный xurl whoami должен вернуть сведения о текущем пользователе. Учётные данные приложений и токены хранятся в ~/.xurl/auth.yml отдельно для каждого зарегистрированного приложения.

Проверка запросов и работа через Hermes

Минимальный прямой запрос к X API:

xurl /2/users/me

Публикация тестового поста через API:

xurl -X POST /2/tweets -d '{"text":"Hello from xurl"}'

Эта команда создаёт пост от имени текущего аккаунта. Выполняйте её только после проверки аккаунта, текста и выбранного приложения.

Репозиторий xurl содержит файл SKILL.md для агентного использования, а установленные навыки Hermes становятся командами с префиксом /. Проверьте список команд через /help. Если /xurl доступна, загрузите её и формулируйте задачу обычным языком, например:

Промпт:

Найди свежие посты по теме Hermes Agent и подготовь краткое резюме. Ничего не публикуй.

Перед операцией записи задавайте явное ограничение и просите показать действие до выполнения:

Промпт:

Подготовь текст ответа на пост, но не публикуй его без моего подтверждения.

Если /xurl отсутствует, используйте официальный CLI напрямую. Способ установки навыка зависит от текущей версии Hermes и её каталога навыков.

Полезные сценарии

Исследование темы без публикации

Задача: найти свежие посты по теме и получить подборку ссылок без записи в X.

Условие: есть приложение X с пользовательской аутентификацией и доступом к нужной конечной точке.

Действие: попросите Hermes выполнить поиск через xurl, сгруппировать результаты и вернуть идентификаторы и URL постов.

Результат: вы получаете список найденных публикаций, который можно проверить по идентификаторам и ссылкам.

Ограничение: доступность поиска зависит от тарифа и лимитов X API.

Работа с закладками

Задача: разобрать закладки и подготовить тематическую подборку.

Условие: OAuth-токен пользователя с разрешениями приложения на работу с закладками.

Действие: попросите Hermes получить список закладок через xurl и сделать краткие описания. Изменение закладок выполняйте только после отдельного подтверждения.

Результат: наблюдаемым результатом будут записи, возвращённые API.

Ограничение: доступ к чтению и изменению закладок зависит от разрешений токена, тарифа и лимитов.

Подготовка и публикация поста

Задача: подготовить пост и опубликовать его после редакционной проверки.

Условие: определены тема, ограничения, аккаунт и приложение X.

Действие: попросите Hermes сначала показать черновик, затем подтвердите публикацию отдельным сообщением.

Результат: после записи проверьте ID поста и откройте его URL.

Ограничение: сценарий не подходит для полностью автономной публикации без редакционной проверки.

Тарифы и лимиты X API

X API применяет отдельные лимиты к каждой конечной точке. Они могут различаться для пользовательского OAuth 2.0-токена и app-only Bearer Token (токена только приложения). При превышении лимита API отвечает кодом 429.

Проверяйте заголовки ответа:

  • x-rate-limit-limit — размер лимита;
  • x-rate-limit-remaining — оставшееся число запросов;
  • x-rate-limit-reset — время сброса в формате Unix timestamp.

Лимиты и тарификация независимы: запрос может укладываться в rate limit, но расходовать оплачиваемую квоту. Актуальные значения смотрите в официальной таблице лимитов и Developer Console.

Решение типичных проблем

ПроблемаЧто проверить
xurl: command not foundНаличие ~/.local/bin в PATH и перезапуск Hermes после изменения окружения
OAuth callback не приходитПолное совпадение redirect URI и доступность порта 8080; для удалённой машины используйте --headless
OAuth успешен, но запросы идут не через то приложениеxurl auth status, затем xurl auth default my-app или явный --app my-app
client-forbidden или client-not-enrolledПроверьте пакет и окружение приложения. В текущем README xurl для этой ошибки указаны Move to package → Pay-per-use и окружение Production
Hermes возвращает HTTP 403 после xAI OAuthВозможное ограничение уровня подписки; переключитесь на провайдера xai с XAI_API_KEY или проверьте право доступа подписки
Токен xAI отозван или не обновляетсяПовторите hermes auth add xai-oauth
xurl не определяет usernameПовторите OAuth с явным YOUR_USERNAME

Где хранятся настройки

ПутьНазначение
~/.hermes/config.yamlНесекретные настройки Hermes
~/.hermes/.envAPI-ключи и другие секреты, добавленные через конфигурацию
~/.hermes/auth.jsonOAuth-токены Hermes, включая xai-oauth
~/.hermes/sessions/Сохранённые сессии
~/.xurl/auth.ymlПриложения X, их credentials и токены
~/.xurl/keys.ymlЛокальные приватные ключи XChat, если используется xurl chat

Не добавляйте эти файлы в Git и не передавайте их другим пользователям.

Официальные источники

Следующий шаг

Hermes Agent — самообучающийся ИИ-агент: установка и быстрый старт

Если вы встраиваете Hermes и X API в командный процесс, заранее определите права доступа, лимиты расходов и операции, для которых нужно ручное подтверждение.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov