База знаний

X API — официальное руководство по работе с Hermes и xurl

Официальное руководство X API по настройке ИИ-агента Hermes с навыком xurl — публикация, поиск, закладки и управление X через естественный язык.

Опубликовано 20.05.2026

ИИ-агенты DevTools API и данные

Open-source ИИ-агент от Nous Research, который работает прямо в терминале. Из коробки поставляется с навыком xurl, позволяющим агенту читать и писать в X от вашего имени — публиковать посты, искать, получать закладки, управлять списками и многое другое — всё через естественный язык.

Это руководство описывает полную настройку: установку Hermes, подключение к провайдеру моделей, установку xurl, аутентификацию через X API и совместное использование.

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

macOS или Linux
Терминал (iTerm2, Ghostty, стандартный Terminal и т.д.)
Активная подписка SuperGrok (регистрация на x.ai/grok)
(Опционально) API-ключ xAI — только если возникнут ограничения по уровню доступа при OAuth
Приложение разработчика X с учётными данными OAuth 2.0 (console.x.com)

1. Установка Hermes

Запустите однострочный установщик:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Скрипт скачивает бинарный файл Hermes и добавляет его в PATH. После завершения запустите hermes, чтобы убедиться в корректной установке и запустить мастер настройки.

2. Мастер настройки

При первом запуске Hermes проведёт вас через конфигурацию. Повторный запуск в любое время — командой hermes setup.

Выбор режима настройки

How would you like to set up Hermes?

 → (●) Quick setup — provider, model & messaging (recommended)
   (○) Full setup — configure everything

Quick setup — самый быстрый путь. Покрывает три основных момента: провайдер моделей, модель по умолчанию и опциональная интеграция с мессенджерами (Telegram, Discord и т.д.). Выбирайте этот вариант, если не хотите настраивать каждый параметр вручную.

Выбор провайдера

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

Select provider:
  (○) OpenRouter (100+ models, pay-per-use)
   ...
 → (●) xAI Grok OAuth (SuperGrok Subscription)
   (○) xAI (direct API key – legacy)
   ...

При выборе xAI Grok OAuth Hermes автоматически откроет браузер на https://accounts.x.ai.

Войдите в аккаунт X, привязанный к подписке SuperGrok.
Подтвердите запрашиваемые разрешения.

Hermes получает токены через локальный callback и сохраняет их в ~/.hermes/auth.json (токены обновляются автоматически в фоновом режиме).

Выбор модели по умолчанию

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

Select default model:
->   grok-4.3
     ...

Выберите подходящую модель. Изменить позже можно командой hermes setup model.

Мессенджеры (опционально)

Connect a messaging platform? (Telegram, Discord, etc.)

   (○) Set up messaging now (recommended)
 → (●) Skip — set up later with 'hermes setup gateway'

Если хотите, чтобы Hermes работал как Telegram- или Discord-бот — настройте сейчас. Иначе пропустите — вернуться можно в любой момент через hermes setup gateway.

Готово

После завершения мастера отобразится итог:

✓ Setup complete! You're ready to go.

    Configure all settings:    hermes setup
    Connect Telegram/Discord:  hermes setup gateway
    Switch model/provider:     hermes model

Также появится отчёт о доступности инструментов — какие категории активны, а какие требуют дополнительных API-ключей.

3. Установка xurl

xurl — отдельный CLI для X API. Hermes использует его под капотом при вызове навыка xurl. Установите любым удобным способом:

Shell-скрипт (без sudo, устанавливается в ~/.local/bin):

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

Homebrew (macOS):

brew install --cask xdevplatform/tap/xurl

npm (требуется Node.js):

npm install -g @xdevplatform/xurl

Go (требуется Go):

go install github.com/xdevplatform/xurl@latest

Если использовали shell-скрипт, может понадобиться добавить ~/.local/bin в PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Проверка установки:

xurl --help

4. Аутентификация xurl через X API

xurl требует учётные данные OAuth 2.0 от приложения разработчика X. Эту настройку нужно делать в терминале напрямую — не внутри Hermes.

Создание приложения разработчика X

Перейдите на developer.x.com/en/portal/dashboard
Создайте новое приложение (или используйте существующее)
В разделе User authentication settings укажите redirect URI:

http://localhost:8080/callback

Скопируйте Client ID и Client Secret

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

xurl auth apps add my-app \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Аутентификация через OAuth

xurl auth oauth2 --app my-app

Откроется браузер для прохождения OAuth-потока. Авторизуйте приложение вашим аккаунтом X.

⚠️

Важно: обязательно указывайте флаг --app my-app. Если пропустить --app, токен может сохраниться в профиль по умолчанию, а не в приложение с вашими client credentials — последующие API-вызовы будут падать с ошибкой 401. Актуальные версии xurl предупреждают об этом и подсказывают нужный флаг.

Если после аутентификации нужно привязать конкретный username:

xurl auth oauth2 --app my-app YOUR_USERNAME

Установка приложения по умолчанию и проверка

xurl auth default my-app
xurl auth status
xurl whoami

xurl whoami должна вывести ваш username в X — значит, всё настроено.

5. Запуск Hermes

Запустите сессию чата:

hermes

Если Hermes предложит запуститься после настройки — введите Y. Иначе просто выполните hermes в терминале.

Внутри введите /help, чтобы увидеть доступные команды. В списке будет /xurl — это нужный навык.

6. Использование навыка xurl

Введите /xurl в чате Hermes для загрузки навыка. Hermes проверит, что xurl установлен и аутентифицирован.

Далее просто говорите Hermes, что нужно сделать, на обычном языке. Он переводит запросы в команды xurl, выполняет их и возвращает результат.

Публикация в X

post "Hello from Hermes"

Hermes выполняет xurl post "Hello from Hermes" и возвращает ID и ссылку на пост:

Posted successfully! Your new post:

- ID: 2047107136023650625
- Text: "Hello from Hermes"
- Link: https://x.com/yourhandle/status/2047107136023650625

Получение закладок

get all of my bookmarks

Hermes выполняет xurl bookmarks -n 100 и выдаёт понятный список ваших закладок — с метриками, типами медиа и именами пользователей — вместо сырого JSON.

Что ещё можно делать

Навык xurl даёт Hermes доступ ко всей поверхности X API:

Действие	Пример команды
Поиск постов	"search for posts about Hermes AI"
Профиль пользователя	"look up @elonmusk"
Ответ на пост	"reply to post 2047107136023650625 with 'great thread'"
Цитирование поста	"quote post 2047107136023650625 with my thoughts"
Лайк / анлайк	"like post 2047107136023650625"
Управление закладками	"unbookmark 2047107136023650625"
Лента	"show my latest timeline"
Пост с медиа	"post this image with the caption 'sunset'"

Поскольку Hermes — агент, можно выстраивать цепочки действий в диалоге. Попросите его найти посты по теме, суммаризировать их и составить ответ — всё за один раз.

Конфигурация

Все настройки Hermes хранятся в ~/.hermes/:

Файл / директория	Назначение
`config.yaml`	Основные настройки (модель, провайдер, поведение агента)
`auth.json`	OAuth-токены (xAI Grok OAuth и т.д.) — управляется автоматически
`.env`	API-ключи (XAI_API_KEY и т.д.)
`cron/`	Запланированные задачи
`sessions/`	История чатов
`logs/`	Логи

Полезные команды для управления:

hermes setup            # Перезапуск мастера настройки
hermes setup model      # Смена модели/провайдера
hermes setup gateway    # Настройка мессенджеров (Telegram, Discord)
hermes setup tools      # Настройка провайдеров инструментов
hermes config           # Просмотр текущих настроек
hermes config edit      # Открыть конфиг в редакторе
hermes doctor           # Диагностика проблем
hermes model            # Смена модели или переключение на xAI Grok OAuth
hermes auth add xai-oauth   # Ручной OAuth-вход (при необходимости)
hermes auth list            # Просмотр сохранённых учётных данных
hermes auth logout xai-oauth # Удаление OAuth-учётных данных

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

Проблема	Решение
xurl: command not found внутри Hermes	Убедитесь, что xurl доступен в PATH. Если устанавливали через shell-скрипт — добавьте `~/.local/bin` в PATH и перезапустите Hermes.
OAuth-поток не завершается	Проверьте, что redirect URI в приложении X точно `http://localhost:8080/callback`. Убедитесь, что порт 8080 свободен при запуске `xurl auth oauth2 --app my-app`.
OAuth проходит, но API-вызовы падают с 401	Убедитесь, что аутентификация прошла через то же приложение, где хранятся client credentials: `xurl auth oauth2 --app my-app`, затем `xurl auth default my-app`. Проверьте `xurl auth status`.
API-ключ содержит не-ASCII символы	Бывает при копировании из PDF или редакторов с форматированием. Hermes предупредит и автоматически уберёт плохие символы, но если аутентификация всё равно не проходит — скопируйте ключ заново из дашборда провайдера.
xurl auth status показывает отсутствие активной сессии	Повторите `xurl auth oauth2 --app my-app` для реаутентификации, затем `xurl auth default my-app`.

Краткий итог

Установите Hermes однострочным скриптом
Запустите мастер настройки (или hermes model) — выберите xAI Grok OAuth (SuperGrok Subscription), пройдите разовый вход через браузер, выберите модель
Установите xurl отдельно
Аутентифицируйте xurl учётными данными приложения разработчика X
Запустите Hermes, загрузите /xurl и начните взаимодействовать с X на обычном языке

Теперь у вас есть ИИ-агент в терминале, который умеет читать и писать в X от вашего имени, суммаризировать ленту, управлять закладками и делать всё остальное, что поддерживает X API — через обычный диалог.

Ссылки

По теме

Если хотите разобрать свою задачу — напишите мне

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

Напишите мне в Телеграм Мой Телеграм канал

Обычно хватает 2–3 сообщений, чтобы понять, могу ли я здесь реально помочь и в каком формате лучше двигаться дальше.