Настройка Mattermost

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

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

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

Как ведёт себя Hermes

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

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

• у каждого DM своя сессия
• у каждого треда своё пространство имён сессии
• у каждого пользователя в общем канале своя сессия внутри этого канала

За это отвечает config.yaml:

group_sessions_per_user: true

Ставьте false, только если вам и правда нужен один общий разговор на весь канал:

group_sessions_per_user: false

Общие сессии бывают удобны для совместной работы в канале, но есть оборотная сторона:

• участники делят разрастающийся контекст и расход токенов
• одна длинная задача с кучей вызовов инструментов раздувает контекст для всех остальных
• запущенный кем-то цикл агента может прервать чужое уточнение в том же канале

Дальше — полный путь настройки: от создания бота в Mattermost до первого отправленного сообщения.

Шаг 1. Включите бот-аккаунты

Прежде чем создавать бота, на сервере Mattermost нужно разрешить бот-аккаунты.

1. Войдите в Mattermost под системным администратором (System Admin).
2. Откройте System Console → Integrations → Bot Accounts.
3. Переведите Enable Bot Account Creation в true.
4. Нажмите Save.

Шаг 2. Создайте бот-аккаунт

1. В Mattermost откройте меню ☰ (слева сверху) → Integrations → Bot Accounts.
2. Нажмите Add Bot Account.
3. Заполните поля:
   • Username: например, hermes
   • Display Name: например, Hermes Agent
   • Description: по желанию
   • Role: достаточно Member
4. Нажмите Create Bot Account.
5. Mattermost покажет токен бота. Скопируйте его сразу же.

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

Шаг 3. Добавьте бота в каналы

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

1. Откройте нужный канал.
2. Кликните по названию канала → Add Members.
3. Найдите имя своего бота (например, hermes) и добавьте его.

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

Шаг 4. Найдите свой Mattermost User ID

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

1. Кликните по своему аватару (левый верхний угол) → Profile.
2. User ID показан в окне профиля — щёлкните по нему, чтобы скопировать.

User ID — это 26-символьная буквенно-цифровая строка вроде 3uo8dkh1p7g1mfk49ear5fzs5c.

Другой способ — получить User ID через API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

Шаг 5. Настройте Hermes Agent

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

Запустите пошаговый мастер:

hermes gateway setup

Выберите Mattermost в списке, затем по запросу вставьте URL сервера, токен бота и свой user 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

• group_sessions_per_user: true держит контекст каждого участника изолированным внутри общих каналов и тредов

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

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

hermes gateway

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

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

Можно назначить «домашний канал» (home channel), куда бот шлёт сообщения по своей инициативе: вывод cron-задач, напоминания, уведомления. Задать его можно двумя способами.

Через слэш-команду

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

Через настройку вручную

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

Подставьте сюда реальный ID канала (кликните по названию канала → View Info → скопируйте ID).

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

Параметр MATTERMOST_REPLY_MODE определяет, как именно Hermes публикует ответы:

Задаётся в ~/.hermes/.env:

MATTERMOST_REPLY_MODE=thread

Реакция на упоминания

По умолчанию в каналах бот отвечает только на @упоминание. Это можно поменять:

Как найти ID канала в Mattermost: откройте канал, кликните по заголовку с его названием и найдите ID в URL или в деталях канала.

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

Список разрешённых каналов (allowed_channels)

Ограничьте бота фиксированным набором каналов Mattermost. Если список задан, бот отвечает только в тех каналах, чей ID в нём перечислен; сообщения из любого другого канала молча отбрасываются — даже при @упоминании.

Личные сообщения под этот фильтр не попадают, поэтому авторизованные пользователи всегда могут достучаться до бота в DM.

mattermost:
  allowed_channels:
    - "abc123def456ghi789jkl012mno"   # #ops
    - "xyz987uvw654rst321opq098nml"   # #incident-response

Либо через переменную окружения (через запятую):

MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml"

Как это работает:

• Пусто / не задано → ограничений нет (полная обратная совместимость).
• Список не пуст → ID канала обязан быть в нём, иначе сообщение отсекается ещё до любых других проверок (требование упоминания, MATTERMOST_FREE_RESPONSE_CHANNELS и прочих).
• ID канала ищите в интерфейсе Mattermost → заголовок канала → «View Info», либо считайте из URL канала.

См. также: разделение слэш-команд на admin/user.

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

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

Причина: бот не состоит в канале, либо в MATTERMOST_ALLOWED_USERS нет вашего User ID.

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

Ошибки 403 Forbidden

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

Что делать: проверьте, что MATTERMOST_TOKEN в .env указан верно. Убедитесь, что бот-аккаунт не деактивирован. Проверьте, что бот добавлен в канал. Если используете персональный токен доступа — убедитесь, что у вашей учётки есть нужные права.

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

Причина: нестабильная сеть, перезапуски сервера Mattermost или проблемы с WebSocket на стороне фаервола/прокси.

Что делать: адаптер переподключается сам, с экспоненциальной задержкой (2s → 60s). Проверьте конфигурацию 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;
}

«Failed to authenticate» при старте

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

Что делать: проверьте, что MATTERMOST_URL указывает на ваш сервер Mattermost (с https://, без слэша на конце). Убедитесь, что MATTERMOST_TOKEN валиден — проверьте через curl:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

Если в ответ приходит информация о пользователе вашего бота — токен рабочий. Если возвращается ошибка — перевыпустите токен.

Бот офлайн

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

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

«User not allowed» / бот вас игнорирует

Причина: вашего User ID нет в MATTERMOST_ALLOWED_USERS.

Что делать: добавьте свой User ID в MATTERMOST_ALLOWED_USERS в ~/.hermes/.env и перезапустите шлюз. Напоминание: User ID — это 26-символьная буквенно-цифровая строка, а не ваш @username.

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

Закрепите за конкретными каналами 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). Все сообщения в нужном канале получают свой промпт в виде временной системной инструкции.

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

Подробнее о защите развёртывания Hermes Agent — в руководстве по безопасности.

Заметки

• Дружит с self-hosted: работает с любым self-hosted-инстансом Mattermost. Аккаунт Mattermost Cloud или подписка не нужны.
• Без лишних зависимостей: адаптер использует aiohttp для HTTP и WebSocket, а он уже идёт в комплекте с Hermes Agent.
• Совместимость с Team Edition: работает и с бесплатной Mattermost Team Edition, и с Enterprise Edition.