Grupos

O OpenClaw trata chats em grupo de forma consistente em todas as plataformas: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Introdução para iniciantes (2 minutos)

O OpenClaw “vive” nas suas próprias contas de mensagens. Não existe um usuário bot separado do WhatsApp. Se você está em um grupo, o OpenClaw pode ver esse grupo e responder lá.

Comportamento padrão:

  • Grupos são restritos (groupPolicy: "allowlist").
  • Respostas exigem menção, a menos que você desative explicitamente a verificação de menção.

Traduzindo: remetentes na lista de permitidos podem acionar o OpenClaw mencionando-o.

TL;DR

  • Acesso a DMs é controlado por *.allowFrom.
  • Acesso a grupos é controlado por *.groupPolicy + listas de permitidos (*.groups, *.groupAllowFrom).
  • Acionamento de respostas é controlado pela verificação de menção (requireMention, /activation).

Fluxo rápido (o que acontece com uma mensagem de grupo):

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

Group message flow

Se você quer…

ObjetivoO que configurar
Permitir todos os grupos mas só responder com @mençãogroups: { "*": { requireMention: true } }
Desativar todas as respostas em gruposgroupPolicy: "disabled"
Apenas grupos específicosgroups: { "<group-id>": { ... } } (sem chave "*")
Apenas você pode acionar em gruposgroupPolicy: "allowlist", groupAllowFrom: ["+1555..."]

Chaves de sessão

  • Sessões de grupo usam chaves agent:<agentId>:<channel>:group:<id> (salas/canais usam agent:<agentId>:<channel>:channel:<id>).
  • Tópicos de fórum do Telegram adicionam :topic:<threadId> ao id do grupo para que cada tópico tenha sua própria sessão.
  • Chats diretos usam a sessão principal (ou por remetente, se configurado).
  • Heartbeats são ignorados para sessões de grupo.

Padrão: DMs pessoais + grupos públicos (agente único)

Sim — isso funciona bem se seu tráfego “pessoal” são DMs e seu tráfego “público” são grupos.

Por quê: no modo de agente único, DMs normalmente chegam à chave de sessão principal (agent:main:main), enquanto grupos sempre usam chaves de sessão não principais (agent:main:<channel>:group:<id>). Se você ativar sandboxing com mode: "non-main", essas sessões de grupo rodam em Docker enquanto sua sessão principal de DM fica no host.

Isso te dá um “cérebro” de agente (workspace + memória compartilhados), mas duas posturas de execução:

  • DMs: ferramentas completas (host)
  • Grupos: sandbox + ferramentas restritas (Docker)

Se você precisa de workspaces/personas verdadeiramente separados (“pessoal” e “público” nunca devem se misturar), use um segundo agente + bindings. Veja Roteamento Multi-Agente.

Exemplo (DMs no host, grupos em sandbox + apenas ferramentas de mensagens):

{
  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"],
      },
    },
  },
}

Quer que “grupos só possam ver a pasta X” em vez de “sem acesso ao host”? Mantenha workspaceAccess: "none" e monte apenas os caminhos permitidos no sandbox:

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

Relacionado:

Rótulos de exibição

  • Rótulos de UI usam displayName quando disponível, formatado como <channel>:<token>.
  • #room é reservado para salas/canais; chats em grupo usam g-<slug> (minúsculas, espaços → -, mantém #@+._-).

Política de grupo

Controle como mensagens de grupo/sala são tratadas por canal:

{
  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": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}
PolíticaComportamento
"open"Grupos ignoram as listas de permitidos; a verificação de menção ainda se aplica.
"disabled"Bloqueia todas as mensagens de grupo completamente.
"allowlist"Permite apenas grupos/salas que correspondam à lista de permitidos configurada.

Notas:

  • groupPolicy é separado da verificação de menção (que exige @menções).
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: usam groupAllowFrom (fallback: allowFrom explícito).
  • Aprovações de pareamento de DM (entradas *-allowFrom do armazenamento) se aplicam apenas ao acesso por DM; a autorização de remetente em grupo permanece explícita nas listas de permitidos do grupo.
  • Discord: lista de permitidos usa channels.discord.guilds.<id>.channels.
  • Slack: lista de permitidos usa channels.slack.channels.
  • Matrix: lista de permitidos usa channels.matrix.groups (IDs de sala, aliases ou nomes). Use channels.matrix.groupAllowFrom para restringir remetentes; listas de permitidos por sala com users também são suportadas.
  • DMs de grupo são controlados separadamente (channels.discord.dm.*, channels.slack.dm.*).
  • A lista de permitidos do Telegram pode corresponder a IDs de usuário ("123456789", "telegram:123456789", "tg:123456789") ou nomes de usuário ("@alice" ou "alice"); prefixos são case-insensitive.
  • O padrão é groupPolicy: "allowlist"; se sua lista de permitidos de grupo estiver vazia, mensagens de grupo são bloqueadas.
  • Segurança em tempo de execução: quando um bloco de provedor está completamente ausente (channels.<provider> não existe), a política de grupo recorre ao modo fail-closed (normalmente allowlist) em vez de herdar channels.defaults.groupPolicy.

Modelo mental rápido (ordem de avaliação para mensagens de grupo):

  1. groupPolicy (open/disabled/allowlist)
  2. Listas de permitidos de grupo (*.groups, *.groupAllowFrom, lista de permitidos específica do canal)
  3. Verificação de menção (requireMention, /activation)

Verificação de menção (padrão)

Mensagens de grupo exigem menção a menos que sejam substituídas por grupo. Os padrões ficam por subsistema em *.groups."*".

Responder a uma mensagem do bot conta como menção implícita (quando o canal suporta metadados de resposta). Isso se aplica a Telegram, WhatsApp, Slack, Discord e Microsoft Teams.

{
  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,
        },
      },
    ],
  },
}

Notas:

  • mentionPatterns são expressões regulares case-insensitive.
  • Plataformas que fornecem menções explícitas continuam funcionando; os padrões são um fallback.
  • Substituição por agente: agents.list[].groupChat.mentionPatterns (útil quando vários agentes compartilham um grupo).
  • A verificação de menção só é aplicada quando a detecção de menção é possível (menções nativas ou mentionPatterns configurados).
  • Os padrões do Discord estão em channels.discord.guilds."*" (podem ser substituídos por servidor/canal).
  • O contexto de histórico de grupo é encapsulado uniformemente entre canais e é apenas pendente (mensagens ignoradas pela verificação de menção); use messages.groupChat.historyLimit para o padrão global e channels.<channel>.historyLimit (ou channels.<channel>.accounts.*.historyLimit) para substituições. Defina 0 para desativar.

Restrições de ferramentas por grupo/canal (opcional)

Algumas configurações de canal permitem restringir quais ferramentas estão disponíveis dentro de um grupo/sala/canal específico.

  • tools: permite/nega ferramentas para todo o grupo.
  • toolsBySender: substituições por remetente dentro do grupo. Use prefixos de chave explícitos: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, e curinga "*". Chaves legacy sem prefixo ainda são aceitas e correspondidas apenas como id:.

Ordem de resolução (o mais específico ganha):

  1. toolsBySender do grupo/canal correspondente
  2. tools do grupo/canal
  3. toolsBySender padrão ("*") correspondente
  4. tools padrão ("*")

Exemplo (Telegram):

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

Notas:

  • Restrições de ferramentas de grupo/canal são aplicadas além da política de ferramentas global/agente (deny sempre ganha).
  • Alguns canais usam aninhamento diferente para salas/canais (ex.: Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Listas de permitidos de grupo

Quando channels.whatsapp.groups, channels.telegram.groups ou channels.imessage.groups está configurado, as chaves atuam como lista de permitidos de grupo. Use "*" para permitir todos os grupos enquanto configura o comportamento de menção padrão.

Padrões comuns (copiar/colar):

  1. Desativar todas as respostas em grupos
{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}
  1. Permitir apenas grupos específicos (WhatsApp)
{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}
  1. Permitir todos os grupos mas exigir menção (explícito)
{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  1. Apenas o proprietário pode acionar em grupos (WhatsApp)
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Ativação (apenas proprietário)

Proprietários de grupo podem alternar a ativação por grupo:

  • /activation mention
  • /activation always

O proprietário é determinado por channels.whatsapp.allowFrom (ou o E.164 próprio do bot quando não configurado). Envie o comando como uma mensagem independente. Outras plataformas atualmente ignoram /activation.

Campos de contexto

Payloads de entrada de grupo definem:

  • ChatType=group
  • GroupSubject (se conhecido)
  • GroupMembers (se conhecido)
  • WasMentioned (resultado da verificação de menção)
  • Tópicos de fórum do Telegram também incluem MessageThreadId e IsForum.

O prompt de sistema do agente inclui uma introdução de grupo no primeiro turno de uma nova sessão de grupo. Ele lembra o modelo de responder como um humano, evitar tabelas Markdown e evitar digitar sequências literais \n.

Especificidades do iMessage

  • Prefira chat_id:<id> ao rotear ou configurar listas de permitidos.
  • Listar chats: imsg chats --limit 20.
  • Respostas de grupo sempre vão para o mesmo chat_id.

Especificidades do WhatsApp

Veja Mensagens de grupo para o comportamento específico do WhatsApp (injeção de histórico, detalhes do tratamento de menções).

arrow_back
Anterior
Group Messages
Próximo
Broadcast Groups
arrow_forward