Правила триггеров и безопасность

На этой странице подробно описаны конфигурация правил триггеров и механизм конвейера безопасности системы Channel. Правила триггеров определяют когда Agent отвечает; конвейер безопасности определяет может ли сообщение вообще достичь Agent.

Правила триггеров

Правила триггеров настраиваются через ChannelTriggerConfig. Каждый экземпляр Channel может настроить их независимо.

:::info Личные сообщения всегда активируют триггер Независимо от того, как настроены правила триггеров, личные сообщения (DM) всегда активируют ответ Agent. Правила триггеров влияют только на сообщения в групповых чатах. :::

Режим all — отвечать на все сообщения

Agent генерирует ответ на каждое сообщение в группе.

{
  "mode": "all"
}

Лучше всего подходит для:

Персональных ботов
Тестовых сред
Небольших групп с малым числом участников

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

Режим mention — отвечать при упоминании @

Agent отвечает только тогда, когда его упоминают через @. Сообщения без совпадения кэшируются как контекст (до 50 сообщений) и отправляются Agent вместе с активирующим сообщением, чтобы он понимал фон разговора в группе.

{
  "mode": "mention",
  "mentionName": "Clawia"
}

Лучше всего подходит для:

Общих серверов Discord/Slack
Многопользовательских рабочих групп
Когда вы не хотите, чтобы бот отвечал слишком часто

Поле mentionName: Установите имя пользователя бота на платформе. Система проверяет, содержит ли сообщение @Clawia (с учётом регистра), чтобы определить, активируется ли триггер.

Режим keyword — совпадение по ключевому слову

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

{
  "mode": "keyword",
  "keywords": ["help", "assist", "Clawia"]
}

Лучше всего подходит для:

Сценариев службы поддержки, где пользователи вводят «help» для активации бота
Каналов, посвящённых определённой теме

Правило сопоставления: Триггер срабатывает, если сообщение содержит хотя бы одно из ключевых слов. Например, сообщение Please help me look into this совпадает с ключевым словом help.

Режим dm_only — только личные сообщения

Agent отвечает только на личные сообщения и полностью игнорирует групповые сообщения (без кэширования, без ответа).

{
  "mode": "dm_only"
}

Лучше всего подходит для:

Развёртывания бота на публичном сервере с приёмом только личных разговоров
Сценариев, чувствительных к конфиденциальности

Общие параметры

Следующие параметры можно сочетать с любым режимом триггера:

ignoreBot — игнорировать собственные сообщения бота

{
  "mode": "all",
  "ignoreBot": true
}

При значении true сообщения, отправленные самим ботом, не активируют ответ, что предотвращает петли самоответов.

allowFrom — список разрешённых отправителей

{
  "mode": "all",
  "allowFrom": ["123456789", "987654321"]
}

Ограничивает ответы Agent только пользователями из списка разрешённых. allowFrom содержит идентификаторы пользователей платформы (например, Discord user ID).

Пустой массив или ["*"] означает, что разрешены все пользователи
Сопоставление ID нечувствительно к регистру
Эта проверка имеет приоритет над режимом триггера: пользователи не из списка разрешённых не активируют ответ, даже если упомянут бота через @

Механизм кэширования сообщений

В режимах mention и keyword несовпадающие сообщения не отбрасываются — они кэшируются в скользящем окне:

Каждая пара «экземпляр Channel + сеанс чата» поддерживает независимый буфер сообщений
Буфер хранит не более 50 последних сообщений (FIFO)
Когда условие триггера выполнено, все сообщения из буфера отправляются Agent вместе с активирующим сообщением
Групповые сообщения оборачиваются в XML-формат, включающий отправителя, временную метку и другой контекст

Это позволяет Agent понимать фон группового разговора при упоминании, а не видеть лишь одно сообщение.

Конвейер безопасности

Каждое сообщение с внешней платформы проходит последовательно через 5 уровней безопасности прежде, чем достигнет Agent. Если какой-либо уровень перехватывает сообщение, последующие уровни не выполняются.

Сообщение поступает
  │
  ├── [1] RateLimiter ─── Превышена частота? → Тихо отбросить
  │
  ├── [2] InputSanitizer ─── Содержит управляющие символы? → Удалить и продолжить
  │
  ├── [3] PromptGuardian ─── Обнаружена атака инъекцией? → Заблокировать + ответить отклоняющим сообщением
  │
  ├── [4] UserPermissionService ─── Роль пользователя запрещена? → Заблокировать
  │
  ├── [5] ChannelPermissionGate ─── Это ответ на запрос подтверждения? → Потребить сообщение
  │
  └── Сопоставление с правилом триггера → Направить к Agent

Уровень 1: RateLimiter — ограничение частоты

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

Конфигурация	По умолчанию	Описание
`enabled`	`false`	Включить ли ограничение частоты
`maxPerMinute`	`20`	Максимум сообщений от одного пользователя в минуту
`maxPerHour`	`200`	Максимум сообщений от одного пользователя в час
`globalMaxPerMinute`	`60`	Максимум сообщений от всех пользователей вместе в минуту

Поведение: Сообщения, превысившие лимит, тихо отбрасываются (без ответа, без уведомления отправителя).

Ключ ограничения частоты: Отслеживается по channelId + senderId; сообщения от одного пользователя в одном экземпляре Channel используют общую квоту.

подсказка

Ограничение частоты по умолчанию отключено. Рекомендуется включать его для ботов, работающих с публичной аудиторией, чтобы предотвратить злонамеренный спам, увеличивающий расходы на API.

Уровень 2: InputSanitizer — очистка входных данных

Удаляет невидимые управляющие символы Unicode из сообщений, предотвращая атаки на основе кодировки и обфускации.

Конфигурация	По умолчанию	Описание
`enabled`	`true`	Включить ли очистку входных данных
`stripControlChars`	`true`	Удалять ли управляющие символы

Типы удаляемых символов:

Нулевые байты (\x00)
Пробелы нулевой ширины (-‏)
Управляющие символы двунаправленного текста Unicode ( -‮)
Маркер BOM ()
Другие управляющие символы C0/C1 (обычные пробельные символы, такие как переводы строк и табуляции, сохраняются)

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

Уровень 3: PromptGuardian — обнаружение инъекций в промпт

Использует AI (LLM) для проверки безопасности сообщений на семантическом уровне, обнаруживая инъекции в промпт, джейлбрейки и состязательные манипуляции.

Конфигурация	Варианты	Описание
`mode`	`off` / `monitor` / `block`	Режим работы

Описание режимов:

Режим	Поведение
`off`	Полностью отключён, нулевые накладные расходы (по умолчанию)
`monitor`	Обнаруживает и записывает в журнал, но не блокирует сообщения. Используйте для оценки частоты ложных срабатываний
`block`	Блокирует сообщение при обнаружении инъекции и отвечает отправителю юмористическим отклоняющим сообщением

Принципы проектирования:

Fail-open (отказ с разрешением): если LLM-проверка превышает таймаут (10 секунд) или завершается ошибкой, сообщение автоматически пропускается, чтобы сбой уровня безопасности не блокировал нормальное общение
Короткие сообщения (менее 10 символов) пропускают проверку
Результаты проверки безопасных сообщений кэшируются (ключ — хэш SHA-256), чтобы избежать повторных проверок

Уровень 4: UserPermissionService — права пользователей

Система управления доступом на основе ролей. Внешние пользователи, отправляющие первое сообщение, автоматически регистрируются с ролью guest.

Иерархия ролей

Роли от высшей к низшей:

Роль	Чат	Выполнение инструментов	Требует подтверждения	Управление пользователями	Управление настройками
owner	Разрешено	Разрешено	Нет	Разрешено	Разрешено
admin	Разрешено	Разрешено	Нет	Разрешено	Нет
trusted	Разрешено	Разрешено	Нет	Нет	Нет
member	Разрешено	Разрешено	Да	Нет	Нет
guest	Разрешено	Нет	—	Нет	Нет
blocked	Нет	Нет	—	Нет	Нет

Описание полей:

Чат: разрешено ли сообщению достигать Agent (canChat)
Выполнение инструментов: может ли пользователь активировать вызовы инструментов, таких как чтение/запись файлов и команды оболочки (canUseTool)
Требует подтверждения: должен ли отправитель подтвердить в Channel выполнение чувствительных инструментов (оболочка, запись файлов) перед их запуском (requireConfirmation)
Управление пользователями: может ли пользователь управлять пользователями с более низкими ролями (canManageUsers)
Управление настройками: может ли пользователь изменять настройки Agent и безопасности (canManageSettings)

Поведение по умолчанию:

Новые пользователи автоматически регистрируются как guest; они могут общаться в чате, но не могут активировать инструменты
Сообщения от пользователей с ролью blocked тихо отбрасываются, а пользователь получает уведомление о блокировке
Администраторы могут изменять роли пользователей через интерфейс Elftia

Уровень 5: ChannelPermissionGate — подтверждение операций

Когда пользователь с ролью member активирует чувствительный инструмент (команды оболочки, запись файлов и т.д.), система не выполняет его напрямую — вместо этого она отправляет запрос подтверждения в Channel:

⚠️ Permission Required

Clawia wants to execute: **Shell Command**
> npm test

Reply: **y** (approve) / **n** (deny) / **always** (always allow this tool)
⏱ Auto-denied in 5 minutes. [confirm-xxx]

Варианты ответа на подтверждение:

Ответ	Эффект
`y` / `yes` / `ok` / `confirm`	Одобрить это выполнение
`n` / `no` / `cancel` / `deny`	Отклонить это выполнение
`always` / `always allow`	Одобрить и запомнить эту комбинацию инструмент + аргумент; автоматически одобрять последующие вызовы

Ключевые детали:

Запросы подтверждения автоматически отклоняются по истечении 5 минут без ответа
Максимум 5 ожидающих подтверждений на один Channel + сеанс чата
Область действия always точна до комбинации инструмент + аргумент (например, «всегда разрешать Bash: npm test» не даёт автоматического одобрения «Bash: rm -rf /»)
Роли owner, admin и trusted никогда не требуют подтверждения; инструменты выполняются напрямую
Роль guest не может активировать инструменты вовсе и никогда не достигает шага подтверждения

Правила триггеров и безопасность