Grupos

OpenClaw aplica as mesmas regras de grupo em todos os canais compatíveis com grupos, incluindo Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp e Zalo.

Para salas sempre ativas que devem fornecer contexto silencioso, a menos que o agente envie explicitamente uma mensagem visível, consulte Eventos de sala em segundo plano.

Introdução para iniciantes (2 minutos)

O OpenClaw "vive" nas suas próprias contas de mensagens. Não há um usuário bot separado no WhatsApp: se você estiver em um grupo, o OpenClaw poderá ver esse grupo e responder nele.

Comportamento padrão:

• Os grupos são restritos (groupPolicy: "allowlist"); os remetentes dos grupos ficam bloqueados até serem incluídos na lista de permissões.
• As respostas exigem uma menção, a menos que você desative a exigência de menção para um grupo.
• O texto da resposta final é publicado automaticamente na sala (visibleReplies: "automatic").

Em outras palavras: remetentes incluídos na lista de permissões podem acionar o OpenClaw ao mencioná-lo.

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

groupPolicy? disabled -> descartargroupPolicy? allowlist -> grupo permitido? não -> descartarrequireMention? sim -> houve menção? não -> armazenar apenas para contextomenção/resposta/comando/mensagem direta -> solicitação do usuárioconversa de grupo sempre ativa -> solicitação do usuário ou evento de sala, quando configurado

Respostas visíveis

Para solicitações normais de grupos/canais, o padrão do OpenClaw é messages.groupChat.visibleReplies: "automatic": o texto final do assistente é publicado na sala como resposta visível.

Use messages.groupChat.visibleReplies: "message_tool" quando uma sala compartilhada precisar permitir que o agente decida quando falar chamando message(action=send). Isso funciona melhor com modelos que usam ferramentas de forma confiável (por exemplo, GPT-5.6 Sol). Se o modelo não usar a ferramenta e retornar um texto final substancial, o OpenClaw manterá esse texto privado em vez de publicá-lo na sala.

Use "automatic" para modelos ou runtimes que não seguem de forma confiável a entrega somente por ferramenta: textos finais normais são publicados diretamente na sala, e o agente ainda pode chamar message(action=send) para arquivos, imagens ou outros anexos que não possam acompanhar o texto final.

Se a ferramenta de mensagens não estiver disponível de acordo com a política de ferramentas ativa, o OpenClaw voltará às respostas visíveis automáticas em vez de suprimir silenciosamente a resposta. openclaw doctor alerta sobre essa incompatibilidade.

Para conversas diretas e qualquer outro evento de origem, messages.visibleReplies: "message_tool" aplica globalmente o mesmo comportamento somente por ferramenta; messages.groupChat.visibleReplies continua sendo a substituição mais específica para salas de grupos/canais. Por padrão, interações diretas internas do WebChat usam a entrega automática da resposta final, para que Pi e Codex recebam o mesmo contrato de resposta visível.

O modo somente por ferramenta substitui o padrão antigo de forçar o modelo a responder NO_REPLY na maioria das interações em modo observador. No modo somente por ferramenta, o prompt não define um contrato NO_REPLY; não fazer nada visível significa simplesmente não chamar a ferramenta de mensagens.

Vinculações de conversa pertencentes a plugins são a exceção. Depois que um plugin vincula uma thread e assume a interação de entrada, a resposta retornada pelo plugin é a resposta visível da vinculação; ela não precisa de message(action=send). Essa resposta é uma saída do runtime do plugin, não um texto final privado do modelo.

Os indicadores de digitação ainda são enviados para solicitações diretas de grupos. Quando habilitados, os eventos em segundo plano de salas sempre ativas permanecem estritos e silenciosos, a menos que o agente chame a ferramenta de mensagens.

Por padrão, as sessões suprimem resumos detalhados de ferramentas/progresso. Use /verbose on (ou /verbose full) para exibi-los na sessão atual durante a depuração e /verbose off para retornar ao comportamento que mostra apenas a resposta final. O estado detalhado é específico de cada sessão e funciona da mesma forma em conversas diretas, grupos, canais e tópicos de fóruns.

Para enviar conversas não mencionadas de grupos sempre ativos como contexto silencioso da sala em vez de solicitações do usuário, use Eventos de sala em segundo plano:

{  messages: {    groupChat: {      unmentionedInbound: "room_event",    },  },}

O padrão é unmentionedInbound: "user_request". Mensagens com menções, comandos, solicitações de cancelamento e mensagens diretas continuam sendo solicitações do usuário.

Para exigir que a saída visível passe pela ferramenta de mensagens nas solicitações de grupos/canais:

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

Para exigir isso em todas as conversas de origem:

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

O Gateway detecta alterações na configuração messages sem precisar ser reiniciado após o arquivo ser salvo. Reinicie somente quando o recarregamento da configuração estiver desativado (gateway.reload.mode: "off").

Interações de comando ignoram visibleReplies: "message_tool" e sempre respondem de forma visível: tanto os comandos de barra nativos (Discord, Telegram e outras interfaces com suporte nativo a comandos) quanto os comandos de texto /... autorizados publicam suas respostas na conversa de origem. Interações de texto /... não autorizadas em grupos permanecem somente por ferramenta de mensagens; interações de conversa comuns seguem o padrão configurado.

Visibilidade do contexto e listas de permissões

Dois controles diferentes estão envolvidos na segurança de grupos:

• Autorização de acionamento: quem pode acionar o agente (groupPolicy, groups, groupAllowFrom, listas de permissões específicas do canal).
• Visibilidade do contexto: qual contexto complementar é injetado no modelo (texto de resposta/citação, histórico da thread, metadados encaminhados).

Por padrão, o OpenClaw mantém o contexto como recebido: as listas de permissões determinam quem pode acionar ações, não quais trechos citados ou históricos o modelo vê. Para também filtrar o contexto complementar, defina contextVisibility:

Defina essa opção por canal (channels.<channel>.contextVisibility), por conta (channels.<channel>.accounts.<accountId>.contextVisibility) ou globalmente (channels.defaults.contextVisibility). Os canais que obtêm contexto complementar (Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp) aplicam a política ao criar o contexto de entrada; combinações de políticas desconhecidas adotam uma postura fechada e omitem o contexto.

Se você quiser...

Para listas de permissões de remetentes reutilizáveis, consulte Grupos de acesso.

Chaves de sessão

• As sessões de grupo usam chaves de sessão agent:<agentId>:<channel>:group:<id> (salas/canais usam agent:<agentId>:<channel>:channel:<id>).
• Os tópicos de fóruns do Telegram adicionam :topic:<threadId> ao ID do grupo, para que cada tópico tenha sua própria sessão.
• As conversas diretas usam a sessão principal (ou sessões por remetente, se session.dmScope estiver configurado).
• Heartbeats são executados na sessão de Heartbeat configurada (padrão: a sessão principal do agente); as sessões de grupo não executam seus próprios Heartbeats.

Padrão: mensagens diretas pessoais + grupos públicos (um único agente)

Sim — isso funciona bem se o seu tráfego "pessoal" ocorrer por mensagens diretas e o seu tráfego "público" ocorrer em grupos.

Motivo: no modo de agente único, as mensagens diretas normalmente chegam à chave de sessão principal (agent:main:main), enquanto os grupos sempre usam chaves de sessão não principais (agent:main:<channel>:group:<id>). Se você habilitar o sandboxing com mode: "non-main", essas sessões de grupo serão executadas no backend de sandbox configurado, enquanto sua sessão principal de mensagens diretas permanecerá no host. Docker será o backend padrão se você não escolher um.

Isso oferece um único "cérebro" de agente (workspace + memória compartilhados), mas duas posturas de execução:

• Mensagens diretas: ferramentas completas (host)
• Grupos: sandbox + ferramentas restritas

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // grupos/canais não são principais -> no sandbox        scope: "session", // isolamento mais forte (um contêiner por grupo/canal)        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // Se allow não estiver vazio, todo o restante será bloqueado (deny ainda prevalece).        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: [            // caminhoNoHost:caminhoNoContêiner:modo            "/home/user/FriendsShared:/data:ro",          ],        },      },    },  },}

Relacionado:

• Chaves de configuração e padrões: Configuração do Gateway
• Como depurar por que uma ferramenta está bloqueada: Sandbox vs. política de ferramentas vs. modo elevado
• Detalhes das montagens bind: Sandboxing

Rótulos de exibição

• Os rótulos da interface usam displayName quando disponível, formatado como <channel>:<token>.
• #room é reservado para salas/canais; conversas em grupo usam g-<slug> (minúsculas, espaços -> -, manter #@+._-). IDs opacos muito longos são reduzidos a um token estável, em vez de expor IDs completos de rotas na interface.

Política de grupos

Controle como as mensagens de grupos/salas são tratadas em cada canal:

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // ID numérico de usuário do Telegram (a configuração resolve @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: { enabled: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { enabled: true } },    },    matrix: {      groupPolicy: "allowlist",      groupAllowFrom: ["@owner:example.org"],      groups: {        "!roomId:example.org": { enabled: true },        "#alias:example.org": { enabled: true },      },    },  },}

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

Exigência de menção (padrão)

Mensagens de grupo exigem uma menção, a menos que isso seja substituído por grupo. Os padrões ficam em cada subsistema, em *.groups."*".

Responder a uma mensagem do bot conta como uma menção implícita quando o canal fornece metadados de resposta; citar uma mensagem do bot também pode contar em canais que fornecem metadados de citação. Casos integrados atuais: Discord, Microsoft Teams, QQBot, Slack, Telegram, WhatsApp e Zalo pessoal.

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

Definir o escopo dos padrões de menção configurados

Os mentionPatterns configurados são gatilhos regex alternativos. Use-os quando a plataforma não fornecer uma menção nativa ao bot ou quando quiser que texto simples, como openclaw:, conte como uma menção. As menções nativas da plataforma são separadas: quando Discord, Slack, Telegram, Matrix, Signal ou outro canal puder comprovar que a mensagem mencionou explicitamente o bot, essa menção nativa ainda será acionada, mesmo que os padrões regex configurados sejam negados.

Por padrão, os padrões de menção configurados se aplicam em todos os locais em que o canal passa informações do provedor e da conversa para a detecção de menções. Para impedir que padrões amplos despertem o agente em todos os grupos, defina o escopo por canal com channels.<channel>.mentionPatterns.

Use mode: "deny" quando os padrões regex de menção devam ficar desativados por padrão em um canal e, depois, habilite-os em salas específicas com allowIn:

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b", "\\bops bot\\b"],    },  },  channels: {    slack: {      mentionPatterns: {        mode: "deny",        allowIn: ["C0123OPS"],      },    },  },}

Use o padrão mode: "allow" (ou omita mode) quando os padrões regex de menção devam se aplicar amplamente e, depois, desative-os em salas movimentadas com denyIn:

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b"],    },  },  channels: {    telegram: {      mentionPatterns: {        denyIn: ["-1001234567890", "-1001234567890:topic:42"],      },    },  },}

Resolução da política:

Política regex com escopo compatível atualmente:

As configurações de canal no nível da conta podem definir a mesma política em channels.<channel>.accounts.<accountId>.mentionPatterns quando esse canal oferece suporte a várias contas. Para essa conta, a política da conta tem precedência sobre a política de canal de nível superior.

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 (allow, alsoAllow, deny; a negação prevalece).
• toolsBySender: substituições por remetente dentro do grupo. Use prefixos de chave explícitos: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> e o curinga "*". IDs de canal usam IDs de canal canônicos do OpenClaw; aliases como teams são normalizados para msteams. Chaves legadas sem prefixo ainda são aceitas, correspondem somente como id: e registram um aviso de descontinuação.

Ordem de resolução (a mais específica prevalece):

Exemplo (Telegram):

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

Listas de permissões de grupos

Quando channels.whatsapp.groups, channels.telegram.groups ou channels.imessage.groups está configurado, as chaves funcionam como uma lista de permissões de grupos. Use "*" para permitir todos os grupos e ainda definir o comportamento padrão de menções.

Intenções comuns (copie e cole):

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

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

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

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

Ativação (somente proprietário)

Os proprietários de grupos podem alternar a ativação por grupo com uma mensagem independente:

• /activation mention
• /activation always

/activation é um comando central restrito ao proprietário e se aplica apenas a conversas em grupo. Proprietário significa que o remetente corresponde a commands.ownerAllowFrom; as listas allowFrom do canal controlam apenas o acesso comum ao canal e aos comandos. O modo armazenado substitui o requireMention desse grupo nos canais que o consultam (Google Chat, QQBot, Telegram, WhatsApp), e a introdução do prompt de sistema do grupo reflete o modo ativo em todos os lugares.

Campos de contexto

As cargas de entrada de grupos definem:

• ChatType=group
• GroupSubject (se conhecido)
• GroupMembers (se conhecido)
• WasMentioned (resultado da restrição por menção)
• Os tópicos de fóruns 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 (e após alterações em /activation). Ela lembra o modelo de responder como uma pessoa, minimizar linhas vazias, seguir o espaçamento normal de conversas e evitar digitar sequências literais \n. Canais cujo modo de tabela declarado não preserva tabelas nativas ou brutas também desaconselham tabelas Markdown. Nomes de grupos e rótulos de participantes provenientes de canais são renderizados como metadados não confiáveis delimitados por cercas, e não como instruções de sistema em linha.

Particularidades do iMessage

• Prefira chat_id:<id> ao rotear ou adicionar à lista de permissões.
• Liste as conversas: imsg chats --limit 20.
• As respostas em grupos sempre retornam ao mesmo chat_id.

Prompts de sistema do WhatsApp

Consulte WhatsApp para ver as regras canônicas de prompts de sistema do WhatsApp, incluindo a resolução de prompts de grupo e diretos, o comportamento de curingas e a semântica de substituição por conta.

Particularidades do WhatsApp

Consulte Mensagens em grupo para conhecer o comportamento exclusivo do WhatsApp (injeção de histórico e detalhes do tratamento de menções).

Relacionados

• Grupos de transmissão
• Roteamento de canais
• Mensagens em grupo
• Pareamento