Перейти к основному содержимому

Настройка Matrix

VibeOS интегрируется с Matrix — открытым, федеративным протоколом обмена сообщениями. Matrix позволяет вам запустить собственный homeserver или использовать публичный, например matrix.org — в любом случае вы сохраняете контроль над своей коммуникацией. Бот подключается через Python SDK mautrix, обрабатывает сообщения через конвейер VibeOS (включая использование инструментов, память и рассуждения) и отвечает в реальном времени. Он поддерживает текст, вложения файлов, изображения, аудио, видео и опциональное сквозное шифрование (E2EE).

VibeOS работает с любым Matrix homeserver — Synapse, Conduit, Dendrite или matrix.org.

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

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

КонтекстПоведение
ЛСVibeOS отвечает на каждое сообщение. @упоминание не требуется. Каждый личный диалог имеет свою сессию. Установите MATRIX_DM_MENTION_THREADS=true, чтобы начинать тред при @упоминании бота в ЛС.
КомнатыПо умолчанию VibeOS требует @упоминание для ответа. Установите MATRIX_REQUIRE_MENTION=false или добавьте ID комнат в MATRIX_FREE_RESPONSE_ROOMS для комнат со свободным ответом. Приглашения в комнаты принимаются автоматически.
ТредыVibeOS поддерживает треды Matrix (MSC3440). Если вы отвечаете в треде, VibeOS изолирует контекст треда от основной временной шкалы комнаты. Треды, в которых бот уже участвовал, не требуют упоминания.
Авто-тредыПо умолчанию VibeOS автоматически создаёт тред для каждого сообщения, на которое отвечает в комнате. Это изолирует беседы. Установите MATRIX_AUTO_THREAD=false, чтобы отключить. Установите MATRIX_DM_AUTO_THREAD=true (по умолчанию false), чтобы также автоматически создавать треды для сообщений в ЛС — это отличается от MATRIX_DM_MENTION_THREADS, который запускает тред только при @упоминании бота в ЛС.
КомандыVibeOS принимает обычные /команды, когда ваш Matrix-клиент их отправляет. Если ваш клиент резервирует / для локальных команд, используйте !команды; VibeOS нормализует известные псевдонимы !команда в /команда.
Интерактивные элементы управленияОдобрение опасных команд и выбор /model могут использовать реакции Matrix. Реакции одобрения могут быть ограничены пользователем, запросившим действие.
Мыслительная деятельность и активность инструментовMatrix использует редактируемые панели мыслей/активности инструментов в тредах, когда включён прогресс шлюза, поэтому обновления не засоряют основную временную шкалу комнаты.
Общие комнаты с несколькими пользователямиПо умолчанию VibeOS изолирует историю сессии для каждого пользователя внутри комнаты. Два человека, разговаривающие в одной комнате, не делят одну стенограмму, если вы явно это не отключите.
подсказка

Бот автоматически присоединяется к комнатам, когда его приглашают. Просто пригласите Matrix-пользователя бота в любую комнату, и он присоединится и начнёт отвечать.

Матрица возможностей​

Эта таблица основана на объявлении возможностей адаптера Matrix и тестовом покрытии Matrix. E2EE зависит от режима, потому что развёртывания выбирают, отключены ли зашифрованные комнаты, используются опционально или обязательны.

ВозможностьMatrix
текстда
тредыда
реакциида
одобренияда
выбор моделида
панели мыслейда
изображенияда
несколько изображенийда
файлыда
голос/аудиода
видеода
E2EEвыкл / опционально / обязательно
диагностикада

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

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

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

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

group_sessions_per_user: true

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

group_sessions_per_user: false

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

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

Конфигурация упоминаний и тредов​

Вы можете настроить поведение упоминаний и авто-тредов через переменные окружения или config.yaml:

matrix:
  require_mention: true           # Требовать @упоминание в комнатах (по умолчанию: true)
  allowed_users:                  # Пользователи Matrix, которым разрешено запускать действия агента
    - "@alice:matrix.org"
  allowed_rooms:                  # Комнаты Matrix, в которых разрешено запускать действия агента
    - "!abc123:matrix.org"
  free_response_rooms:            # Комнаты, освобождённые от требования упоминания
    - "!abc123:matrix.org"
  ignore_user_patterns:           # Игнорировать мостовых/призрачных пользователей
    - "^@telegram_"
    - "^@whatsapp_"
  process_notices: false          # Игнорировать m.notice по умолчанию
  session_scope: room             # auto|room|thread; room рекомендуется для проектных комнат
  auto_thread: true               # Автоматически создавать треды для ответов (по умолчанию: true)
  dm_mention_threads: false       # Создавать тред при @упоминании в ЛС (по умолчанию: false)

Или через переменные окружения:

MATRIX_REQUIRE_MENTION=true
MATRIX_ALLOWED_USERS=@alice:matrix.org
MATRIX_ALLOWED_ROOMS=!abc123:matrix.org
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@whatsapp_'
MATRIX_PROCESS_NOTICES=false
MATRIX_SESSION_SCOPE=room       # рекомендуется для стабильного контекста проектной комнаты
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
MATRIX_REACTIONS=true          # по умолчанию: true — эмодзи-реакции во время обработки
MATRIX_ALLOW_ROOM_MENTIONS=false
Отключение реакций

MATRIX_REACTIONS=false отключает эмодзи-реакции жизненного цикла обработки (👀/✅/❌), которые бот публикует на входящие сообщения. Полезно для комнат, где события реакций создают шум или не поддерживаются всеми участвующими клиентами.

Упоминания всей комнаты

VibeOS отправляет структурированные упоминания пользователей Matrix для явных Matrix ID, таких как @alice:example.org. Уведомления для всей комнаты @room отключены по умолчанию; устанавливайте MATRIX_ALLOW_ROOM_MENTIONS=true только в комнатах, где боту разрешено уведомлять всех.

примечание

Если вы обновляетесь с версии, в которой не было MATRIX_REQUIRE_MENTION, бот ранее отвечал на все сообщения в комнатах. Чтобы сохранить такое поведение, установите MATRIX_REQUIRE_MENTION=false.

Изоляция проектной комнаты​

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

MATRIX_SESSION_SCOPE=room
MATRIX_AUTO_THREAD=false

MATRIX_SESSION_SCOPE принимает:

ОбластьПоведение
autoОбратно совместимое значение по умолчанию. Существующее поведение MATRIX_AUTO_THREAD управляет синтетическими тредами.
roomСообщения комнаты без тредов остаются в одной стабильной сессии комнаты. Реальные треды Matrix по-прежнему используют свой корень треда.
threadСообщения комнаты без тредов синтезируют тред/сессию из ID события-триггера.

VibeOS теперь включает текущее имя комнаты Matrix, ID комнаты, тему, ID сообщения и заметку о границе комнаты Matrix в подсказке агента. /status также показывает текущую область видимости комнаты/сессии Matrix, а /resume не будет молча возобновлять именованную сессию из другой комнаты Matrix, если вы явно не используете /resume --cross-room <имя сессии>.

MATRIX_SESSION_SCOPE=room управляет дорожкой комнаты/треда. Существующая настройка group_sessions_per_user по-прежнему контролирует, делят ли пользователи внутри этой комнаты дорожку. С group_sessions_per_user: true (по умолчанию) Алиса и Боб получают отдельные сессии Проекта Б. С group_sessions_per_user: false комната имеет одну общую стенограмму Проекта Б.

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

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

Вам нужна учётная запись пользователя Matrix для бота. Есть несколько способов сделать это:

Вариант A: Зарегистрируйтесь на своём Homeserver (рекомендуется)​

Если вы запускаете свой собственный homeserver (Synapse, Conduit, Dendrite):

  1. Используйте API администратора или инструмент регистрации для создания нового пользователя:
# Пример для Synapse
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
  1. Выберите имя пользователя, например vibeos — полный ID пользователя будет @vibeos:your-server.org.

Вариант B: Используйте matrix.org или другой публичный Homeserver​

  1. Перейдите на Element Web и создайте новую учётную запись.
  2. Выберите имя пользователя для вашего бота (например, vibeos-bot).

Вариант C: Используйте свою собственную учётную запись​

Вы также можете запустить VibeOS от имени своего собственного пользователя. Это означает, что бот будет публиковать сообщения от вашего имени — полезно для персональных ассистентов.

Шаг 2: Получите токен доступа​

VibeOS нужен токен доступа для аутентификации на homeserver. У вас есть два варианта:

Вариант A: Токен доступа (рекомендуется)​

Самый надёжный способ получить токен:

Через Element:

  1. Войдите в Element под учётной записью бота.
  2. Перейдите в Настройки → Помощь и о программе.
  3. Прокрутите вниз и разверните Дополнительно — там отображается токен доступа.
  4. Скопируйте его немедленно.

Через API:

curl -X POST https://your-server/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@vibeos:your-server.org",
    "password": "your-password"
  }'

Ответ содержит поле access_token — скопируйте его.

Храните токен доступа в безопасности

Токен доступа предоставляет полный доступ к Matrix-учётной записи бота. Никогда не делитесь им публично и не сохраняйте в Git. В случае компрометации отзовите его, выйдя из всех сессий для этого пользователя.

Вариант B: Вход по паролю​

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

MATRIX_USER_ID=@vibeos:your-server.org
MATRIX_PASSWORD=your-password

Шаг 3: Найдите свой Matrix User ID​

VibeOS использует ваш Matrix User ID для контроля того, кто может взаимодействовать с ботом. Matrix User ID имеют формат @username:server.

Чтобы найти свой:

  1. Откройте Element (или ваш предпочитаемый Matrix-клиент).
  2. Нажмите на свой аватар → Настройки.
  3. Ваш User ID отображается в верхней части профиля (например, @alice:matrix.org).
подсказка

Matrix User ID всегда начинаются с @ и содержат :, за которым следует имя сервера. Например: @alice:matrix.org, @bob:your-server.com.

Шаг 4: Настройте VibeOS​

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

Запустите команду guided setup:

vibeos gateway setup

Выберите Matrix при запросе, затем укажите URL вашего homeserver, токен доступа (или ID пользователя + пароль) и разрешённые ID пользователей.

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

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

С использованием токена доступа:

# Обязательно
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Опционально: ID пользователя (автоопределяется из токена, если опущен)
# MATRIX_USER_ID=@vibeos:matrix.example.org

# Безопасность: ограничьте, кто может взаимодействовать с ботом
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Опционально: ограничьте, какие комнаты могут запускать бота
MATRIX_ALLOWED_ROOMS=!abc123:matrix.example.org

# Несколько разрешённых пользователей (через запятую)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

С использованием входа по паролю:

# Обязательно
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@vibeos:matrix.example.org
MATRIX_PASSWORD=***

# Безопасность
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

Усиление защиты частного развёртывания​

Для частных развёртываний Matrix установите оба белых списка: пользователей и комнат. Если MATRIX_ALLOWED_USERS не задан, любой отправитель, который может связаться с ботом в комнате, где он состоит, может запустить действие агента. Если MATRIX_ALLOWED_ROOMS не задан, любая комната, в которую вступил бот, может запустить действие агента. Защищённое развёртывание должно установить оба:

MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org
MATRIX_ALLOWED_ROOMS=!ops:matrix.example.org,!dmroom:matrix.example.org

Развёртывания с мостами и приложениями-сервисами нуждаются в дополнительной защите от циклов. VibeOS всегда игнорирует свои собственные события, пользователей Matrix в стиле appservice, чья локальная часть начинается с _, дубликаты ID событий, старые события запуска, события замены редактирования и события m.notice по умолчанию. Добавьте специфичные для развёртывания шаблоны мостовых призраков, когда ваш мост использует другое соглашение об именах:

MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@slack_,^@whatsapp_'

Включайте уведомления только тогда, когда доверенный человеческий рабочий процесс действительно отправляет m.notice:

MATRIX_PROCESS_NOTICES=true

Исходящие уведомления для всей комнаты отключены по умолчанию. Оставляйте MATRIX_ALLOW_ROOM_MENTIONS=false, если боту явно не разрешено будить всю комнату с помощью @room.

Диагностика и отладочные полезные нагрузки скрывают токены доступа Matrix, ключи восстановления, идентификаторы устройств и тела сообщений. Загрузка медиа ограничена URI контента Matrix mxc:// и отклоняется, когда они превышают MATRIX_MAX_MEDIA_BYTES. Относитесь к федеративным комнатам и ненадёжным homeserver как к ненадёжному вводу: держите белые списки комнат строгими, предпочитайте ЛС или частные комнаты для задач с интенсивным использованием инструментов и избегайте авторизации мостовых призраков или марионеток appservice в качестве разрешённых пользователей.

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

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

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

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

vibeos gateway

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

подсказка

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

Сквозное шифрование (E2EE)​

VibeOS поддерживает сквозное шифрование Matrix, поэтому вы можете общаться с ботом в зашифрованных комнатах.

Требования​

E2EE требует библиотеку mautrix с расширениями для шифрования и библиотеку C libolm:

# Установка mautrix с поддержкой E2EE
pip install 'mautrix[encryption]'

# Или установка с расширениями vibeos
cd ~/.vibeos/vibeos-agent && uv pip install -e ".[matrix]"

Вам также понадобится libolm, установленная в вашей системе:

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

Включение E2EE​

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

MATRIX_E2EE_MODE=required

MATRIX_E2EE_MODE принимает:

РежимПоведение
offНе инициализировать Matrix E2EE.
optionalПытаться использовать E2EE, когда зависимости доступны, но оставить незашифрованные комнаты работающими, если криптография не может быть инициализирована.
requiredЗавершиться с ошибкой, если зависимости E2EE или настройка криптографии недоступны.

Опциональный режим может вернуться к работе без E2EE, когда настройка криптографии недоступна. Обязательный режим завершается с ошибкой вместо молчаливого понижения.

Для обратной совместимости MATRIX_ENCRYPTION=true по-прежнему включает обязательное поведение E2EE.

Когда E2EE включено, VibeOS:

  • Хранит ключи шифрования в ~/.vibeos/platforms/matrix/store/ (для устаревших установок: ~/.vibeos/matrix/store/)
  • Загружает ключи устройства при первом подключении
  • Автоматически расшифровывает входящие сообщения и шифрует исходящие
  • Автоматически присоединяется к зашифрованным комнатам при приглашении

Инструменты и элементы управления Matrix​

В беседах Matrix VibeOS предоставляет агенту инструменты, специфичные для Matrix:

  • matrix_send_reaction
  • matrix_redact_message
  • matrix_create_room
  • matrix_invite_user
  • matrix_fetch_history
  • matrix_set_presence

Эти инструменты ограничены контекстом Matrix и недоступны в наборах инструментов, не связанных с Matrix. Инструменты административного типа отключены по умолчанию: редактирование требует MATRIX_TOOLS_ALLOW_REDACTION=true, приглашения требуют MATRIX_TOOLS_ALLOW_INVITES=true, а создание комнат требует MATRIX_TOOLS_ALLOW_ROOM_CREATE=true. Создание публичных комнат также требует MATRIX_ALLOW_PUBLIC_ROOMS=true. Инструменты Matrix по умолчанию ограничены текущей комнатой Matrix. Явные цели за пределами комнаты требуют MATRIX_TOOLS_ALLOW_CROSS_ROOM=true; действия по редактированию и приглашению за пределами комнаты дополнительно требуют MATRIX_TOOLS_ALLOW_CROSS_ROOM_DESTRUCTIVE=true. Если установлен MATRIX_ALLOWED_ROOMS, инструменты Matrix могут нацеливаться только на эти комнаты.

Элементы управления реакциями используют:

  • ✅ одобрить один раз
  • ♾️ одобрять всегда
  • ❌ отклонить
  • числовые реакции для выбора /model

Установите MATRIX_APPROVAL_REQUIRE_SENDER=false, если вы намеренно хотите, чтобы любой авторизованный пользователь Matrix в комнате мог управлять запросом на одобрение/выбор модели. По умолчанию привязка к запросившему, когда VibeOS знает, кто запросил действие.

Лимиты медиа​

VibeOS загружает и скачивает изображения, файлы, аудио и видео Matrix через API медиа Matrix. Несколько сгенерированных изображений отправляются как один упорядоченный логический пакет, сохраняя подписи и контекст треда во всём пакете.

По умолчанию медиа Matrix размером более 100 МБ отклоняется перед загрузкой/скачиванием. Переопределите с помощью:

MATRIX_MAX_MEDIA_BYTES=104857600

Входящие медиа должны использовать URI контента Matrix mxc://. VibeOS отклоняет произвольные URL медиа HTTP(S) в событиях Matrix, чтобы избежать превращения федеративной комнаты в неограниченный загрузчик.

Интеграционные тесты Synapse​

VibeOS включает опциональную среду Synapse для локальной проверки:

docker compose -f tests/e2e/matrix_synapse_gateway/docker-compose.yml up -d
VIBEOS_MATRIX_SYNAPSE_INTEGRATION=1 \
  scripts/run_tests.sh -m "integration and matrix_synapse" \
  tests/e2e/matrix_synapse_gateway/test_gateway.py
docker compose -f tests/e2e/matrix_synapse_gateway/docker-compose.yml down -v

Среда создаёт временных пользователей через регистрацию с общим секретом Synapse и охватывает отправку/получение в частной комнате, приглашение/вступление в именованную комнату, загрузку/скачивание медиа, доставку ответов бота и фильтрацию старых событий при запуске. Дымовое тестирование E2EE отдельно помечено как matrix_e2ee, чтобы оно оставалось опциональным на машинах разработчиков.

Проверка кросс-подписи (рекомендуется)​

Если ваша учётная запись Matrix включает кросс-подпись (по умолчанию в Element), установите ключ восстановления, чтобы бот мог самостоятельно подписывать своё устройство при запуске. Без этого другие Matrix-клиенты могут отказаться делиться сессиями шифрования с ботом после ротации ключей устройства.

MATRIX_RECOVERY_KEY=EsT... ваш ключ восстановления здесь

Где его найти: В Element перейдите в Настройки → Безопасность и конфиденциальность → Шифрование → ваш ключ восстановления (также называется «Ключ безопасности»). Это ключ, который вас попросили сохранить при первой настройке кросс-подписи.

При каждом запуске, если установлен MATRIX_RECOVERY_KEY, VibeOS импортирует ключи кросс-подписи из защищённого хранилища секретов homeserver и подписывает текущее устройство. Это идемпотентно и безопасно оставлять включённым постоянно.

Если VibeOS создаёт новый ключ восстановления Matrix, он никогда не записывает сырой ключ в журнал. Установите MATRIX_RECOVERY_KEY_OUTPUT_FILE=/secure/path/matrix-recovery-key.txt перед запуском, чтобы записать сгенерированный ключ один раз с правами доступа к файлу 0600; файл не перезаписывается, если он уже существует.

Удаление хранилища криптографии

Если вы удалите ~/.vibeos/platforms/matrix/store/crypto.db, бот потеряет свою криптографическую идентичность. Простой перезапуск с тем же ID устройства не приведёт к полному восстановлению — homeserver по-прежнему хранит одноразовые ключи, подписанные старым ключом идентичности, и пиры не могут установить новые сессии Olm.

VibeOS обнаруживает это состояние при запуске и отказывается включать E2EE, записывая в журнал: device XXXX has stale one-time keys on the server signed with a previous identity key.

Самый простой способ восстановления: сгенерируйте новый токен доступа (который получит новый ID устройства без истории устаревших ключей). См. раздел «Обновление с предыдущей версии с E2EE» ниже. Это самый надёжный путь и позволяет избежать вмешательства в базу данных homeserver.

Ручное восстановление (продвинутый уровень — сохраняет тот же ID устройства):

  1. Остановите Synapse и удалите старое устройство из его базы данных:

    sudo systemctl stop matrix-synapse
    sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "
      DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@vibeos:your-server';
      DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@vibeos:your-server';
      DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@vibeos:your-server';
      DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@vibeos:your-server';
    "
    sudo systemctl start matrix-synapse

    Или через API администратора Synapse (обратите внимание на URL-кодированный ID пользователя):

    curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
      'https://your-server/_synapse/admin/v2/users/%40vibeos%3Ayour-server/devices/DEVICE_ID'

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

  2. Удалите локальное хранилище криптографии и перезапустите VibeOS:

    rm -f ~/.vibeos/platforms/matrix/store/crypto.db*
    # перезапустите vibeos

Другие Matrix-клиенты (Element, matrix-commander) могут кэшировать старые ключи устройства. После восстановления введите /discardsession в Element, чтобы принудительно создать новую сессию шифрования с ботом.

к сведению

Если mautrix[encryption] не установлен или libolm отсутствует, бот автоматически переключается на обычный (незашифрованный) клиент. Вы увидите предупреждение в журналах.

Домашняя комната​

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

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

Введите /sethome в любой комнате Matrix, где присутствует бот. Эта комната станет домашней. Если ваш Matrix-клиент перехватывает слеш-команды, введите !sethome.

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

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

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

Белый список комнат (allowed_rooms)​

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

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

matrix:
  allowed_rooms:
    - "!abc123def456:matrix.example.org"
    - "!opsroom789:matrix.example.org"

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

MATRIX_ALLOWED_ROOMS="!abc123def456:matrix.example.org,!opsroom789:matrix.example.org"

Поведение:

  • Пусто / не задано → без ограничений (по умолчанию).
  • Не пусто → ID комнаты должен быть в списке. Проверка выполняется до любой другой проверки (требование упоминания, белый список отправителей и т.д.).
  • Используйте внутренний ID комнаты (!abc...:server), а не её псевдоним (#room:server). Вы можете найти внутренний ID комнаты в Element через Комната → Настройки → Дополнительно.

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

подсказка

Чтобы найти ID комнаты: в Element перейдите в комнату → Настройки → Дополнительно → Внутренний ID комнаты отображается там (начинается с !).

Команды в Matrix​

VibeOS поддерживает те же команды шлюза в Matrix, что и на других платформах обмена сообщениями, включая /commands, /model, /stop, /queue, /steer, /goal, /subgoal, /background, /bg, /btw, /tasks и /yolo.

Некоторые Matrix-клиенты резервируют ведущий / для локальных клиентских команд и могут не отправлять неизвестные слеш-команды в комнату. В этом случае используйте ! как безопасный для Matrix псевдоним:

!commands
!model
!model gpt-5.5 --provider openrouter
!queue continue with the next task
!stop

VibeOS нормализует !команда только тогда, когда команда известна шлюзу, зарегистрированная команда плагина или установленная команда навыка. Обычные восклицания, такие как !important, остаются обычными сообщениями чата.

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

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

Причина: Бот не присоединился к комнате, MATRIX_ALLOWED_USERS не включает ваш User ID, MATRIX_ALLOWED_ROOMS не включает комнату или сообщение в комнате не содержало упоминания бота.

Решение: Пригласите бота в комнату — он автоматически присоединяется по приглашению. Убедитесь, что ваш User ID есть в MATRIX_ALLOWED_USERS (используйте полный формат @user:server) и ID комнаты есть в MATRIX_ALLOWED_ROOMS, если этот белый список настроен. В комнатах упомяните бота или добавьте комнату в MATRIX_FREE_RESPONSE_ROOMS. Перезапустите шлю