Mattermost Hermes Agent — чат для команды

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

Никаких дополнительных библиотек устанавливать не нужно: адаптер использует aiohttp, который уже поставляется вместе с Hermes. Он работает как с Mattermost Team Edition (бесплатной), так и с Enterprise Edition.

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

Где вы с ним общаетесь	Что происходит
Личные сообщения	Hermes отвечает на каждое сообщение — `@mention` не нужен. У каждого личного диалога своя сессия.
Каналы	Hermes отвечает, когда вы упоминаете его через `@mention`. Без упоминания он игнорирует сообщение.
Треды	При `MATTERMOST_REPLY_MODE=thread` ответы вкладываются под вашим сообщением и остаются изолированными от родительского канала.
Общие каналы	История сессий по умолчанию изолирована для каждого пользователя, поэтому два человека в одном канале не делят общую переписку.

Это последнее поведение управляется параметром group_sessions_per_user в config.yaml:

group_sessions_per_user: true   # each person keeps their own context

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

Шаг 1: Включите бот-аккаунты (на стороне администратора)

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

Войдите в Mattermost как System Admin.
Перейдите в System Console → Integrations → Bot Accounts.
Установите Enable Bot Account Creation в true, затем нажмите Save.

Нет доступа администратора? Попросите вашего администратора Mattermost включить бот-аккаунты и создать один для вас.

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

Нажмите меню ☰ (слева вверху) → Integrations → Bot Accounts → Add Bot Account.
Заполните данные: Username, например hermes, Display Name, например Hermes Agent, и Role — достаточно Member.
Нажмите Create Bot Account, затем сразу скопируйте токен — он отображается только один раз. Потеряете его — придётся перегенерировать в настройках бот-аккаунта.

⚠️ Никогда не делитесь токеном и не коммитьте его в Git. Любой, у кого он есть, получает полный контроль над ботом.

Хотите, чтобы агент писал от вашего имени, а не от отдельного бота? Создайте personal access token в разделе Profile → Security → Personal Access Tokens → Create Token.

Шаг 3: Пригласите бота в каналы

Бот отвечает только в тех каналах, в которых состоит:

Откройте канал → нажмите на название канала → Add Members.
Найдите имя бота (например, hermes) и добавьте его.

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

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

Hermes использует ваш User ID — не имя пользователя — чтобы решить, кому разрешено общаться с ботом:

Нажмите на свой аватар (в левом верхнем углу) → Profile.
В диалоге отобразится ваш User ID: 26-символьная буквенно-цифровая строка, например 3uo8dkh1p7g1mfk49ear5fzs5c. Нажмите на неё, чтобы скопировать.

Его также можно получить через API:

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

Ваш User ID — это не @username, который вы видите в сообщениях. Вставка имени пользователя — самая частая причина, по которой бот молчит.

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

Запустите пошаговую настройку и выберите Mattermost, когда появится запрос — она спросит URL сервера, токен бота и ваш User ID:

hermes gateway setup

Или настройте вручную в ~/.hermes/.env:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

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

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

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

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

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

hermes gateway

Бот подключится к вашему серверу Mattermost в течение нескольких секунд. Отправьте ему личное сообщение или упомяните его через @mention в канале, куда он добавлен, чтобы проверить.

Шаг 6: Необязательные переключатели поведения

Настройка	Что она делает
`MATTERMOST_REPLY_MODE`	`off` (по умолчанию) публикует плоские сообщения; `thread` вкладывает ответы под вашим сообщением и поддерживает порядок в оживлённых каналах.
`MATTERMOST_REQUIRE_MENTION`	По умолчанию `true`. Установите `false`, чтобы отвечать на все сообщения в канале (личные сообщения работают всегда).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	ID каналов, которые пропускают требование упоминания, даже когда упоминания обязательны.
`MATTERMOST_HOME_CHANNEL`	Куда идут проактивные сообщения — вывод cron, напоминания, уведомления. Или введите `/sethome` в канале.
`mattermost.allowed_channels`	Ограничивает бота списком ID каналов; сообщения отовсюду ещё отбрасываются. Личные сообщения — исключение.
`mattermost.channel_prompts`	Внедряет эфемерный системный промпт для каждого канала — применяется на каждом ходу, никогда не сохраняется в историю переписки.

Когда бота упоминают через @mention, упоминание удаляется из сообщения перед обработкой, поэтому @hermes summarize this thread приходит как чистая инструкция.

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

Симптом	Вероятная причина	Решение
Бот игнорирует вас в каналах	Его нет в канале, или ваш User ID отсутствует в `MATTERMOST_ALLOWED_USERS`	Добавьте бота в канал, проверьте 26-символьный User ID, перезапустите шлюз
Бот не может публиковать	Недействительный токен или у бота нет прав в этом канале	Проверьте `MATTERMOST_TOKEN`, убедитесь, что аккаунт активен и является участником канала
Постоянные разрывы соединения	Обрывы WebSocket, перезапуски сервера или проблемы с прокси/файрволом	Адаптер переподключается с экспоненциальной задержкой (2с → 60с); для nginx убедитесь, что настроены заголовки обновления WebSocket
Ничего не происходит вообще	Шлюз не запущен или URL/токен неверны	Проверьте вывод `hermes gateway` и что `MATTERMOST_URL` содержит `https://` без завершающего слеша

Проверить токен напрямую можно так:

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

Защита бота

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

Что дальше?

Как только шлюз запущен, Mattermost ведёт себя как любой другой канал Hermes: слэш-команды, загрузка файлов, голосовые заметки, вывод cron, доставляемый в ваш домашний канал — всё на инфраструктуре, которую вы контролируете. Если вы предпочитаете хостинговый вариант, интеграция со Slack описывает путь через Socket Mode; если вы запускаете шлюзы на нескольких машинах, Hermes Relay соединяет их.