🏠 Главная › Документация › Мессенджеры

Настройка Mattermost

Hermes Agent интегрируется с Mattermost в качестве бота, позволяя вам общаться с вашим AI-ассистентом через личные сообщения или командные каналы. Mattermost — это самостоятельно размещаемая альтернатива Slack с открытым исходным кодом: вы запускаете её на своей собственной инфраструктуре, сохраняя полный контроль над данными. Бот подключается через REST API (v4) Mattermost и WebSocket для обработки событий в реальном времени, обрабатывает сообщения через пайплайн Hermes Agent (включая использование инструментов, память и рассуждения) и отвечает в реальном времени. Поддерживаются текст, вложения файлов, изображения и слеш-команды.

Не требуется никаких внешних библиотек Mattermost — адаптер использует aiohttp, который уже является зависимостью Hermes.

Перед настройкой — то, что большинство хочет узнать: как Hermes ведёт себя, оказавшись в вашем экземпляре Mattermost.

Как работает Hermes

Контекст Поведение
ЛС Hermes отвечает на каждое сообщение. @mention не требуется. Каждое ЛС имеет свою собственную сессию.
Публичные/приватные каналы Hermes отвечает, когда вы его @mention. Без упоминания Hermes игнорирует сообщение.
Ветки Если установлено MATTERMOST_REPLY_MODE=thread, Hermes отвечает в ветке под вашим сообщением. Контекст ветки остаётся изолированным от родительского канала.
Общие каналы с несколькими пользователями По умолчанию Hermes изолирует историю сессии для каждого пользователя внутри канала. Два человека, общающиеся в одном канале, не делят один транскрипт, если вы явно не отключите это.
Если вы хотите, чтобы Hermes отвечал в виде обсуждений в ветках (вложенных под ваше исходное сообщение), установите `MATTERMOST_REPLY_MODE=thread`. По умолчанию — `off`, что отправляет плоские сообщения в канал.

Модель сессий в Mattermost

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

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

group_sessions_per_user: true

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

group_sessions_per_user: false

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

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

Шаг 1: Включение учётных записей ботов

Учётные записи ботов должны быть включены на вашем сервере Mattermost, прежде чем вы сможете создать одну.

  1. Войдите в Mattermost как Системный администратор.

  2. Перейдите в System Console → Integrations → Bot Accounts.

  3. Установите Enable Bot Account Creation в значение true.

  4. Нажмите Save.

Если у вас нет доступа системного администратора, попросите вашего администратора Mattermost включить учётные записи ботов и создать одну для вас.

Шаг 2: Создание учётной записи бота

  1. В Mattermost нажмите меню ☰ (вверху слева) → Integrations → Bot Accounts.

  2. Нажмите Add Bot Account.

  3. Заполните данные:

  4. Username: например, hermes
  5. Display Name: например, Hermes Agent
  6. Description: необязательно

  7. Role: Member достаточно

  8. Нажмите Create Bot Account.

  9. Mattermost отобразит токен бота. Скопируйте его немедленно.

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

Сохраните токен в надёжном месте (например, в менеджере паролей). Он понадобится вам на шаге 5.

Вы также можете использовать **персональный токен доступа** вместо учётной записи бота. Перейдите в **Profile** → **Security** → **Personal Access Tokens** → **Create Token**. Это полезно, если вы хотите, чтобы Hermes публиковал сообщения от имени вашего пользователя, а не отдельного бота.

Шаг 3: Добавление бота в каналы

Бот должен быть участником любого канала, где вы хотите, чтобы он отвечал:

  1. Откройте канал, в который вы хотите добавить бота.

  2. Нажмите на название канала → Add Members.

  3. Найдите имя пользователя бота (например, hermes) и добавьте его.

Для ЛС просто откройте личное сообщение с ботом — он сможет отвечать сразу.

Шаг 4: Поиск вашего ID пользователя Mattermost

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

  1. Нажмите на свой аватар (в левом верхнем углу) → Profile.

  2. Ваш ID пользователя отображается в диалоге профиля — нажмите на него, чтобы скопировать.

Ваш ID пользователя представляет собой 26-символьную буквенно-цифровую строку, например 3uo8dkh1p7g1mfk49ear5fzs5c.

Ваш ID пользователя — это **не** ваше имя пользователя. Имя пользователя — это то, что отображается после `@` (например, `@alice`). ID пользователя — это длинный буквенно-цифровой идентификатор, который Mattermost использует внутренне.

Альтернатива: Вы также можете получить свой ID пользователя через API:

curl -H "Authorization: Bearer YOUR_T...span class="w"> \\
  https://your-mattermost-server/api/v4/users/me | jq .id
Чтобы получить **ID канала**: нажмите на название канала → **View Info**. ID канала отображается в информационной панели. Он понадобится вам, если вы хотите вручную установить домашний канал.

Шаг 5: Настройка Hermes Agent

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

hermes gateway setup

Выберите Mattermost при появлении запроса, затем вставьте URL вашего сервера, токен бота и ID пользователя, когда будет предложено.

Вариант B: Ручная настройка

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

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply mode (thread or off, default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without @mention (default: true = require mention)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where bot responds without @mention (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Дополнительные настройки поведения в ~/.hermes/config.yaml:

group_sessions_per_user: true

Запуск шлюза

После настройки запустите шлюз Mattermost:

hermes gateway

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

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

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

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

Использование слеш-команды

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

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

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

Замените ID на фактический ID канала (нажмите на название канала → View Info → скопируйте ID).

Режим ответов

Настройка MATTERMOST_REPLY_MODE управляет тем, как Hermes публикует ответы:

Режим Поведение
off (по умолчанию) Hermes публикует плоские сообщения в канале, как обычный пользователь.
thread Hermes отвечает в ветке под вашим исходным сообщением. Поддерживает каналы в чистоте при большом количестве переписки.

Установите в вашем ~/.hermes/.env:

MATTERMOST_REPLY_MODE=thread

Поведение при упоминаниях

По умолчанию бот отвечает в каналах только при @упоминании. Вы можете изменить это:

Переменная По умолчанию Описание
MATTERMOST_REQUIRE_MENTION true Установите false, чтобы отвечать на все сообщения в каналах (ЛС работают всегда).
MATTERMOST_FREE_RESPONSE_CHANNELS (нет) ID каналов, разделённые запятыми, где бот отвечает без @упоминания, даже если require_ention имеет значение true.

Чтобы найти ID канала в Mattermost: откройте канал, нажмите на заголовок с названием канала и найдите ID в URL или в деталях канала.

Когда бота @упоминают, упоминание автоматически удаляется из сообщения перед обработкой.

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

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

Причина: Бот не является участником канала, или MATTERMOST_ALLOWED_USERS не включает ваш ID пользователя.

Исправление: Добавьте бота в канал (название канала → Add Members → поиск бота). Убедитесь, что ваш ID пользователя указан в MATTERMOST_ALLOWED_USERS. Перезапустите шлюз.

Ошибки 403 Forbidden

Причина: Токен бота недействителен, или у бота нет разрешения на публикацию в канале.

Исправление: Проверьте, что MATTERMOST_TOKEN в вашем файле .env корректен. Убедитесь, что учётная запись бота не была деактивирована. Проверьте, что бот добавлен в канал. Если вы используете персональный токен доступа, убедитесь, что ваша учётная запись имеет необходимые разрешения.

Отключения WebSocket / циклы переподключения

Причина: Нестабильность сети, перезагрузки сервера Mattermost или проблемы с брандмауэром/прокси при подключениях WebSocket.

Исправление: Адаптер автоматически переподключается с экспоненциальной задержкой (2с → 60с). Проверьте конфигурацию WebSocket вашего сервера — обратные прокси (nginx, Apache) требуют настройки заголовков обновления WebSocket. Убедитесь, что брандмауэр не блокирует подключения WebSocket на вашем сервере Mattermost.

Для nginx убедитесь, что ваша конфигурация включает:

location /api/v4/websocket {
    proxy_pass http://mattermost-backend;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
}

Ошибка аутентификации при запуске

Причина: Неправильный токен или URL сервера.

Исправление: Проверьте, что MATTERMOST_URL указывает на ваш сервер Mattermost (включая https://, без завершающего слеша). Проверьте, что MATTERMOST_TOKEN действителен — попробуйте с curl:

curl -H "Authorization: Bearer YOUR_T...span class="w"> \\
  https://your-server/api/v4/users/me

Если это возвращает информацию о пользователе бота, токен действителен. Если возвращает ошибку, сгенерируйте токен заново.

Бот не в сети

Причина: Шлюз Hermes не запущен или не смог подключиться.

Исправление: Проверьте, запущен ли hermes gateway. Посмотрите на вывод терминала на наличие сообщений об ошибках. Частые проблемы: неправильный URL, истёкший токен, сервер Mattermost недоступен.

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

Причина: Ваш ID пользователя не указан в MATTERMOST_ALLOWED_USERS.

Исправление: Добавьте ваш ID пользователя в MATTERMOST_ALLOWED_USERS в ~/.hermes/.env и перезапустите шлюз. Помните: ID пользователя — это 26-символьная буквенно-цифровая строка, а не ваше @имя_пользователя.

Промпты для отдельных каналов

Назначьте эфемерные системные промпты для определённых каналов Mattermost. Промпт внедряется во время выполнения на каждом шаге — никогда не сохраняется в истории транскрипта, поэтому изменения вступают в силу немедленно.

mattermost:
  channel_prompts:
    "channel_id_abc123": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "channel_id_def456": |
      Code review mode. Be precise about edge cases and
      performance implications.

Ключи — это ID каналов Mattermost (найдите их в URL канала или через API). Все сообщения в соответствующем канале получают промпт в виде эфемерной системной инструкции.

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

Всегда устанавливайте `MATTERMOST_ALLOWED_USERS`, чтобы ограничить круг лиц, которые могут взаимодействовать с ботом. Без этого шлюз по умолчанию запрещает всех пользователей в качестве меры безопасности. Добавляйте только ID пользователей, которым вы доверяете — авторизованные пользователи имеют полный доступ к возможностям агента, включая использование инструментов и доступ к системе.

Для получения дополнительной информации о защите вашего развёртывания Hermes Agent см. Руководство по безопасности.

Примечания