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

sidebar_position: 8 title: "Mattermost" description: "Set up Hermes Agent as a Mattermost bot" lang: ru

Самая важная настройка

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

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

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

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

Контекст Поведение
DM Гермес отвечает на каждое сообщение. @mention не требуется. У каждого DM есть своя сессия.
Общественные/частные каналы Гермес отвечает, когда вы @mention его. Без упоминания Гермес игнорирует сообщение.
Темы Если MATTERMOST_REPLY_MODE=thread, Гермес ответит в теме под вашим сообщением. Контекст потока остается изолированным от родительского канала.
Общие каналы с несколькими пользователями По умолчанию 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. Откройте Системная консоль → Интеграция → Учетные записи ботов.
  3. Установите для параметра Включить создание учетной записи бота значение true.
  4. Нажмите Сохранить.

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

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

  1. В Mattermost нажмите меню ☰ (вверху слева) → Интеграции → Учётные записи ботов.
  2. Нажмите Добавить учетную запись бота.
  3. Заполните данные:
  4. Имя пользователя: например, hermes.
  5. Отображаемое имя: например, Hermes Agent.
  6. Описание: необязательно.
  7. Роль: достаточно Member
  8. Нажмите Создать учетную запись бота.
  9. Mattermost отобразит токен бота. Скопируйте его немедленно.

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

:::совет Вы также можете использовать токен личного доступа вместо учетной записи бота. Откройте Профиль → Безопасность → Токены личного доступа → Создать токен. Это полезно, если вы хотите, чтобы Hermes публиковал сообщения как ваш собственный пользователь, а не как отдельный пользователь бота.

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

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

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

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

Шаг 4: Найдите свой самый важный идентификатор пользователя

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

  1. Нажмите на свой аватар (левый верхний угол) → Профиль.
  2. Ваш идентификатор пользователя отображается в диалоговом окне профиля — щелкните его, чтобы скопировать.

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

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

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

:::совет Чтобы получить Идентификатор канала: нажмите на название канала → Просмотреть информацию. Идентификатор канала отображается на информационной панели. Это понадобится вам, если вы хотите установить домашний канал вручную.

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

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

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

hermes gateway setup

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

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

Добавьте следующее в свой файл ~/.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 в течение нескольких секунд. Отправьте ему сообщение — либо в DM, либо на канал, где оно было добавлено — для проверки.

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

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

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

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

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

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

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

Замените идентификатор фактическим идентификатором канала (нажмите имя канала → Просмотреть информацию → скопируйте идентификатор).

Режим ответа

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

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

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

MATTERMOST_REPLY_MODE=thread

Упоминание поведения

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

Переменная По умолчанию Описание
MATTERMOST_REQUIRE_MENTION true Установите false, чтобы отвечать на все сообщения в каналах (DM всегда работают).
MATTERMOST_FREE_RESPONSE_CHANNELS (нет) Идентификаторы каналов, разделенные запятыми, на которые бот отвечает без @mention, даже если require_mention имеет значение true.

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

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

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

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

Причина: бот не является участником канала, или MATTERMOST_ALLOWED_USERS не содержит ваш идентификатор пользователя.

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

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

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

Исправление: проверьте правильность 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://, no trailing slash). Check that MATTERMOST_TOKEN is valid — try it with curl:

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

If this returns your bot's user info, the token is valid. If it returns an error, regenerate the token.

Bot is offline

Cause: The Hermes gateway isn't running, or it failed to connect.

Fix: Check that hermes шлюз is running. Look at the terminal output for error messages. Common issues: wrong URL, expired token, Mattermost server unreachable.

"User not allowed" / Bot ignores you

Cause: Your User ID isn't in MATTERMOST_ALLOWED_USERS.

Fix: Add your User ID to MATTERMOST_ALLOWED_USERS in ~/.hermes/.env and restart the gateway. Remember: the User ID is a 26-character alphanumeric string, not your @username.

Per-Channel Prompts

Assign ephemeral system prompts to specific Mattermost channels. The prompt is injected at runtime on every turn — never persisted to transcript history — so changes take effect immediately.

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.

Keys are Mattermost channel IDs (find them in the channel URL or via the API). All messages in the matching channel get the prompt injected as an ephemeral system instruction.

Security

⚠️ Warning

Always set `MATTERMOST_ALLOWED_USERS` to restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access.

For more information on securing your Hermes Agent deployment, see the Security Guide.

Notes