Введение для начинающих (2 минуты)
OpenClaw «живет» в ваших собственных учетных записях мессенджеров. Отдельного пользователя-бота WhatsApp нет. Если вы состоите в группе, OpenClaw может видеть эту группу и отвечать в ней. Поведение по умолчанию:- Группы ограничены (
groupPolicy: "allowlist"). - Для ответов требуется упоминание, если вы явно не отключите шлюзование по упоминаниям.
- Видимые ответы в группах/каналах по умолчанию используют инструмент
message.
Кратко
- Доступ к личным сообщениям управляется через
*.allowFrom. - Доступ к группам управляется через
*.groupPolicy+ списки разрешенных (*.groups,*.groupAllowFrom). - Запуск ответа управляется шлюзованием по упоминаниям (
requireMention,/activation).
Видимые ответы
Для обычных групповых/канальных запросов OpenClaw по умолчанию используетmessages.groupChat.visibleReplies: "automatic". Итоговый текст ассистента публикуется через устаревший путь видимого ответа, если вы не включите для комнаты вывод только через инструмент сообщений.
Используйте messages.groupChat.visibleReplies: "message_tool", когда в общей комнате агент должен сам решать, когда говорить, вызывая message(action=send). Это лучше всего работает для групповых комнат на базе моделей последнего поколения с надежной работой инструментов, таких как GPT 5.5. Если модель пропустит этот инструмент и вернет содержательный итоговый текст, OpenClaw сохранит этот итоговый текст приватным вместо публикации в комнату.
Используйте "automatic" для более слабых моделей или сред выполнения, которые ненадежно понимают доставку только через инструмент. В автоматическом режиме итоговый текст ассистента является видимым исходным путем ответа, поэтому модель, которая не может стабильно вызывать message(action=send), все равно может отвечать обычным образом.
В автоматическом режиме обычные итоговые текстовые ответы публикуются напрямую в комнату. Если видимому ответу нужны файлы, изображения или другие вложения, агент все еще может использовать message(action=send) для такого вложения вместо попытки протолкнуть его через итоговый текстовый ответ.
Если инструмент сообщений недоступен по активной политике инструментов, OpenClaw откатывается
к автоматическим видимым ответам вместо молчаливого подавления ответа.
openclaw doctor предупреждает об этом несоответствии.
Для прямых чатов и любого другого исходного события используйте messages.visibleReplies: "message_tool", чтобы глобально применить такое же поведение видимых ответов только через инструмент. Прямые ходы внутреннего WebChat по умолчанию используют автоматическую доставку итогового ответа, чтобы Pi и Codex получали один и тот же контракт видимого ответа. Задайте messages.visibleReplies: "message_tool", чтобы намеренно требовать message(action=send) для видимого вывода. messages.groupChat.visibleReplies остается более специфичным переопределением для групповых/канальных комнат.
Это заменяет старый шаблон принуждения модели отвечать NO_REPLY для большинства ходов в режиме наблюдения. В режиме только через инструмент промпт не определяет контракт NO_REPLY. Отсутствие видимых действий просто означает, что инструмент сообщений не вызывается.
Привязки разговоров, принадлежащие Plugin, являются исключением. Когда Plugin привязывает тред и забирает входящий ход, ответ, возвращенный Plugin, является видимым ответом привязки; ему не нужен message(action=send). Этот ответ является выводом среды выполнения Plugin, а не приватным итоговым текстом модели.
Индикаторы набора текста все еще отправляются для прямых групповых запросов. Фоновые постоянно включенные события комнат, если они включены, остаются строгими и тихими, если агент не вызывает инструмент сообщений.
Сеансы по умолчанию подавляют подробные сводки инструментов/прогресса. Используйте /verbose on,
чтобы показывать эти сводки для текущего сеанса при отладке, и
/verbose off, чтобы вернуться к поведению только с итоговыми ответами. То же состояние подробного режима
применяется в прямых чатах, группах, каналах и темах форумов.
Чтобы отправлять неупомянутую болтовню в постоянно включенной группе как тихий контекст комнаты вместо пользовательских запросов, используйте Фоновые события комнат:
unmentionedInbound: "user_request".
Упомянутые сообщения, команды, запросы прерывания и личные сообщения остаются пользовательскими запросами.
Чтобы потребовать прохождения видимого вывода через инструмент сообщений для групповых/канальных запросов:
messages после сохранения файла. Перезапуск нужен только
когда наблюдение за файлами или перезагрузка конфигурации отключены в развертывании.
Чтобы потребовать прохождения видимого вывода через инструмент сообщений для каждого исходного чата:
visibleReplies: "message_tool" и всегда отвечают видимо, чтобы нативный для канала командный UI получил ожидаемый ответ. Это применяется только к проверенным нативным командным ходам; текстовые команды /... и обычные ходы чата по-прежнему следуют настроенному групповому значению по умолчанию.
Видимость контекста и списки разрешенных
В безопасности групп задействованы два разных механизма управления:- Авторизация запуска: кто может запускать агента (
groupPolicy,groups,groupAllowFrom, списки разрешенных, специфичные для канала). - Видимость контекста: какой дополнительный контекст внедряется в модель (текст ответа, цитаты, история треда, пересланные метаданные).
Текущее поведение зависит от канала
Текущее поведение зависит от канала
- Некоторые каналы уже применяют фильтрацию по отправителю для дополнительного контекста в конкретных путях (например, начальное заполнение тредов Slack, поиск ответов/тредов Matrix).
- Другие каналы все еще передают контекст цитат/ответов/пересылок в полученном виде.
Направление усиления защиты (запланировано)
Направление усиления защиты (запланировано)
contextVisibility: "all"(по умолчанию) сохраняет текущее поведение в полученном виде.contextVisibility: "allowlist"фильтрует дополнительный контекст до отправителей из списка разрешенных.contextVisibility: "allowlist_quote"— этоallowlistплюс одно явное исключение для цитаты/ответа.
| Цель | Что задать |
|---|---|
| Разрешить все группы, но отвечать только на @упоминания | groups: { "*": { requireMention: true } } |
| Отключить все ответы в группах | groupPolicy: "disabled" |
| Только конкретные группы | groups: { "<group-id>": { ... } } (без ключа "*") |
| Только вы можете запускать в группах | groupPolicy: "allowlist", groupAllowFrom: ["+1555..."] |
| Повторно использовать один набор доверенных отправителей в каналах | groupAllowFrom: ["accessGroup:operators"] |
Ключи сеансов
- Групповые сеансы используют ключи сеансов
agent:<agentId>:<channel>:group:<id>(комнаты/каналы используютagent:<agentId>:<channel>:channel:<id>). - Темы форумов Telegram добавляют
:topic:<threadId>к идентификатору группы, чтобы у каждой темы был собственный сеанс. - Прямые чаты используют основной сеанс (или отдельный по отправителю, если настроено).
- Heartbeat пропускаются для групповых сеансов.
Шаблон: личные сообщения + публичные группы (один агент)
Да — это хорошо работает, если ваш «личный» трафик — это личные сообщения, а ваш «публичный» трафик — это группы. Почему: в режиме одного агента личные сообщения обычно попадают в основной ключ сеанса (agent:main:main), тогда как группы всегда используют неосновные ключи сеансов (agent:main:<channel>:group:<id>). Если вы включите изоляцию с mode: "non-main", эти групповые сеансы будут работать в настроенном backend изоляции, а ваш основной сеанс личных сообщений останется на хосте. Docker является backend по умолчанию, если вы не выберете другой.
Это дает вам один «мозг» агента (общая рабочая область + память), но две позиции выполнения:
- Личные сообщения: полные инструменты (хост)
- Группы: изоляция + ограниченные инструменты
Если вам нужны действительно отдельные рабочие области/персоны («личное» и «публичное» никогда не должны смешиваться), используйте второго агента + привязки. См. Маршрутизация нескольких агентов.
- Личные сообщения на хосте, группы изолированы
- Группы видят только папку из списка разрешенных
- Ключи конфигурации и значения по умолчанию: Конфигурация Gateway
- Отладка того, почему инструмент заблокирован: Изоляция vs политика инструментов vs повышенные права
- Подробности bind mounts: Изоляция
Отображаемые метки
- Метки UI используют
displayName, когда доступно, в формате<channel>:<token>. #roomзарезервировано для комнат/каналов; групповые чаты используютg-<slug>(нижний регистр, пробелы ->-, сохранять#@+._-).
Политика групп
Управляйте обработкой сообщений групп/комнат для каждого канала:| Политика | Поведение |
|---|---|
"open" | Группы обходят списки разрешений; фильтр упоминаний всё ещё применяется. |
"disabled" | Полностью блокировать все групповые сообщения. |
"allowlist" | Разрешать только группы/комнаты, которые соответствуют настроенному списку разрешений. |
Примечания по каналам
Примечания по каналам
groupPolicyотделена от фильтра упоминаний (который требует @упоминания).- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: используйте
groupAllowFrom(резервный вариант: явныйallowFrom). - Signal:
groupAllowFromможет совпадать либо с входящим идентификатором группы Signal, либо с телефоном/UUID отправителя. - Одобрения привязки DM (записи хранилища
*-allowFrom) применяются только к доступу DM; авторизация отправителя в группе остаётся явно заданной через групповые списки разрешений. - Discord: список разрешений использует
channels.discord.guilds.<id>.channels. - Slack: список разрешений использует
channels.slack.channels. - Matrix: список разрешений использует
channels.matrix.groups. Предпочитайте идентификаторы комнат или псевдонимы; поиск имени присоединённой комнаты выполняется по мере возможности, а неразрешённые имена игнорируются во время выполнения. Используйтеchannels.matrix.groupAllowFrom, чтобы ограничить отправителей; списки разрешенийusersдля отдельных комнат также поддерживаются. - Групповые DM управляются отдельно (
channels.discord.dm.*,channels.slack.dm.*). - Список разрешений Telegram может совпадать с идентификаторами пользователей (
"123456789","telegram:123456789","tg:123456789") или именами пользователей ("@alice"или"alice"); префиксы нечувствительны к регистру. - По умолчанию используется
groupPolicy: "allowlist"; если список разрешённых групп пуст, групповые сообщения блокируются. - Безопасность во время выполнения: когда блок провайдера полностью отсутствует (
channels.<provider>отсутствует), групповая политика откатывается к закрытому при сбое режиму (обычноallowlist) вместо наследованияchannels.defaults.groupPolicy.
Групповые списки разрешений
Групповые списки разрешений (
*.groups, *.groupAllowFrom, список разрешений для конкретного канала).Фильтр упоминаний (по умолчанию)
Групповые сообщения требуют упоминания, если это не переопределено для отдельной группы. Значения по умолчанию находятся для каждой подсистемы в*.groups."*".
Ответ на сообщение бота считается неявным упоминанием, когда канал поддерживает метаданные ответа. Цитирование сообщения бота также может считаться неявным упоминанием в каналах, которые предоставляют метаданные цитаты. Текущие встроенные случаи включают Telegram, WhatsApp, Slack, Discord, Microsoft Teams и ZaloUser.
Область действия настроенных шаблонов упоминаний
НастроенныеmentionPatterns — это резервные триггеры regex. Используйте их, когда
платформа не предоставляет нативное упоминание бота или когда вы хотите, чтобы обычный текст,
например openclaw:, считался упоминанием. Нативные упоминания платформы отделены:
когда Discord, Slack, Telegram, Matrix или другой канал может доказать, что сообщение
явно упомянуло бота, это нативное упоминание всё равно срабатывает, даже если
настроенные regex-шаблоны запрещены.
По умолчанию настроенные шаблоны упоминаний применяются везде, где этот канал передаёт
факты о провайдере и беседе в обнаружение упоминаний. Чтобы широкие шаблоны
не пробуждали агента в каждой группе, ограничьте их область действия по каналу с помощью
channels.<channel>.mentionPatterns.
Используйте mode: "deny", когда regex-шаблоны упоминаний должны быть выключены по умолчанию для
канала, а затем включайте отдельные комнаты через allowIn:
mode: "allow" (или опустите mode), когда regex-шаблоны упоминаний
должны применяться широко, а затем отключайте их в шумных комнатах с помощью denyIn:
| Поле | Эффект |
|---|---|
mode: "allow" | Regex-шаблоны упоминаний включены, если идентификатор беседы не находится в denyIn. Это значение по умолчанию. |
mode: "deny" | Regex-шаблоны упоминаний отключены, если идентификатор беседы не находится в allowIn. |
allowIn | Идентификаторы бесед, где regex-шаблоны упоминаний включены в режиме запрета. |
denyIn | Идентификаторы бесед, где regex-шаблоны упоминаний отключены. denyIn имеет приоритет над allowIn, если оба содержат один и тот же идентификатор. |
| Канал | Идентификаторы, используемые в allowIn / denyIn |
|---|---|
| Discord | Идентификаторы каналов Discord. |
| Matrix | Идентификаторы комнат Matrix. |
| Slack | Идентификаторы каналов Slack. |
| Telegram | Идентификаторы групповых чатов или chatId:topic:threadId для тем форума. |
Идентификаторы бесед WhatsApp, например 123@g.us. |
channels.<channel>.accounts.<accountId>.mentionPatterns, когда этот канал
поддерживает несколько аккаунтов. Политика аккаунта имеет приоритет над политикой канала
верхнего уровня для этого аккаунта.
Примечания к фильтру упоминаний
Примечания к фильтру упоминаний
mentionPatterns— безопасные regex-шаблоны без учёта регистра; недействительные шаблоны и небезопасные формы с вложенными повторениями игнорируются.- Поверхности, которые предоставляют явные упоминания, всё равно проходят; настроенные regex-шаблоны являются резервным вариантом.
channels.<channel>.mentionPatterns.mode: "deny"по умолчанию отключает настроенные шаблоны упоминаний для этого канала; включайте выбранные беседы обратно с помощьюallowIn.channels.<channel>.mentionPatterns.denyInотключает настроенные шаблоны упоминаний для конкретных идентификаторов бесед, при этом нативные @упоминания платформы всё равно проходят.- Переопределение для агента:
agents.list[].groupChat.mentionPatterns(полезно, когда несколько агентов используют одну группу). - Фильтр упоминаний применяется только тогда, когда обнаружение упоминаний возможно (настроены нативные упоминания или
mentionPatterns). - Добавление группы или отправителя в список разрешений не отключает фильтр упоминаний; установите для этой группы
requireMentionвfalse, когда все сообщения должны запускать обработку. - Автоматический контекст подсказки группового чата передаёт разрешённую инструкцию тихого ответа на каждом ходу; файлы рабочей области не должны дублировать механику
NO_REPLY. - Группы, где автоматические тихие ответы разрешены, трактуют чистые пустые ходы модели или ходы только с рассуждениями как тихие, эквивалентные
NO_REPLY. Прямые чаты никогда не получают указанияNO_REPLY, а групповые ответы только через инструмент сообщений остаются тихими, если не вызываютmessage(action=send). - Фоновый всегда включённый групповой обмен сообщениями по умолчанию использует семантику пользовательского запроса. Установите
messages.groupChat.unmentionedInbound: "room_event", чтобы отправлять его как тихий контекст. См. Фоновые события комнаты для примеров настройки. - События комнаты не сохраняются как поддельные пользовательские запросы, а частный текст ассистента из событий комнаты без инструмента сообщений не воспроизводится как история чата.
- Значения по умолчанию Discord находятся в
channels.discord.guilds."*"(переопределяются для отдельной гильдии/канала). - Контекст истории группы оборачивается единообразно во всех каналах. Группы с фильтром упоминаний сохраняют ожидающие пропущенные сообщения; всегда включённые группы также могут сохранять недавние обработанные сообщения комнаты, когда канал это поддерживает. Используйте
messages.groupChat.historyLimitдля глобального значения по умолчанию иchannels.<channel>.historyLimit(илиchannels.<channel>.accounts.*.historyLimit) для переопределений. Установите0, чтобы отключить.
Ограничения инструментов для групп/каналов (необязательно)
Некоторые конфигурации каналов поддерживают ограничение инструментов, доступных внутри конкретной группы/комнаты/канала.tools: разрешить/запретить инструменты для всей группы.toolsBySender: переопределения по отправителю внутри группы. Используйте явные префиксы ключей:channel:<channelId>:<senderId>,id:<senderId>,e164:<phone>,username:<handle>,name:<displayName>и подстановочный знак"*". Идентификаторы каналов используют канонические идентификаторы каналов OpenClaw; псевдонимы, такие какteams, нормализуются вmsteams. Устаревшие ключи без префикса всё ещё принимаются и сопоставляются только какid:.
Пример (Telegram):
Ограничения инструментов для групп/каналов применяются в дополнение к глобальной политике инструментов/политике инструментов агента (запрет всё равно имеет приоритет). Некоторые каналы используют другую вложенность для комнат/каналов (например, Discord
guilds.*.channels.*, Slack channels.*, Microsoft Teams teams.*.channels.*).Групповые списки разрешений
Когда настроеныchannels.whatsapp.groups, channels.telegram.groups или channels.imessage.groups, ключи действуют как групповой список разрешений. Используйте "*", чтобы разрешить все группы, при этом всё ещё задавая поведение упоминаний по умолчанию.
Типовые задачи (скопировать/вставить):
- Отключить все ответы в группах
- Разрешить только определенные группы (WhatsApp)
- Разрешить все группы, но требовать упоминание
- Триггеры только для владельца (WhatsApp)
Активация (только владелец)
Владельцы групп могут переключать активацию для каждой группы:/activation mention/activation always
channels.whatsapp.allowFrom (или по собственному номеру бота в формате E.164, если значение не задано). Отправьте команду отдельным сообщением. Другие интерфейсы сейчас игнорируют /activation.
Поля контекста
Входящие групповые полезные нагрузки задают:ChatType=groupGroupSubject(если известно)GroupMembers(если известно)WasMentioned(результат проверки упоминания)- Темы форумов Telegram также включают
MessageThreadIdиIsForum.
\n. В группах не из Telegram также не рекомендуется использовать таблицы Markdown; рекомендации по форматированному тексту Telegram поступают из подсказки канала Telegram. Имена групп и метки участников, полученные из каналов, отображаются как огражденные недоверенные метаданные, а не как встроенные системные инструкции.
Особенности iMessage
- Предпочитайте
chat_id:<id>при маршрутизации или добавлении в разрешающий список. - Список чатов:
imsg chats --limit 20. - Ответы в группе всегда возвращаются в тот же
chat_id.