Перейти к содержанию

Mattermost

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

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

Контекст Поведение
ЛС Hermes отвечает на каждое сообщение. @упоминание не требуется. Каждое ЛС имеет свою собственную сессию.
Публичные/приватные каналы Hermes отвечает, когда вы @упоминаете его. Без упоминания Hermes игнорирует сообщение.
Треды Если MATTERMOST_REPLY_MODE=thread, Hermes отвечает в треде под вашим сообщением. Контекст треда изолирован от родительского канала.
Общие каналы с несколькими пользователями По умолчанию Hermes изолирует историю сессии для каждого пользователя внутри канала. Два человека, общающиеся в одном канале, не делят один транскрипт, если вы явно не отключите это.

tip Если вы хотите, чтобы Hermes отвечал в виде threaded-бесед (вложенных под ваше исходное сообщение), установите MATTERMOST_REPLY_MODE=thread. По умолчанию стоит off, что отправляет плоские сообщения в канал.

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

По умолчанию: * каждое ЛС получает свою собственную сессию * каждый тред получает своё пространство имён сессии * каждый пользователь в общем канале получает свою собственную сессию внутри этого канала

Это контролируется через config.yaml: [code] group_sessions_per_user: true

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

[/code] Общие сессии могут быть полезны для коллаборативного канала, но они также означают: * пользователи делят рост контекста и затраты на токены * длительная задача одного человека с большим количеством инструментов может раздуть контекст для всех остальных * выполняющаяся задача одного человека может прервать продолжение другого в том же канале

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

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

Учётные записи ботов должны быть включены на вашем сервере Mattermost, прежде чем вы сможете создать бота. 1. Войдите в Mattermost как системный администратор. 2. Перейдите в System Console → Integrations → Bot Accounts. 3. Установите Enable Bot Account Creation в true. 4. Нажмите Save.

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

Шаг 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 покажет токен бота. Скопируйте его немедленно.

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

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

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

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

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

Шаг 4: Поиск вашего User ID в Mattermost​

Hermes Agent использует ваш User ID в Mattermost для контроля того, кто может взаимодействовать с ботом. Чтобы найти его: 1. Нажмите на ваш аватар (в верхнем левом углу) → Profile. 2. Ваш User ID отображается в диалоговом окне профиля — нажмите на него, чтобы скопировать.

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

warning Ваш User ID — это не ваше имя пользователя. Имя пользователя — это то, что отображается после @ (например, @alice). User ID — это длинный буквенно-цифровой идентификатор, который Mattermost использует внутри. Альтернатива: Вы также можете получить свой User ID через API: [code] curl -H "Authorization: Bearer YOUR_TOKEN" \ https://your-mattermost-server/api/v4/users/me | jq .id

[/code]

tip Чтобы получить Channel ID: нажмите на название канала → View Info. Channel ID отображается в информационной панели. Он понадобится вам, если вы хотите вручную установить домашний канал.

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

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

Запустите команду интерактивной настройки: [code] hermes gateway setup

[/code] Выберите Mattermost при появлении запроса, затем вставьте URL вашего сервера, токен бота и user ID, когда вас попросят.

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

Добавьте следующее в ваш файл ~/.hermes/.env: [code] # Обязательно 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

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

[/code] * group_sessions_per_user: true сохраняет контекст каждого участника изолированным внутри общих каналов и тредов

Запуск шлюза​

После настройки запустите шлюз Mattermost: [code] hermes gateway

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

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

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

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

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

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

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

Добавьте это в ваш ~/.hermes/.env: [code] MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

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

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

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

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

Установите в вашем ~/.hermes/.env: [code] MATTERMOST_REPLY_MODE=thread

[/code]

Поведение упоминаний​

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

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

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

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

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

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

Ошибки 403 Forbidden​

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

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

Причина: Нестабильность сети, перезапуски сервера Mattermost или проблемы с брандмауэром/прокси для WebSocket-соединений. Решение: Адаптер автоматически переподключается с экспоненциальной задержкой (2с → 60с). Проверьте конфигурацию WebSocket вашего сервера — обратные прокси (nginx, Apache) должны иметь настроенные заголовки обновления WebSocket. Убедитесь, что брандмауэр не блокирует WebSocket-соединения на вашем сервере Mattermost. Для nginx убедитесь, что ваша конфигурация включает: [code] location /api/v4/websocket { proxy_pass http://mattermost-backend; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 600s; }

[/code]

«Failed to authenticate» при запуске​

Причина: Токен или URL сервера неправильные. Решение: Проверьте, что MATTERMOST_URL указывает на ваш сервер Mattermost (включая https://, без завершающего слеша). Убедитесь, что MATTERMOST_TOKEN действителен — попробуйте его с curl: [code] curl -H "Authorization: Bearer YOUR_TOKEN" \ https://your-server/api/v4/users/me

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

Бот офлайн​

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

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

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

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

Назначайте эфемерные системные промпты для определённых каналов Mattermost. Промпт внедряется во время выполнения на каждом шаге — никогда не сохраняется в истории транскрипта — поэтому изменения вступают в силу немедленно. [code] mattermost: channel_prompts: "channel_id_abc123": | Ты — исследовательский ассистент. Сосредоточься на академических источниках, цитированиях и кратком синтезе. "channel_id_def456": | Режим ревью кода. Будь точен в отношении граничных случаев и влияния на производительность.

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

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

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

Примечания​