Настройка Mattermost

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

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

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

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

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

подсказка

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

Модель сеанса в Mattermost

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

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

Это контролируется в config.yaml:

group_sessions_per_user: true

Установите значение false только если вы явно хотите один общий разговор для всего канала:

group_sessions_per_user: false

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

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

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

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

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

Войдите в Mattermost как Системный администратор.
Перейдите в Системная консоль → Интеграции → Учётные записи ботов.
Установите Включить создание учётных записей ботов в true.
Нажмите Сохранить.

к сведению

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

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

В Mattermost нажмите меню ☰ (вверху слева) → Интеграции → Учётные записи ботов.
Нажмите Добавить учётную запись бота.
Заполните данные:
- Имя пользователя: например, vibeos
- Отображаемое имя: например, VibeOS
- Описание: необязательно
- Роль: Участник достаточно
Нажмите Создать учётную запись бота.
Mattermost отобразит токен бота. Скопируйте его немедленно.

Токен показывается только один раз

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

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

подсказка

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

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

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

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

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

Шаг 4: Поиск вашего идентификатора пользователя Mattermost

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

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

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

предупреждение

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

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

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

подсказка

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

Шаг 5: Настройка VibeOS

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

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

vibeos gateway setup

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

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

Добавьте следующее в ваш файл ~/.vibeos/.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

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

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

group_sessions_per_user: true

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

Запуск шлюза

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

vibeos gateway

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

подсказка

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

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

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

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

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

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

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

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

Режим ответа

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

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

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

MATTERMOST_REPLY_MODE=thread

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

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

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

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

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

Белый список каналов (`allowed_channels`)

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

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

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

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

MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml"

Поведение:

Пусто / не задано → без ограничений (полная обратная совместимость).
Не пусто → идентификатор канала должен быть в списке, иначе сообщение отбрасывается до выполнения любой другой проверки (требование упоминания, MATTERMOST_FREE_RESPONSE_CHANNELS и т.д.).
Найдите идентификатор канала через интерфейс Mattermost → заголовок канала → «Просмотреть информацию» или прочитайте его из URL канала.

См. также: разделение команд администратора/пользователя.

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

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

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

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

Ошибки 403 Forbidden

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

Решение: Проверьте, что 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:

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

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

Бот офлайн

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

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

«Пользователь не разрешён» / Бот игнорирует вас

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

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

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

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

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

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

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

предупреждение

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

Для получения дополнительной информации о безопасности вашего развёртывания VibeOS см. Руководство по безопасности.

Примечания

Дружелюбно к самостоятельному размещению: Работает с любым самостоятельно размещённым экземпляром Mattermost. Не требуется учётная запись Mattermost Cloud или подписка.
Без дополнительных зависимостей: Адаптер использует aiohttp для HTTP и WebSocket, который уже включён в VibeOS.
Совместимость с Team Edition: Работает как с Mattermost Team Edition (бесплатно), так и с Enterprise Edition.

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

Модель сеанса в Mattermost​

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

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

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

Шаг 4: Поиск вашего идентификатора пользователя Mattermost​

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

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

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

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

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

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

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

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

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

Белый список каналов (allowed_channels)​

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

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

Ошибки 403 Forbidden​

Разрывы WebSocket / циклы переподключения​

«Не удалось аутентифицироваться» при запуске​

Бот офлайн​

«Пользователь не разрешён» / Бот игнорирует вас​

Промпты для каждого канала​

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

Примечания​

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

Модель сеанса в Mattermost

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

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

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

Шаг 4: Поиск вашего идентификатора пользователя Mattermost

Шаг 5: Настройка VibeOS

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

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

Запуск шлюза

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

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

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

Режим ответа

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

Белый список каналов (`allowed_channels`)

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

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

Ошибки 403 Forbidden

Разрывы WebSocket / циклы переподключения

«Не удалось аутентифицироваться» при запуске

Бот офлайн

«Пользователь не разрешён» / Бот игнорирует вас

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

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

Примечания