Настройка имеет значение

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

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

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

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

Контекст	Поведение
Личные сообщения	Hermes отвечает за каждое сообщение. Упоминание через `@` не требуется. Каждое личное сообщение имеет свою сессию.
Публичные/частные каналы	Hermes отвечает, когда вы упоминаете его через `@`. Без упоминания 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 как Системный администратор.
Перейдите в Системная консоль → Интеграции → Учётные записи ботов.
Установите Включить создание учётных записей ботов в true.
Нажмите Сохранить.
ℹ️ Info
Если у вас нет доступа к системному администратору, спросите его администратора Mattermost, вам нужно включить учётные записи ботов и создать одну для себя.

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

В Mattermost нажмите меню ☰ (слева вверху) → Интеграции → Учётные записи ботов.
Нажмите Добавить учётную запись бота.
Заполните данные:
Имя пользователя: например, hermes
Отражаемое имя: например, Агент Hermes
Описание: необязательно
Роль: Член достаточно
Нажмите Создать учётную запись бота.
Самое главное отобразит токен бота. Скопируйте его немедленно.
⚠️ Warning
[Токен отображается только один раз] Токен бота отображается только один раз при создании учетной записи бота. Если вы его потеряете, вам нужно будет заново сгенерировать его из настроек учётной записи бота. Никогда не делитесь своим токеном публично и не сохраняйте его в Git — любой, у кого есть этот токен, имеет полный контроль над дном.
Храните токен в безопасном месте (например, в менеджере паролей). Он понадобится для шага 5.
💡 Tip
Вы также можете использовать персональный токен доступа вместо учётной записи бота. Перейдите в Профиль → Безопасность → Персональные токены доступа → Создать токен. Это полезно, если вы хотите, чтобы Hermes публиковал сообщения от вашего имени, а не от отдельного пользователя-бота.

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

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

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

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

Шаг 4: Найдите свой ID пользователя Mattermost

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

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

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

⚠️ Warning

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

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

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq.id
```<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p>
Чтобы получить **ID канала**: нажмите на название канала → **Просмотреть информацию**. Идентификатор канала отображается на информационной панели. Это понадобится, если вы решите вручную установить домашний канал.</div>
## Шаг 5: Настраиваем агент Hermes

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

Запустите команду пошаговой настройки:
```bash
hermes gateway setup

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

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

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

# Обязательно
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Несколько разрешённых пользователей (через запятую)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Опционально: режим ответа (thread или off, по умолчанию: off)
# MATTERMOST_REPLY_MODE=thread

# Опционально: отвечать без @упоминания (по умолчанию: true = требуется упоминание)
# MATTERMOST_REQUIRE_MENTION=false

# Опционально: каналы, где бот отвечает без @упоминания (ID каналов через запятую)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

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

group_sessions_per_user: true

group_sessions_per_user: true изолирует контекст каждой участника внутри групп каналов и веток.

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

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

hermes gateway

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

💡 Tip

Вы можете активировать «шлюз Hermesа» в фоновом режиме или как сервис systemd для постоянной работы. Подробнее см. в документации по развёртыванию.

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

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

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

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

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

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

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

Режим ответа

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

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

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

MATTERMOST_REPLY_MODE=thread

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

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

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

Чтобы найти идентификатор канала в Mattermost: внедрите канал, нажмите на заголовок имени канала и перейдите по идентификатору в URL или детали канала.

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

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

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

Причина: Бот не является партнером канала, или 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://, без завершающего слеша). Убедитесь, что MATTERMOST_TOKEN действителен — форма с завитком:

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

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

Бот нет в сети

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

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

"Пользователь не разрешен" / Бот автоматически добавляет вас

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

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

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

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

mattermost:
  channel_prompts:
    "channel_id_abc123": |
      Вы — исследовательский ассистент. Сосредоточьтесь на академических источниках,
      цитированиях и кратком синтезе.
    "channel_id_def456": |
      Режим ревью кода. Будьте точны в отношении краевых случаев и
      влияния на производительность.

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

Безопасность
⚠️ Warning

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