Hermes Agent на Discord — это полноценный AI-агент прямо в вашем сервере: он читает сообщения в каналах и личных сообщениях, вызывает инструменты, помнит контекст и отвечает в реальном времени. Разберём по шагам, как создать бота в Discord Developer Portal, выдать ему нужные права, настроить доступ по user ID и ролям и запустить шлюз Hermes так, чтобы бот не просто «горел зелёным», а действительно отвечал.
Что такое Hermes Agent на Discord?
Hermes Agent на Discord — это интеграция через messaging gateway (шлюз сообщений), которая позволяет AI-агенту работать внутри Discord как обычный бот-участник сервера. Бот принимает сообщения, прогоняет их через полный конвейер Hermes — с инструментами, памятью и reasoning — и отвечает в том же канале, треде или личке. Поддерживаются текст, голосовые сообщения, вложения и слэш-команды.
Ключевое отличие от «болталки с ИИ» в чате: Discord-бот Hermes не stateless. Он авторизует отправителя, проверяет правила упоминания, поднимает сессию из истории диалога и только потом запускает агента с полным доступом к его инструментам.
Как Hermes ведёт себя в Discord: правила по умолчанию
Прежде чем настраивать — поймите модель поведения. Вот таблица из официальной документации Hermes Agent:
| Контекст | Поведение |
|---|---|
| Личные сообщения (DM) | Hermes отвечает на каждое сообщение, `@mention` не нужен. Каждая личка — отдельная сессия. |
| Каналы сервера | По умолчанию Hermes отвечает только при `@mention`. Сообщение без упоминания игнорируется. |
| Free-response каналы | Каналы, добавленные в `DISCORD_FREE_RESPONSE_CHANNELS`, работают без упоминаний. Автотрединг в них отключается — канал остаётся лёгким чатом. |
| Треды | Hermes отвечает в том же треде. Правила упоминаний сохраняются, если тред или его родительский канал не помечен как free-response. Историю тред хранит отдельно от канала. |
| Общие каналы с несколькими людьми | По умолчанию история сессий изолирована по пользователям. Два человека в одном канале не делят один транскрипт. |
| Сообщения с упоминанием других | При `DISCORD_IGNORE_NO_MENTION=true` (по умолчанию) бот молчит, если сообщение упоминает других, но не его. Это защита от «встрявания» в чужие диалоги. |
Если нужен обычный канал-помощник, где люди пишут боту без тега, — добавьте его ID в DISCORD_FREE_RESPONSE_CHANNELS.
Чем Discord-бот Hermes отличается от простого webhook-бота?
Hermes на Discord — не webhook, который отвечает без состояния. Каждое входящее сообщение проходит шесть последовательных этапов:
DISCORD_ALLOWED_USERS / DISCORD_ALLOWED_ROLES / DISCORD_ALLOWED_CHANNELS)Именно поэтому поведение бота в загруженном сервере зависит не только от маршрутизации Discord, но и от политики сессий Hermes.
Модель сессий в Discord
По умолчанию каждая личка — отдельная сессия, каждый серверный тред — отдельное пространство имён, а каждый пользователь в общем канале получает собственную сессию внутри этого канала. То есть если Алиса и Боб пишут Hermes в канале #research, это две несвязанные беседы, хотя канал визуально один.
Управляется настройкой в config.yaml:
group_sessions_per_user: true # изоляция сессий по пользователю (по умолчанию)
Ставить false стоит только если вы сознательно хотите один общий транскрипт на всю комнату. У shared-сессий есть цена: участники делят рост контекста и расход токенов, долгая задача одного человека раздувает контекст всем, а его запущенный процесс может прервать ответ другому.
Пошаговая настройка: от Developer Portal до первого ответа
Шаг 1. Создайте приложение
Откройте Discord Developer Portal, войдите в свой аккаунт Discord, нажмите New Application, введите имя (например, «Hermes Agent») и примите Developer Terms of Service. После создания вы попадёте на страницу General Information — сохраните Application ID, он понадобится для ссылки-приглашения.
Шаг 2. Создайте бота
В левом меню выберите Bot — Discord автоматически создаст бот-аккаунт для приложения. В блоке Authorization Flow:
Здесь же можно задать аватар и баннер — их увидят участники сервера.
Шаг 3. Включите Privileged Gateway Intents — это главный шаг
Если бот подключается, но не читает сообщения, проблема почти всегда здесь. На странице Bot прокрутите до Privileged Gateway Intents:
| Intent | Назначение | Обязателен? |
|---|---|---|
| Presence Intent | Видеть статус онлайн/офлайн | Нет |
| Server Members Intent | Доступ к списку участников, разрешение имён | **Да** |
| Message Content Intent | Чтение текста сообщений | **Да** |
Message Content Intent — критичный переключатель. Без него Discord присылает события сообщений, но текст в них пустой: бот формально «слышит» событие и не видит, что вы написали. Server Members Intent нужен, чтобы Hermes мог разрешать имена в списке разрешённых и понимал, кто именно пишет боту.
Если бот находится менее чем в 100 серверах, интенты включаются и выключаются свободно. От 100 серверов Discord требует подать заявку на верификацию — для личного или командного использования это неактуально.
Шаг 4. Получите токен бота
На той же странице Bot, в блоке Token, нажмите Reset Token. Если включена двухфакторная аутентификация — введите код 2FA. Discord покажет токен только один раз, скопируйте его сразу.
Токен — это учётные данные, которыми Hermes логинится под вашим ботом. Любой, кто получил токен, получает полный контроль над ботом. Храните его в менеджере паролей или в .env с правами 600, а не в Git, скриншотах и переписке.
Шаг 5. Соберите ссылку-приглашение
Вариант A (рекомендуемый). Вкладка Installation → включите Guild Install → для Install Link выберите Discord Provided Link → в Default Install Settings укажите scopes bot и applications.commands и нужные права.
Вариант B (ручная ссылка). Соберите URL сами:
https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912
Замените YOUR_APP_ID на Application ID из шага 1.
Минимальные права: View Channels, Send Messages, Embed Links, Attach Files, Read Message History. Рекомендуется добавить Send Messages in Threads и Add Reactions.
Числовые значения прав:
| Уровень | Permission integer | Что входит |
|---|---|---|
| Минимум | `117760` | View Channels, Send Messages, Read Message History, Attach Files |
| Рекомендуемый | `274878286912` | Всё выше + Embed Links, Send Messages in Threads, Add Reactions |
Шаг 6. Пригласите бота на сервер
Откройте ссылку-приглашение, выберите сервер в поле Add to Server, нажмите Continue → Authorize, пройдите CAPTCHA. Для приглашения нужно право Manage Server — если вашего сервера нет в списке, попросите администратора. После авторизации бот появится в списке участников и будет отображаться офлайн, пока вы не запустите шлюз Hermes.
Шаг 7. Узнайте свой Discord User ID
Hermes использует ваш User ID, чтобы решать, кому можно писать боту. Откройте Discord → Settings → Advanced → включите Developer Mode. Затем нажмите правой кнопкой на свой ник (в сообщении, списке участников или профиле) → Copy User ID. Это длинное число вида 284102345871466496.
Developer Mode заодно позволяет копировать Channel ID и Server ID — правой кнопкой по каналу или названию сервера → Copy ID.
Шаг 8. Настройте Hermes
Интерактивно (рекомендуется):
hermes gateway setup
Выберите Discord, затем вставьте токен бота и User ID, когда скрипт попросит.
Вручную. В файл ~/.hermes/.env добавьте:
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496
Затем запустите шлюз:
hermes gateway
В течение нескольких секунд бот должен появиться в Discord онлайн. Напишите ему — в личку или в канал, который он видит, — и проверьте ответ.
Для постоянной работы запускайте hermes gateway в фоне или как systemd-сервис; команда hermes gateway install ставит сервис, hermes gateway status показывает состояние.
Обязательная авторизация: без неё бот молчит
Начиная с версии 0.18 Hermes намеренно «fail closed» на внешне доступных адаптерах. Бот без DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES, DISCORD_ALLOWED_CHANNELS и без явного allow-all флага подключится успешно, но будет отклонять всех входящих до обычной обработки.
Если в логе ~/.hermes/logs/gateway.log есть строка:
No Discord access policy configured; inbound Discord messages will be denied by default.
— значит, политика доступа не задана, и правки модели или токена ничего не изменят.
Три способа задать доступ:
| Способ | Кому подходит |
|---|---|
| `DISCORD_ALLOWED_USERS` | Личный бот: список конкретных user ID |
| `DISCORD_ALLOWED_ROLES` | Команда модераторов или поддержки, состав которой меняется |
| `DISCORD_ALLOWED_CHANNELS` | Серверный бот, который должен работать только в определённых комнатах |
DISCORD_ALLOWED_ROLES работает по OR-семантике с DISCORD_ALLOWED_USERS: пользователь авторизован, если его ID в списке или у него есть одна из указанных ролей. Роли удобны тем, что новый модератор получает доступ сразу после выдачи роли — без правки конфига. При установке DISCORD_ALLOWED_ROLES Hermes автоматически включает Server Members Intent, потому что иначе Discord не присылает информацию о ролях. Роли указываются ID, не названиями.
Основные переменные окружения
Поведение Discord-бота описывается двумя файлами: ~/.hermes/.env для секретов и env-переключателей и ~/.hermes/config.yaml для структурных настроек. Переменные окружения всегда имеют приоритет над значениями из config.yaml.
| Переменная | По умолчанию | Что делает |
|---|---|---|
| `DISCORD_BOT_TOKEN` | — | Токен бота (обязателен) |
| `DISCORD_ALLOWED_USERS` | — | User ID через запятую, кому разрешено писать боту |
| `DISCORD_ALLOWED_ROLES` | — | ID ролей; OR с users, авто-включает Members Intent |
| `DISCORD_HOME_CHANNEL` | — | Канал для проактивных сообщений: вывод cron, напоминания, уведомления |
| `DISCORD_REQUIRE_MENTION` | `true` | Отвечать только на `@mention` в каналах |
| `DISCORD_FREE_RESPONSE_CHANNELS` | — | Каналы, где упоминание не требуется |
| `DISCORD_IGNORED_CHANNELS` | — | Каналы, где бот не отвечает никогда, даже при упоминании; приоритет выше остальных настроек |
| `DISCORD_ALLOWED_CHANNELS` | — | Только эти каналы (плюс личка, если разрешена) |
| `DISCORD_AUTO_THREAD` | `true` | Автосоздание треда на каждый `@mention` в текстовом канале |
| `DISCORD_NO_THREAD_CHANNELS` | — | Каналы, где бот отвечает прямо в канале, без треда |
| `DISCORD_ALLOW_BOTS` | `»none»` | Обработка сообщений от других ботов: `none`, `mentions`, `all` |
| `DISCORD_REACTIONS` | `true` | Реакции-подтверждения: 👀 при старте, ✅ при успехе, ❌ при ошибке |
| `DISCORD_HISTORY_BACKFILL` | `true` | Подклеивать недавний скроллбек канала к сообщению с упоминанием |
| `DISCORD_PROXY` | — | Прокси для Discord (HTTP, WebSocket, REST), поддерживает `socks5://` |
| `DISCORD_MAX_ATTACHMENT_BYTES` | `33554432` | Максимальный размер вложения (32 МиБ), `0` — без лимита |
Пример .env для командного чата:
DISCORD_BOT_TOKEN=ваш-токен
DISCORD_ALLOWED_USERS=284102345871466496
DISCORD_ALLOWED_ROLES=987654321098765432
DISCORD_HOME_CHANNEL=1234567890123456789
DISCORD_FREE_RESPONSE_CHANNELS=1234567890,9876543210
Слэш-команды и скиллы
Hermes регистрирует установленные скиллы как нативные Application Commands Discord. Они появляются в автоподстановке по / рядом со встроенными командами: каждый скилл становится командой (например, /code-review), принимает необязательный строковый параметр args и регистрируется при старте бота вместе с /model, /reset и /bg.
Никакой дополнительной настройки не нужно: любой скилл, установленный через hermes skills install, автоматически становится слэш-командой при следующем перезапуске шлюза. У Discord есть лимит в 100 application commands на бота — если скиллов больше, лишние пропускаются с предупреждением в логе.
Полезно знать:
/model без аргументов открывает интерактивный выбор модели: сначала провайдер, затем модель (до 25 вариантов в каждом выпадающем списке, таймаут 120 секунд). Доступно только авторизованным пользователям./verbose переключает режим отображения прогресса выполнения инструментов, если включена настройка display.tool_progress_command./sethome в любом канале, где присутствует бот, назначает этот канал домашним для проактивных сообщений./whoami показывает вашу область действия, уровень доступа (admin / user) и разрешённые команды.Разделение админов и обычных пользователей
По умолчанию любой разрешённый пользователь может запускать любую слэш-команду. Чтобы разделить права, добавьте в блок extra платформы Discord настройки allow_admin_from и user_allowed_commands:
gateway:
platforms:
discord:
extra:
allow_from:
- "123456789012345678" # админ
- "999888777666555444" # обычный пользователь
allow_admin_from:
- "123456789012345678"
user_allowed_commands:
- status
- model
- history
Пользователь из allow_admin_from может запускать все зарегистрированные команды — встроенные и плагинные. Остальные получают только список из user_allowed_commands плюс обязательный минимум /help и /whoami. Обычный текст в чат это не ограничивает: не-админы так же разговаривают с агентом, просто не могут вызывать произвольные команды.
Файлы, голос и форумы
Файлы. Discord-адаптер загружает вложения нативно: изображения приходят с превью, анимированные GIF воспроизводятся, видео открывается в плеере, аудио отправляется как голосовое сообщение, документы — с кнопкой скачивания. Входящие любого типа скачиваются, кэшируются в ~/.hermes/cache/documents/ и передаются агенту как событие типа DOCUMENT, чтобы он мог открыть файл через terminal или read_file. Небольшие текстовые файлы (код, JSON, YAML, HTML) автоматически инжектятся в промпт до 100 КиБ. Ограничение размера — 32 МиБ на файл по умолчанию.
Голос. Входящие голосовые сообщения автоматически транскрибируются настроенным STT-провайдером (локальный faster-whisper без ключа, Groq Whisper или OpenAI Whisper). Команда /voice tts заставляет бота присылать озвученные ответы. Hermes также умеет заходить в голосовой канал, слушать говорящих и отвечать голосом.
Форумы. Форумные каналы Discord (тип 15) не принимают сообщения напрямую — каждый пост является тредом. Hermes определяет такие каналы автоматически и создаёт новый пост-тред на каждую отправку: имя треда берётся из первой строки сообщения (до 100 символов), вложения едут вместе со стартовым сообщением. Важная деталь: один вызов — один тред, поэтому последовательные отправки в форум создадут отдельные посты.
Безопасность: что настроить до запуска
Авторизованные пользователи получают полный доступ к возможностям агента, включая работу с инструментами и системой. Поэтому:
DISCORD_ALLOWED_USERS или DISCORD_ALLOWED_ROLES — без них шлюз отклоняет всех по умолчанию.DISCORD_ALLOW_ALL_USERS=true на публичном сервере — только для доверенного приватного сервера или временного теста.DISCORD_ALLOW_BOTS в значении none. Discord автоматически упоминает автора при ответе, поэтому два бота с режимом mentions будут бесконечно зацикливать ответы друг другу. Схема «несколько профилей Hermes отвечают друг другу в общем канале» не поддерживается, и предохранителя от такого цикла нет.DISCORD_ALLOW_MENTION_EVERYONE и DISCORD_ALLOW_MENTION_ROLES по умолчанию false — оставьте так.Типичные проблемы и решения
Бот онлайн, но не отвечает. Две причины: выключен Message Content Intent или не настроена политика доступа (fail-closed). Включите Message Content Intent в Developer Portal → Bot → Privileged Gateway Intents → Save Changes, проверьте наличие DISCORD_ALLOWED_USERS или DISCORD_ALLOW_ALL_USERS, затем перезапустите шлюз.
Ошибка PrivilegedIntentsRequired при старте. Hermes запрашивает привилегированные интенты, которые не включены у бота, и Discord отклоняет WebSocket-соединение. Hermes всегда запрашивает Message Content Intent и дополнительно Server Members Intent, если allowlist использует имена вместо числовых ID или задан DISCORD_ALLOWED_ROLES. Включите интенты в портале и перезапустите шлюз — это ошибка конфигурации портала, а не сетевая нестабильность.
Бот отвечает в личке, но не в канале. Права канала переопределяют права сервера. Правой кнопкой по каналу → Edit Channel → Permissions, убедитесь, что у роли бота явно стоят View Channel, Send Messages и Read Message History.
Бот создаёт тред на каждый ответ, а вам это не нужно. Hermes по умолчанию автотредингует в серверных каналах. Переопределите для конкретных каналов через discord.no_thread_channels в config.yaml или DISCORD_NO_THREAD_CHANNELS.
Шлюз работает, но бот офлайн. Процесс жив, а WebSocket-соединение с Discord не установилось. Проверьте hermes gateway status: токен мог быть сброшен в портале без обновления .env.
REST API работает, а новые сообщения не приходят. REST и Gateway WebSocket — разные транспорты. Успешный fetch_user(), вернувший HTTP 200, не доказывает, что бот получает события. Hermes следит за здоровьем сокета (состояние ready, открытость сокета, возраст heartbeat ACK, латентность) и сам переподключается после серии неудачных проб — добавлять свой цикл реконнекта не нужно. Таймауты настраиваются в config.yaml:
discord:
websocket_liveness_interval_seconds: 15
websocket_liveness_failure_threshold: 2
websocket_heartbeat_ack_max_age_seconds: 60
websocket_max_latency_seconds: 30
FAQ
Нужны ли Hermes права администратора Discord?
Нет. Начните с минимального набора: View Channels, Send Messages, Read Message History, Attach Files и Embed Links. Этого достаточно, чтобы читать канал, получать упоминания и публиковать ответы. Расширяйте права только под доказанные задачи — например, Send Messages in Threads для тредов.
Почему бот в Discord онлайн, но не отвечает?
Онлайн доказывает только то, что Discord-подключение состоялось. Дальше Hermes применяет политику доступа, правила упоминаний, права канала и выполнение модели. Проверяйте по порядку: настроен ли allowlist (fail-closed), включён ли Message Content Intent, требует ли канал упоминания, есть ли у бота право читать канал, здоров ли провайдер модели. Не начинайте со сброса токена.
Как заставить бота отвечать без @упоминания?
Добавьте ID канала в DISCORD_FREE_RESPONSE_CHANNELS — тогда упоминание не требуется. Альтернатива — выключить требование упоминаний глобально через DISCORD_REQUIRE_MENTION=false. В free-response каналах Hermes отвечает прямо в канале, без создания треда.
Могут ли несколько человек в одном канале делиться одной беседой?
Нет, по умолчанию нет. При group_sessions_per_user: true каждый пользователь в общем канале имеет собственную историю и собственный слот выполняющегося агента. Выключайте изоляцию только если комнате действительно нужен один общий транскрипт — тогда участники разделят и расход токенов, и взаимные прерывания.
Работает ли бот в тредах и форумах?
Да. Треды используют собственное пространство имён сессий, а ответы остаются внутри треда. Форумные каналы Hermes распознаёт автоматически и создаёт пост-тред на каждую отправку. Сначала проверьте обычный канал, а потом конкретный тред или форум-пост: права, наследуемые от родителя, и правила упоминаний там могут отличаться.
Как запускать Discord-бота круглосуточно?
Запустите hermes gateway как systemd-сервис (hermes gateway install) на сервере, проверяйте состояние через hermes gateway status, а здоровье WebSocket — по логам шлюза и таймаутам websocket_* в конфиге. Для 24/7-бота оставьте DISCORD_COMMAND_SYNC_POLICY=safe, чтобы Hermes обновлял только изменившиеся слэш-команды, а не перерегистрировал все при каждом старте.