Конфигурация

Группы

OpenClaw обрабатывает групповые чаты единообразно на всех платформах: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Введение для начинающих (2 минуты)

OpenClaw «живет» на ваших собственных аккаунтах обмена сообщениями. Отдельного пользователя-бота WhatsApp не существует. Если вы находитесь в группе, OpenClaw может видеть эту группу и отвечать в ней. Поведение по умолчанию:

Группы ограничены (groupPolicy: "allowlist").
Ответы требуют упоминания, если вы явно не отключили это правило.

Перевод: отправители из разрешительного списка могут активировать OpenClaw, упомянув его.

TL;DR

Доступ в личных сообщениях контролируется *.allowFrom.

Доступ в группах контролируется *.groupPolicy + разрешительные списки (*.groups, *.groupAllowFrom).

Активация ответа контролируется правилом упоминаний (requireMention, /activation).

Быстрая схема (что происходит с групповым сообщением):

groupPolicy? disabled -> отбросить
groupPolicy? allowlist -> группа разрешена? нет -> отбросить
requireMention? да -> упомянут? нет -> сохранить только для контекста
иначе -> ответить

Поток групповых сообщений Если вы хотите…

Цель	Что установить
Разрешить все группы, но отвечать только на @упоминания	`groups: { "*": { requireMention: true } }`
Отключить все ответы в группах	`groupPolicy: "disabled"`
Только определенные группы	`groups: { "<group-id>": { ... } }` (без ключа `"*"`)
Только вы можете активировать в группах	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Ключи сессий

Групповые сессии используют ключи agent:<agentId>:<channel>:group:<id> (комнаты/каналы используют agent:<agentId>:<channel>:channel:<id>).
Темы форума Telegram добавляют :topic:<threadId> к идентификатору группы, так что каждая тема имеет свою собственную сессию.
Личные чаты используют основную сессию (или сессию на отправителя, если настроено).
Heartbeats пропускаются для групповых сессий.

Паттерн: личные ЛС + публичные группы (один агент)

Да — это хорошо работает, если ваш «личный» трафик — это ЛС, а «публичный» трафик — группы. Почему: в режиме одного агента ЛС обычно попадают в основной ключ сессии (agent:main:main), в то время как группы всегда используют неосновные ключи сессии (agent:main:<channel>:group:<id>). Если вы включите песочницу с mode: "non-main", эти групповые сессии будут выполняться в Docker, в то время как ваша основная сессия ЛС остается на хосте. Это дает вам один «мозг» агента (общее рабочее пространство + память), но две модели выполнения:

ЛС: полный набор инструментов (хост)
Группы: песочница + ограниченные инструменты (Docker)

Если вам нужны полностью отдельные рабочие пространства/персонажи («личное» и «публичное» никогда не должны смешиваться), используйте второго агента + привязки. См. Маршрутизация между агентами.

Пример (ЛС на хосте, группы в песочнице + только инструменты обмена сообщениями):

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // группы/каналы являются неосновными -> помещаются в песочницу
        scope: "session", // максимальная изоляция (один контейнер на группу/канал)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // Если allow не пуст, все остальное блокируется (deny все равно имеет приоритет).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

Хотите «группы могут видеть только папку X» вместо «нет доступа к хосту»? Оставьте workspaceAccess: "none" и подключите в песочницу только разрешенные пути:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

Связанное:

Ключи конфигурации и значения по умолчанию: Конфигурация шлюза
Отладка, почему инструмент заблокирован: Песочница vs Политика инструментов vs Повышенные права
Подробности о привязке томов: Песочница

Отображаемые метки

Метки в интерфейсе используют displayName, когда доступно, в формате <channel>:<token>.
#room зарезервировано для комнат/каналов; групповые чаты используют g-<slug> (нижний регистр, пробелы -> -, сохраняются #@+._-).

Групповая политика

Управление обработкой сообщений групп/комнат для каждого канала:

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // числовой идентификатор пользователя Telegram (мастер может разрешить @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["user@org.com"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

Политика	Поведение
`"open"`	Группы обходят разрешительные списки; правило упоминаний все еще применяется.
`"disabled"`	Блокировать все групповые сообщения полностью.
`"allowlist"`	Разрешать только группы/комнаты, соответствующие настроенному разрешительному списку.

Примечания:

groupPolicy отделен от правила упоминаний (которое требует @упоминаний).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: используйте groupAllowFrom (резервный вариант: явный allowFrom).
Одобрения сопряжения в ЛС (записи хранилища *-allowFrom) применяются только к доступу в ЛС; авторизация отправителя в группах остается явной для групповых разрешительных списков.
Discord: разрешительный список использует channels.discord.guilds.<id>.channels.
Slack: разрешительный список использует channels.slack.channels.
Matrix: разрешительный список использует channels.matrix.groups (идентификаторы комнат, алиасы или имена). Используйте channels.matrix.groupAllowFrom для ограничения отправителей; также поддерживаются разрешительные списки users для каждой комнаты.
Групповые ЛС управляются отдельно (channels.discord.dm.*, channels.slack.dm.*).
Разрешительный список Telegram может соответствовать идентификаторам пользователей ("123456789", "telegram:123456789", "tg:123456789") или именам пользователей ("@alice" или "alice"); префиксы нечувствительны к регистру.
По умолчанию groupPolicy: "allowlist"; если ваш групповой разрешительный список пуст, групповые сообщения блокируются.
Безопасность времени выполнения: когда блок провайдера полностью отсутствует (channels.<provider> отсутствует), групповая политика возвращается к режиму «закрыто при сбое» (обычно allowlist) вместо наследования channels.defaults.groupPolicy.

Быстрая ментальная модель (порядок оценки для групповых сообщений):

groupPolicy (open/disabled/allowlist)
Групповые разрешительные списки (*.groups, *.groupAllowFrom, специфичные для канала разрешительные списки)
Правило упоминаний (requireMention, /activation)

Правило упоминаний (по умолчанию)

Групповые сообщения требуют упоминания, если не переопределено для конкретной группы. Значения по умолчанию находятся в каждой подсистеме под *.groups."*". Ответ на сообщение бота считается неявным упоминанием (когда канал поддерживает метаданные ответа). Это применяется к Telegram, WhatsApp, Slack, Discord и Microsoft Teams.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

Примечания:

mentionPatterns — это регулярные выражения, нечувствительные к регистру.
Платформы, предоставляющие явные упоминания, все равно проходят; шаблоны являются запасным вариантом.
Переопределение на агента: agents.list[].groupChat.mentionPatterns (полезно, когда несколько агентов используют одну группу).
Правило упоминаний применяется только тогда, когда возможно обнаружение упоминаний (нативные упоминания или настроены mentionPatterns).
Значения по умолчанию для Discord находятся в channels.discord.guilds."*" (можно переопределить для каждого сервера/канала).
Контекст истории группы унифицирован для всех каналов и является только ожидающим (сообщения, пропущенные из-за правила упоминаний); используйте messages.groupChat.historyLimit для глобального значения по умолчанию и channels.<channel>.historyLimit (или channels.<channel>.accounts.*.historyLimit) для переопределений. Установите 0 для отключения.

Ограничения инструментов для групп/каналов (опционально)

Некоторые конфигурации каналов поддерживают ограничение доступных инструментов внутри конкретной группы/комнаты/канала.

tools: разрешить/запретить инструменты для всей группы.
toolsBySender: переопределения для каждого отправителя внутри группы. Используйте явные префиксы ключей: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> и подстановочный знак "*". Устаревшие ключи без префикса все еще принимаются и сопоставляются только как id:.

Порядок разрешения (выигрывает наиболее специфичный):

Совпадение toolsBySender группы/канала
tools группы/канала
Совпадение toolsBySender по умолчанию ("*")
tools по умолчанию ("*")

Пример (Telegram):

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

Примечания:

Ограничения инструментов группы/канала применяются в дополнение к глобальной/агентской политике инструментов (запрет все равно имеет приоритет).
Некоторые каналы используют другую вложенность для комнат/каналов (например, Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Разрешительные списки групп

Когда настроены channels.whatsapp.groups, channels.telegram.groups или channels.imessage.groups, ключи действуют как разрешительный список групп. Используйте "*", чтобы разрешить все группы, при этом все еще устанавливая поведение упоминаний по умолчанию. Распространенные намерения (копировать/вставить):

Отключить все ответы в группах

{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}

Разрешить только определенные группы (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}

Разрешить все группы, но требовать упоминание (явно)

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

Только владелец может активировать в группах (WhatsApp)

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Активация (только для владельца)

Владельцы групп могут переключать активацию для каждой группы:

/activation mention
/activation always

Владелец определяется channels.whatsapp.allowFrom (или собственным E.164 бота, если не установлено). Отправьте команду как отдельное сообщение. Другие платформы в настоящее время игнорируют /activation.

Поля контекста

Входящие полезные данные группы устанавливают:

ChatType=group
GroupSubject (если известно)
GroupMembers (если известно)
WasMentioned (результат правила упоминаний)
Темы форума Telegram также включают MessageThreadId и IsForum.

Системный промпт агента включает введение в группу на первом шаге новой групповой сессии. Он напоминает модели отвечать как человек, избегать таблиц Markdown и избегать ввода буквальных последовательностей \n.

Особенности iMessage

Предпочитайте chat_id:<id> при маршрутизации или составлении разрешительных списков.
Список чатов: imsg chats --limit 20.
Групповые ответы всегда возвращаются в тот же chat_id.

Особенности WhatsApp

См. Групповые сообщения для поведения, специфичного для WhatsApp (инъекция истории, детали обработки упоминаний).

Групповые сообщения Группы рассылки