Групи

OpenClaw обробляє групові чати узгоджено на всіх поверхнях: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

# Вступ для початківців (2 хвилини)

OpenClaw «живе» у ваших власних облікових записах месенджерів. Окремого користувача-бота WhatsApp немає. Якщо ви перебуваєте в групі, OpenClaw може бачити цю групу й відповідати в ній.

Типова поведінка:

• Групи обмежені (groupPolicy: "allowlist").
• Відповіді потребують згадки, якщо ви явно не вимкнули обмеження за згадкою.
• Звичайні фінальні відповіді в групах/каналах за замовчуванням приватні. Видимий вивід у кімнату використовує інструмент message.

Інакше кажучи: відправники зі списку дозволених можуть запускати OpenClaw, згадуючи його.

Швидкий потік (що відбувається з груповим повідомленням):

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

# Видимі відповіді

Для групових/канальних кімнат OpenClaw за замовчуванням використовує messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix записує це типове значення в конфігурації налаштованих каналів, де його пропущено. Це означає, що агент усе одно обробляє хід і може оновлювати стан памʼяті/сесії, але його звичайна фінальна відповідь не публікується автоматично назад у кімнату. Щоб говорити видимо, агент використовує message(action=send).

Це типове значення залежить від моделі/середовища виконання, які надійно викликають інструменти. Якщо журнали показують текст асистента, але didSendViaMessagingTool: false, модель відповіла приватно замість виклику інструмента повідомлень. Це не збій надсилання Discord/Slack/Telegram. Для групових/канальних сесій використовуйте модель, яка надійно викликає інструменти, або встановіть messages.groupChat.visibleReplies: "automatic", щоб відновити застарілі видимі фінальні відповіді.

Якщо інструмент повідомлень недоступний за активною політикою інструментів, OpenClaw повертається до автоматичних видимих відповідей замість тихого приглушення відповіді. openclaw doctor попереджає про цю невідповідність.

Для прямих чатів і будь-якого іншого початкового ходу використовуйте messages.visibleReplies: "message_tool", щоб застосувати таку саму поведінку видимих відповідей лише через інструмент глобально. Тестові середовища також можуть вибрати це як типове значення, коли воно не задане; середовище Codex робить це для прямих чатів у режимі Codex. messages.groupChat.visibleReplies лишається конкретнішим перевизначенням для групових/канальних кімнат.

Це замінює старий шаблон примушування моделі відповідати NO_REPLY для більшості ходів у режимі пасивного спостереження. У режимі лише з інструментами відсутність видимих дій просто означає, що інструмент повідомлень не викликається.

Індикатори набору тексту все ще надсилаються, поки агент працює в режимі лише з інструментами. Типовий груповий режим набору тексту для таких ходів підвищується з "message" до "instant", бо звичайного тексту повідомлення асистента може взагалі не бути до того, як агент вирішить, чи викликати інструмент повідомлень. Явна конфігурація режиму набору тексту все ще має пріоритет.

Щоб відновити застарілі автоматичні фінальні відповіді для групових/канальних кімнат:

{
  messages: {
    groupChat: {
      visibleReplies: "automatic",
    },
  },
}

Gateway гаряче перезавантажує конфігурацію messages після збереження файла. Перезапускайте лише тоді, коли спостереження за файлами або перезавантаження конфігурації вимкнено в розгортанні.

Щоб вимагати, аби видимий вивід для кожного початкового чату проходив через інструмент повідомлень:

{
  messages: {
    visibleReplies: "message_tool",
  },
}

Нативні slash-команди (Discord, Telegram та інші поверхні з підтримкою нативних команд) обходять visibleReplies: "message_tool" і завжди відповідають видимо, щоб нативний для каналу інтерфейс команд отримав очікувану відповідь. Це стосується лише перевірених ходів нативних команд; команди /..., набрані як текст, і звичайні ходи чату все ще дотримуються налаштованого типового значення для груп.

# Видимість контексту та списки дозволених

У безпеці груп беруть участь два різні механізми керування:

• Авторизація запуску: хто може запускати агента (groupPolicy, groups, groupAllowFrom, списки дозволених для окремих каналів).
• Видимість контексту: який додатковий контекст додається в модель (текст відповіді, цитати, історія гілки, метадані пересилання).

За замовчуванням OpenClaw надає пріоритет звичайній поведінці чату й здебільшого зберігає контекст таким, яким його отримано. Це означає, що списки дозволених насамперед визначають, хто може запускати дії, а не є універсальною межею редагування для кожного процитованого або історичного фрагмента.

Якщо ви хочете...

Про багаторазово використовувані списки дозволених відправників див. Групи доступу.

# Ключі сесій

• Групові сесії використовують ключі сесій 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", ці групові сесії запускаються в налаштованому ізольованому бекенді, а ваша основна сесія приватних повідомлень лишається на хості. Docker — типовий бекенд, якщо ви не виберете інший.

Це дає вам один «мозок» агента (спільний робочий простір + памʼять), але дві позиції виконання:

• Приватні повідомлення: повні інструменти (хост)
• Групи: ізоляція + обмежені інструменти

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // groups/channels are non-main -> sandboxed
        scope: "session", // strongest isolation (one container per group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // If allow is non-empty, everything else is blocked (deny still wins).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

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

Повʼязане:

• Ключі конфігурації та типові значення: Конфігурація Gateway
• Налагодження, чому інструмент заблоковано: Ізоляція vs політика інструментів vs підвищені права
• Подробиці bind-монтувань: Ізоляція

# Відображувані мітки

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

# Політика груп

Керуйте обробкою групових повідомлень/повідомлень кімнат для кожного каналу:

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["[email protected]"],
    },
    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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

Швидка ментальна модель (порядок оцінювання для групових повідомлень):

# Обмеження за згадками (типово)

Групові повідомлення потребують згадки, якщо це не перевизначено для групи. Типові значення зберігаються для кожної підсистеми в *.groups."*".

Відповідь на повідомлення бота вважається неявною згадкою, коли канал підтримує метадані відповіді. Цитування повідомлення бота також може вважатися неявною згадкою в каналах, які надають метадані цитування. Поточні вбудовані випадки включають Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "[email protected]": { 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,
        },
      },
    ],
  },
}

# Обмеження інструментів для групи/каналу (необов’язково)

Деякі конфігурації каналів підтримують обмеження того, які інструменти доступні всередині конкретної групи/кімнати/каналу.

• tools: дозволити/заборонити інструменти для всієї групи.
• toolsBySender: перевизначення для окремих відправників у групі. Використовуйте явні префікси ключів: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> і wildcard "*". Застарілі ключі без префікса все ще приймаються й зіставляються лише як id:.

Порядок розв’язання (найконкретніше перемагає):

Приклад (Telegram):

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

# Групові списки дозволів

Коли налаштовано channels.whatsapp.groups, channels.telegram.groups або channels.imessage.groups, ключі працюють як груповий список дозволів. Використовуйте "*", щоб дозволити всі групи й водночас задати типову поведінку згадок.

Поширені наміри (скопіюйте/вставте):

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

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

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

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

# Активація (лише власник)

Власники груп можуть перемикати активацію для кожної групи:

• /activation mention
• /activation always

Власник визначається за channels.whatsapp.allowFrom (або за власним E.164 бота, якщо не задано). Надсилайте команду окремим повідомленням. Інші поверхні наразі ігнорують /activation.

# Поля контексту

Вхідні групові payload задають:

• ChatType=group
• GroupSubject (якщо відомо)
• GroupMembers (якщо відомо)
• WasMentioned (результат обмеження за згадками)
• Теми форумів Telegram також включають MessageThreadId та IsForum.

Нотатки для окремих каналів:

• BlueBubbles може за бажанням доповнювати безіменних учасників груп macOS з локальної бази даних Contacts перед заповненням GroupMembers. Це вимкнено за замовчуванням і виконується лише після проходження звичайної групової перевірки.

Системна підказка агента включає груповий вступ на першому ході нової групової сесії. Вона нагадує моделі відповідати як людина, уникати Markdown-таблиць, мінімізувати порожні рядки й дотримуватися звичайних інтервалів чату, а також уникати введення буквальних послідовностей \n. Назви груп і мітки учасників, отримані з каналу, відтворюються як fenced недовірені метадані, а не як вбудовані системні інструкції.

# Специфіка iMessage

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

# Системні підказки WhatsApp

Див. WhatsApp для канонічних правил системних підказок WhatsApp, включно з розв’язанням групових і прямих підказок, поведінкою wildcard і семантикою перевизначення облікового запису.

# Специфіка WhatsApp

Див. Групові повідомлення щодо поведінки лише для WhatsApp (ін’єкція історії, деталі обробки згадок).

# Пов’язане

• Групи трансляцій
• Маршрутизація каналів
• Групові повідомлення
• Сполучення