🏠 Главная › User Guide › discord

sidebar_position: 3 title: "Discord" description: "Set up Hermes Agent as a Discord bot" lang: ru

Настройка Дискорда

Агент Hermes интегрируется с Discord в качестве бота, позволяя вам общаться с вашим ИИ-помощником через прямые сообщения или каналы сервера. Бот получает ваши сообщения, обрабатывает их через конвейер агента Hermes (включая использование инструментов, память и рассуждения) и отвечает в режиме реального времени. Он поддерживает текстовые, голосовые сообщения, вложения файлов и команды с косой чертой.

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

Как ведет себя Гермес

Контекст Поведение
DM Гермес отвечает на каждое сообщение. @mention не требуется. У каждого DM есть своя сессия.
Серверные каналы По умолчанию Hermes отвечает только тогда, когда вы @mention его. Если вы опубликуете сообщение в канале, не упомянув об этом, Гермес проигнорирует сообщение.
Каналы с бесплатным ответом Вы можете запретить упоминание определенных каналов с помощью DISCORD_FREE_RESPONSE_CHANNELS или запретить упоминания глобально с помощью DISCORD_REQUIRE_MENTION=false. На сообщения в этих каналах отвечают в режиме онлайн — автоматическая цепочка сообщений пропускается, поэтому канал остается простым чатом.
Темы Гермес отвечает в той же теме. Правила упоминаний по-прежнему применяются, если только эта тема или ее родительский канал не настроены как свободные ответы. Потоки остаются изолированными от родительского канала для истории сеансов.
Общие каналы с несколькими пользователями По умолчанию Hermes изолирует историю сеансов каждого пользователя внутри канала в целях безопасности и ясности. Два человека, разговаривающие по одному и тому же каналу, не будут использовать одну стенограмму, если вы явно не отключите ее.
Сообщения с упоминанием других пользователей Если DISCORD_IGNORE_NO_MENTION имеет значение true (по умолчанию), Hermes хранит молчание, если в сообщении @упоминаются другие пользователи, но не упоминается бот. Это не позволяет боту вступать в разговоры, адресованные другим людям. Установите false, если хотите, чтобы бот отвечал на все сообщения независимо от того, кто упомянут. Это применимо только к каналам сервера, а не к личным сообщениям.

:::совет Если вам нужен обычный канал помощи ботам, где люди смогут общаться с Гермесом, не отмечая его каждый раз, добавьте этот канал в DISCORD_FREE_RESPONSE_CHANNELS.

Модель шлюза Discord

Гермес в Discord — это не вебхук, который отвечает без сохранения состояния. Он проходит через полный шлюз обмена сообщениями, что означает, что каждое входящее сообщение проходит:

  1. авторизация (DISCORD_ALLOWED_USERS)
  2. проверка упоминаний/свободных ответов
  3. поиск сеанса
  4. загрузка стенограммы сеанса
  5. нормальное выполнение агента Hermes, включая инструменты, память и команды косой черты.
  6. доставка ответа обратно в Discord

Это важно, поскольку поведение на загруженном сервере зависит как от маршрутизации Discord, так и от политики сеанса Hermes.

Модель сеанса в Discord

По умолчанию:

Таким образом, если Алиса и Боб оба разговаривают с Гермесом в #research, Гермес по умолчанию рассматривает их как отдельные разговоры, даже если они используют один и тот же видимый канал Discord.

Это контролируется config.yaml:

group_sessions_per_user: true

Установите значение false только в том случае, если вы явно хотите, чтобы один общий разговор был для всей комнаты:

group_sessions_per_user: false

Общие сеансы могут быть полезны для совместной комнаты, но они также означают:

Прерывания и параллелизм

Hermes отслеживает запущенных агентов по сеансовому ключу.

По умолчанию group_sessions_per_user: true:

С group_sessions_per_user: false:

Это руководство проведет вас через весь процесс настройки — от создания бота на портале разработчиков Discord до отправки первого сообщения.

Шаг 1. Создайте приложение Discord

  1. Перейдите на Портал разработчиков Discord и войдите в свою учетную запись Discord.
  2. Нажмите Новое приложение в правом верхнем углу.
  3. Введите имя своего приложения (например, «Агент Гермес») и примите Условия обслуживания разработчика.
  4. Нажмите Создать.

Вы попадете на страницу Общая информация. Обратите внимание на Идентификатор приложения — он понадобится вам позже для создания URL-адреса приглашения.

Шаг 2: Создайте бота

  1. На левой боковой панели нажмите Бот.
  2. Discord автоматически создает пользователя-бота для вашего приложения. Вы увидите имя пользователя бота, которое вы можете настроить.
  3. В разделе Последовательность авторизации:
  4. Установите для Public Bot значение ON — необходимо для использования ссылки для приглашения, предоставленной Discord (рекомендуется). Это позволит вкладке «Установка» создать URL-адрес авторизации по умолчанию. – Оставьте для параметра Требовать предоставление кода OAuth2 значение ВЫКЛ.

:::совет На этой странице вы можете установить собственный аватар и баннер для своего бота. Это то, что пользователи увидят в Discord.

ℹ️ Info

[Альтернатива частного бота] Если вы предпочитаете, чтобы ваш бот оставался конфиденциальным (Public Bot = OFF), вы **должны** использовать метод **URL-адрес вручную** на шаге 5 вместо вкладки «Установка». Ссылка, предоставленная Discord, требует включения Public Bot.

Шаг 3. Включите намерения привилегированного шлюза

Это самый важный шаг во всей настройке. Если не включены правильные намерения, ваш бот подключится к Discord, но не сможет читать содержимое сообщения.

На странице Бот прокрутите вниз до пункта Намерения привилегированного шлюза. Вы увидите три переключателя:

Намерение Цель Необходимый?
Намерение присутствия Просмотр статуса пользователя онлайн/оффлайн Необязательно
Намерение участников сервера Доступ к списку участников, разрешение имен пользователей Обязательно
Намерение содержимого сообщения Читать текстовое содержимое сообщений Обязательно

Включите намерение участников сервера и намерение содержимого сообщения, переключив их в положение ВКЛ.

:::предупреждение[Это причина №1, по которой боты Discord не работают] Если ваш бот находится в сети, но никогда не отвечает на сообщения, Намерение содержимого сообщения почти наверняка отключено. Вернитесь на Портал разработчика, выберите свое приложение → Бот → Намерения привилегированного шлюза и убедитесь, что Намерение содержимого сообщения включено. Нажмите Сохранить изменения. Что касается количества серверов: - Если ваш бот находится на менее 100 серверах, вы можете просто свободно включать и выключать намерения. - Если ваш бот находится на 100 или более серверах, Discord потребует от вас отправить заявку на проверку для использования привилегированных намерений. Для личного использования это не проблема.

Нажмите Сохранить изменения внизу страницы.

Шаг 4: Получите токен бота

Токен бота — это учетные данные, которые агент Hermes использует для входа в систему в качестве вашего бота. Все еще на странице Бот:

  1. В разделе Токен нажмите Сбросить токен.
  2. Если в вашей учетной записи Discord включена двухфакторная аутентификация, введите код 2FA.
  3. Discord отобразит ваш новый токен. Скопируйте его немедленно.

:::предупреждение[Токен отображается только один раз] Токен отображается только один раз. Если вы потеряете его, вам придется сбросить его и создать новый. Никогда не делитесь своим токеном публично и не передавайте его в Git — любой, у кого есть этот токен, имеет полный контроль над вашим ботом. Сохраните токен в безопасном месте (например, в менеджере паролей). Он понадобится вам на шаге 8.

Шаг 5. Создайте URL-адрес приглашения

Вам понадобится URL-адрес OAuth2, чтобы пригласить бота на ваш сервер. Есть два способа сделать это:

Вариант A: Использование вкладки «Установка» (рекомендуется)

📝 Note

[Требуется общедоступный бот] Для этого метода необходимо, чтобы для **Public Bot** было установлено значение **ON** на шаге 2. Если для Public Bot установлено значение OFF, вместо этого используйте указанный ниже метод URL-адреса вручную.
  1. На левой боковой панели нажмите Установка.
  2. В разделе Контексты установки включите Гильдейскую установку.
  3. В поле Ссылка для установки выберите Ссылка, предоставленная Discord.
  4. В разделе Настройки установки по умолчанию для установки гильдии:
  5. Области: выберите bot и applications.commands.
  6. Разрешения: выберите разрешения, перечисленные ниже.

Вариант Б: URL-адрес вручную

Вы можете создать URL-адрес приглашения напрямую, используя этот формат:

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

Замените YOUR_APP_ID на идентификатор приложения из шага 1.

Необходимые разрешения

Вот минимальные разрешения, необходимые вашему боту:

Рекомендуемые дополнительные разрешения

Целые числа разрешений

Уровень Разрешения Целое число Что включено
Минимальный 117760 Просмотр каналов, отправка сообщений, чтение истории сообщений, прикрепление файлов
Рекомендуется 274878286912 Все вышеперечисленное, а также встраивание ссылок, отправка сообщений в темах, добавление реакций

Шаг 6: Пригласите на свой сервер

  1. Откройте URL-адрес приглашения в своем браузере (на вкладке «Установка» или URL-адрес, который вы создали вручную).
  2. В раскрывающемся списке Добавить на сервер выберите свой сервер.
  3. Нажмите Продолжить, затем Авторизовать.
  4. Заполните CAPTCHA, если будет предложено.

:::информация Чтобы пригласить бота, вам необходимо разрешение Управление сервером на сервере Discord. Если вы не видите свой сервер в раскрывающемся списке, попросите администратора сервера использовать ссылку для приглашения. После авторизации бот появится в списке участников вашего сервера (он будет отображаться как оффлайн, пока вы не запустите шлюз Hermes).

Шаг 7: Найдите свой идентификатор пользователя Discord

Агент Hermes использует ваш идентификатор пользователя Discord, чтобы контролировать, кто может взаимодействовать с ботом. Чтобы найти его:

  1. Откройте Discord (на рабочем столе или в веб-приложении).
  2. Откройте Настройки → Дополнительно → установите для параметра Режим разработчика значение ВКЛ.
  3. Закройте настройки.
  4. Щелкните правой кнопкой мыши свое имя пользователя (в сообщении, списке участников или вашем профиле) → Копировать идентификатор пользователя.

Ваш идентификатор пользователя — это длинное число, например 284102345871466496.

:::совет Режим разработчика также позволяет копировать Идентификаторы каналов и Идентификаторы серверов одним и тем же способом — щелкните правой кнопкой мыши имя канала или сервера и выберите «Копировать идентификатор». Вам понадобится идентификатор канала, если вы хотите установить домашний канал вручную.

Шаг 8: Настройка агента Hermes

Вариант A: Интерактивная настройка (рекомендуется)

Запустите команду управляемой настройки:

hermes gateway setup

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

Вариант Б: настройка вручную

Добавьте следующее в свой файл ~/.hermes/.env:

# Required
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

# Multiple allowed users (comma-separated)
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

Затем запустите шлюз:

hermes gateway

Бот должен подключиться к Discord в течение нескольких секунд. Отправьте ему сообщение — либо в DM, либо по каналу, который он видит — для проверки.

:::совет Вы можете запустить hermes gateway в фоновом режиме или в качестве службы systemd для постоянной работы. Подробности см. в документации по развертыванию.

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

Поведение Discord контролируется с помощью двух файлов: ~/.hermes/.env для учетных данных и переключателей уровня среды и ~/.hermes/config.yaml для структурированных настроек. Переменные среды всегда имеют приоритет над значениями config.yaml, если оба они установлены.

Переменные среды (.env)

Переменная Требуется По умолчанию Описание
DISCORD_BOT_TOKEN Да — Токен бота с Портала разработчиков Discord.
DISCORD_ALLOWED_USERS Да — Идентификаторы пользователей Discord, разделенные запятыми, позволяют взаимодействовать с ботом. Без этого или DISCORD_ALLOWED_ROLES шлюз запрещает доступ всем пользователям.
DISCORD_ALLOWED_ROLES Нет — Идентификаторы ролей Discord, разделенные запятыми. Авторизован любой участник с одной из этих ролей — ИЛИ семантика с DISCORD_ALLOWED_USERS. Автоматически включает Намерение участников сервера при подключении. Полезно, когда команды модераторов отменяются: новые моды получают доступ, как только роль предоставлена, не требуется никаких изменений конфигурации.
DISCORD_HOME_CHANNEL Нет — Идентификатор канала, по которому бот отправляет упреждающие сообщения (вывод cron, напоминания, уведомления).
DISCORD_HOME_CHANNEL_NAME Нет "Home" Отображаемое имя домашнего канала в журналах и выводе состояния.
DISCORD_COMMAND_SYNC_POLICY Нет "safe" Управляет встроенной синхронизацией запуска с помощью косой черты. "safe" различает существующие глобальные команды и обновляет только то, что изменилось, воссоздавая команды, когда изменения метаданных Discord невозможно применить с помощью патча. "bulk" сохраняет старое поведение tree.sync(). "off" полностью пропускает синхронизацию при запуске.
DISCORD_REQUIRE_MENTION Нет true При true бот отвечает в каналах сервера только при @mentioned. Установите false, чтобы отвечать на все сообщения в каждом канале.
DISCORD_FREE_RESPONSE_CHANNELS Нет — Идентификаторы каналов, разделенные запятыми, на которые бот отвечает, не требуя @mention, даже если DISCORD_REQUIRE_MENTION равно true.
DISCORD_IGNORE_NO_MENTION Нет true При true бот хранит молчание, если сообщение @mentions поступает другим пользователям, но не упоминает бот. Не позволяет боту вступать в разговоры, адресованные другим людям. Применяется только в каналах сервера, а не в личных сообщениях.
DISCORD_AUTO_THREAD Нет true При true автоматически создается новый поток для каждого @mention в текстовом канале, поэтому каждый разговор изолируется (аналогично поведению Slack). Сообщения, уже находящиеся внутри тредов или личных сообщений, не затрагиваются.
DISCORD_ALLOW_BOTS Нет "none" Управляет тем, как бот обрабатывает сообщения от других ботов Discord. "none" — игнорировать всех остальных ботов. "mentions" — принимать только сообщения ботов, которые @mention Hermes. "all" — принимать все сообщения бота.
DISCORD_REACTIONS Нет true При true бот добавляет эмодзи-реакции к сообщениям во время обработки (👀 при запуске, ✅ при успехе, ❌ при ошибке). Установите false, чтобы полностью отключить реакции.
DISCORD_IGNORED_CHANNELS Нет — Идентификаторы каналов, разделенные запятыми, на которые бот никогда не отвечает, даже если @mentioned. Имеет приоритет над всеми остальными настройками канала.
DISCORD_ALLOWED_CHANNELS Нет — Идентификаторы каналов, разделенные запятыми. Если этот параметр установлен, бот **отвечает только по этим каналам (плюс личные сообщения, если это разрешено). Переопределяет config.yaml discord.allowed_channels. Объедините с DISCORD_IGNORED_CHANNELS, чтобы выразить правила разрешения/запрета.
DISCORD_NO_THREAD_CHANNELS Нет — Идентификаторы каналов, разделенные запятыми, при которых бот отвечает непосредственно в канале, а не создает поток. Актуально только тогда, когда DISCORD_AUTO_THREAD равно true.
DISCORD_REPLY_TO_MODE Нет "first" Управляет поведением ответной ссылки: "off" — никогда не отвечать на исходное сообщение, "first" — ответная ссылка только на первый фрагмент сообщения (по умолчанию), "all" — ответная ссылка на каждый фрагмент.
DISCORD_ALLOW_MENTION_EVERYONE Нет false При false (по умолчанию) бот не может выполнить ping @everyone или @here, даже если его ответ содержит эти токены. Установите значение true, чтобы снова принять участие. См. Контроль упоминаний ниже.
DISCORD_ALLOW_MENTION_ROLES Нет false Когда false (по умолчанию), бот не может пинговать упоминания @role. Установите true, чтобы разрешить.
DISCORD_ALLOW_MENTION_USERS Нет true Если true (по умолчанию), бот может пинговать отдельных пользователей по идентификатору.
DISCORD_ALLOW_MENTION_REPLIED_USER Нет true Когда true (по умолчанию) при ответе на сообщение проверяется первоначальный автор.
DISCORD_PROXY Нет — URL-адрес прокси-сервера для подключений Discord (HTTP, WebSocket, REST). Переопределяет HTTPS_PROXY/ALL_PROXY. Поддерживает схемы http://, https://, и socks5://.
HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS Нет 0.6 Окно льготного периода, в котором адаптер ожидает перед очисткой текстового фрагмента, находящегося в очереди. Полезно для сглаживания потокового вывода.
HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS Нет 2.0 Задержка между разделенными частями, когда одно сообщение превышает ограничение длины Discord.

Файл конфигурации (config.yaml)

Раздел discord в ~/.hermes/config.yaml отражает приведенные выше переменные окружения. Настройки Config.yaml применяются по умолчанию — если эквивалентная переменная env уже установлена, побеждает переменная env.

# Discord-specific settings
discord:
  require_mention: true           # Require @mention in server channels
  free_response_channels: ""      # Comma-separated channel IDs (or YAML list)
  auto_thread: true               # Auto-create threads on @mention
  reactions: true                 # Add emoji reactions during processing
  ignored_channels: []            # Channel IDs where bot never responds
  no_thread_channels: []          # Channel IDs where bot responds without threading
  channel_prompts: {}             # Per-channel ephemeral system prompts
  allow_mentions:                 # What the bot is allowed to ping (safe defaults)
    everyone: false               # @everyone / @here pings (default: false)
    roles: false                  # @role pings (default: false)
    users: true                   # @user pings (default: true)
    replied_user: true            # reply-reference pings the author (default: true)

# Session isolation (applies to all gateway platforms, not just Discord)
group_sessions_per_user: true     # Isolate sessions per user in shared channels

discord.require_mention

Тип: логическое значение — По умолчанию: true

Если эта функция включена, бот отвечает только в каналах сервера, если напрямую @mentioned. DM всегда получают ответ независимо от этого параметра.

discord.free_response_channels

Тип: строка или список — По умолчанию: ""

Идентификаторы каналов, по которым бот отвечает на все сообщения без необходимости @mention. Принимает либо строку, разделенную запятыми, либо список YAML:

# String format
discord:
  free_response_channels: "1234567890,9876543210"

# List format
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

Если родительский канал потока находится в этом списке, поток также не подлежит упоминанию.

Каналы с бесплатными ответами также пропускают автоматическое создание цепочек — бот отвечает прямо в сети, а не создает новую цепочку для каждого сообщения. Это позволяет использовать канал в качестве облегченной поверхности для чата. Если вам нужно многопоточное поведение, не указывайте канал как свободный ответ (вместо этого используйте обычный поток @mention).

discord.auto_thread

Тип: логическое значение — По умолчанию: true

Если этот параметр включен, каждый @mention в обычном текстовом канале автоматически создает новую ветку для разговора. Это сохраняет основной канал чистым и дает каждому разговору собственную изолированную историю сеансов. После создания потока последующие сообщения в этом потоке не требуют @mention — бот знает, что он уже участвует.

Этот параметр не влияет на сообщения, отправленные в существующих темах или личных сообщениях. Каналы, перечисленные в discord.free_response_channels или discord.no_thread_channels, также обходят автоматическую поточность и вместо этого получают встроенные ответы.

discord.reactions

Тип: логическое значение — По умолчанию: true

Определяет, добавляет ли бот эмодзи-реакции на сообщения в качестве визуальной обратной связи: - 👀 добавляется, когда бот начинает обрабатывать ваше сообщение - ✅ добавляется, когда ответ доставлен успешно - ❌ добавляется, если при обработке возникает ошибка

Отключите эту функцию, если реакции вас отвлекают или если роль бота не имеет разрешения Добавлять реакции.

discord.ignored_channels

Тип: строка или список — По умолчанию: []

Идентификаторы каналов, на которые бот никогда не отвечает, даже если напрямую @mentioned. Это имеет наивысший приоритет — если канал есть в этом списке, бот молча игнорирует все сообщения там, независимо от require_mention, free_response_channels или любой другой настройки.

# String format
discord:
  ignored_channels: "1234567890,9876543210"

# List format
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

Если родительский канал потока находится в этом списке, сообщения в этом потоке также игнорируются.

discord.no_thread_channels

Тип: строка или список — По умолчанию: []

Идентификаторы каналов, на которых бот отвечает непосредственно в канале, а не автоматически создает поток. Это имеет эффект только в том случае, если auto_thread равно true (по умолчанию). В этих каналах бот отвечает как обычное сообщение, а не создает новую ветку.

discord:
  no_thread_channels:
    - 1234567890  # Bot responds inline here

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

discord.channel_prompts

Тип: сопоставление — По умолчанию: {}

Поканальные эфемерные системные подсказки, которые вводятся на каждом этапе в соответствующий канал или поток Discord и не сохраняются в истории расшифровки.

discord:
  channel_prompts:
    "1234567890": |
      This channel is for research tasks. Prefer deep comparisons,
      citations, and concise synthesis.
    "9876543210": |
      This forum is for therapy-style support. Be warm, grounded,
      and non-judgmental.

Поведение: - Точное совпадение идентификатора потока/канала. - Если сообщение поступает в ветку или сообщение на форуме и эта ветка не имеет явной записи, Hermes возвращается к родительскому идентификатору канала/форума. — Подсказки применяются эфемерно во время выполнения, поэтому их изменение сразу же влияет на будущие ходы, не переписывая историю прошлых сеансов.

group_sessions_per_user

Тип: логическое значение — По умолчанию: true

Это глобальная настройка шлюза (не специфичная для Discord), которая определяет, будут ли пользователи в одном канале получать изолированные истории сеансов.

Когда true: Алиса и Боб разговаривают в #research, каждый ведет отдельный разговор с Гермесом. Когда false: весь канал использует одну расшифровку разговора и один слот для работающего агента.

group_sessions_per_user: true

Подробные сведения о каждом режиме см. в разделе Модель сеанса выше.

display.tool_progress

Тип: строка — По умолчанию: "all" — Значения: off, new, all, verbose

Определяет, отправляет ли бот сообщения о ходе выполнения в чат во время обработки (например, «Чтение файла...», «Выполнение команды терминала...»). Это глобальная настройка шлюза, которая применяется ко всем платформам.

display:
  tool_progress: "all"    # off | new | all | verbose

display.tool_progress_command

Тип: логическое значение — По умолчанию: false

Если этот параметр включен, команда косой черты /verbose становится доступной в шлюзе, позволяя переключаться между режимами работы инструмента (off → new → all → verbose → off) без редактирования config.yaml.

display:
  tool_progress_command: true

Интерактивный выбор моделей

Отправьте /model без аргументов в канал Discord, чтобы открыть раскрывающийся список моделей:

  1. Выбор поставщика — раскрывающийся список «Выбрать», в котором показаны доступные поставщики (до 25).
  2. Выбор модели — второй раскрывающийся список с моделями выбранного провайдера (до 25).

Тайм-аут сборщика истекает через 120 секунд. С ним могут взаимодействовать только авторизованные пользователи (в DISCORD_ALLOWED_USERS). Если вы знаете название модели, введите /model <name> напрямую.

Собственные слэш-команды для навыков

Hermes автоматически регистрирует установленные навыки как собственные команды приложения Discord. Это означает, что навыки появляются в меню автозаполнения / Discord вместе со встроенными командами.

Никакой дополнительной настройки не требуется — любой навык, установленный через hermes skills install, автоматически регистрируется как косая черта в Discord при следующем перезапуске шлюза.

Отключение регистрации слэш-команд

Если вы запускаете несколько шлюзов Hermes для одного и того же приложения Discord (например, промежуточное + производственное), только один из них должен владеть глобальной регистрацией слэш-команды — в противном случае побеждает последний запуск, и регистрации отменяются. Отключите регистрацию косой черты на шлюзе «последователя»:

gateway:
  platforms:
    discord:
      extra:
        slash_commands: false   # default: true

Если оставить это значение true на «основном» шлюзе, сохраняется нормальное поведение — глобальные команды /-меню для встроенных модулей и установленных навыков.

Отправка мультимедиа (send_message + теги MEDIA:)

Адаптер Discord поддерживает загрузку файлов для каждого распространенного типа мультимедиа с помощью инструмента send_message и встроенных тегов MEDIA:/path/to/file, создаваемых агентом:

Тип Как это доставляется
Изображения (PNG/JPG/WebP) Вложенное изображение Discord со встроенным предварительным просмотром
Анимированные GIF-файлы send_animation загружается как animation.gif, поэтому Discord воспроизводит его онлайн (а не как статическую миниатюру)
Видео (MP4/MOV) send_video — родной видеоплеер
Аудио/Голос send_voice — если возможно, собственное голосовое сообщение, в противном случае вложение файла
Документы (PDF/ZIP/docx/и т. д.) send_document — родное вложение с кнопкой скачивания

Ограничение размера загрузки Discord зависит от уровня повышения сервера (25 МБ бесплатно, до 500 МБ). Если Hermes получает HTTP 413, адаптер возвращается к ссылке, указывающей на путь локального кэша, вместо того, чтобы молча выйти из строя.

Домашний канал

Вы можете назначить «домашний канал», куда бот будет отправлять упреждающие сообщения (например, выходные данные задания cron, напоминания и уведомления). Есть два способа установить его:

Использование команды косой черты

Введите /sethome в любом канале Discord, где присутствует бот. Этот канал становится домашним каналом.

Ручная настройка

Добавьте это в свой ~/.hermes/.env:

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

Замените идентификатор фактическим идентификатором канала (щелкните правой кнопкой мыши → Копировать идентификатор канала с включенным режимом разработчика).

Голосовые сообщения

Агент Hermes поддерживает голосовые сообщения Discord:

Полное руководство по настройке и эксплуатации см.: - Голосовой режим - Использовать голосовой режим с Hermes

Каналы форума

Каналы форума Discord (тип 15) не принимают прямые сообщения — каждое сообщение на форуме должно быть веткой. Hermes автоматически определяет каналы форума и создает новое сообщение в теме всякий раз, когда его необходимо отправить туда, поэтому send_message, TTS, изображения, голосовые сообщения и вложения файлов работают без специальной обработки со стороны агента.

Обновление каталога (/channels refresh на платформах, которые его предоставляют, или перезапуск шлюза) заполняет кеш всеми каналами форума, созданными после запуска бота.

Устранение неполадок

Бот онлайн, но не отвечает на сообщения

Причина: Цель содержимого сообщения отключена.

Исправление: перейдите на Портал разработчика → ваше приложение → Бот → Намерения привилегированного шлюза → включите Намерение содержимого сообщения → Сохранить изменения. Перезапустите шлюз.

Ошибка «Запрещенные намерения» при запуске

Причина: ваш код запрашивает намерения, которые не включены на портале разработчика.

Исправление: включите все три цели привилегированного шлюза (присутствие, участники сервера, содержимое сообщения) в настройках бота, а затем перезапустите.

Бот не видит сообщения в определенном канале

Причина: Роль бота не имеет разрешения на просмотр этого канала.

Исправление: в Discord перейдите в настройки канала → Разрешения → добавьте роль бота с включенными параметрами Просмотр канала и Чтение истории сообщений.

403 Запрещенные ошибки

Причина: у бота отсутствуют необходимые разрешения.

Исправление: повторно пригласите бота с правильными разрешениями, используя URL-адрес из шага 5, или вручную настройте разрешения роли бота в разделе «Настройки сервера» → «Роли».

Бот не в сети

Причина: шлюз Hermes не работает или неверный токен.

Исправление: убедитесь, что hermes gateway работает. Проверьте DISCORD_BOT_TOKEN в своем файле .env. Если вы недавно сбросили токен, обновите его.

«Пользователь не разрешен» / Бот вас игнорирует

Причина: вашего идентификатора пользователя нет в DISCORD_ALLOWED_USERS.

Исправление: добавьте свой идентификатор пользователя в DISCORD_ALLOWED_USERS в ~/.hermes/.env и перезапустите шлюз.

Люди в одном канале неожиданно делятся контекстом

Причина: group_sessions_per_user отключен, или платформа не может предоставить идентификатор пользователя для сообщений в этом контексте.

Исправление: установите это в ~/.hermes/config.yaml и перезапустите шлюз:

group_sessions_per_user: true

Если вы намеренно хотите провести разговор в общей комнате, отключите его — просто ожидайте общей истории стенограмм и общего поведения прерываний.

Безопасность

:::предупреждение Всегда устанавливайте DISCORD_ALLOWED_USERS (или DISCORD_ALLOWED_ROLES), чтобы ограничить круг лиц, которые могут взаимодействовать с ботом. Без того и другого шлюз по умолчанию запрещает доступ всем пользователям в качестве меры безопасности. Авторизуйте только тех, кому вы доверяете: авторизованные пользователи имеют полный доступ к возможностям агента, включая использование инструментов и доступ к системе.

Управление доступом на основе ролей

Для серверов, где доступ управляется ролями, а не отдельными списками пользователей (группы модераторов, сотрудники службы поддержки, внутренние инструменты), используйте DISCORD_ALLOWED_ROLES — список идентификаторов ролей, разделенных запятыми. Любой участник с одной из этих ролей авторизован.

# ~/.hermes/.env — works alongside or instead of DISCORD_ALLOWED_USERS
DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

Семантика:

Это предпочтительная схема при смене команды модераторов — новые модераторы получают доступ в тот момент, когда им предоставлена ​​роль, без необходимости редактирования .env или перезапуска шлюза.

Контроль упоминаний

По умолчанию Hermes блокирует пинг @everyone, @here и упоминания ролей бота, даже если его ответ содержит эти токены. Это предотвращает рассылку спама по всему серверу из-за плохо сформулированного приглашения или отраженного пользовательского контента. Индивидуальные пинги @user и пинги с ссылкой на ответ (маленькая микросхема «ответ на…») остаются включенными, поэтому нормальный разговор по-прежнему работает.

Вы можете ослабить эти значения по умолчанию с помощью env vars или config.yaml:

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # allow the bot to ping @everyone / @here
    roles: false         # allow the bot to ping @role mentions
    users: true          # allow the bot to ping individual @users
    replied_user: true   # ping the author when replying to their message

# ~/.hermes/.env — env vars win over config.yaml
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true

:::совет Оставьте everyone и roles на false, если вы точно не знаете, зачем они вам нужны. LLM очень легко создать строку @everyone внутри нормально выглядящего ответа; без этой защиты это уведомило бы каждого члена вашего сервера. Дополнительную информацию о защите вашего агента Hermes см. в Руководстве по безопасности.