Grupos

OpenClaw trata chats em grupo de forma consistente entre superfícies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

# Introdução para iniciantes (2 minutos)

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

Comportamento padrão:

• Grupos são restritos (groupPolicy: "allowlist").
• Respostas exigem uma menção, a menos que você desative explicitamente o bloqueio por menção.
• Respostas finais normais em grupos/canais são privadas por padrão. Saída visível na sala usa a ferramenta message.

Tradução: remetentes na lista de permissões podem acionar o OpenClaw mencionando-o.

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

# Respostas visíveis

Para salas de grupo/canal, OpenClaw usa por padrão messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix grava esse padrão nas configurações de canais configurados que o omitem. Isso significa que o agente ainda processa o turno e pode atualizar o estado de memória/sessão, mas sua resposta final normal não é publicada automaticamente de volta na sala. Para falar de forma visível, o agente usa message(action=send).

Esse padrão depende de um modelo/runtime que chama ferramentas de forma confiável. Se os logs mostrarem texto do assistente mas didSendViaMessagingTool: false, o modelo respondeu privadamente em vez de chamar a ferramenta de mensagem. Isso não é uma falha de envio do Discord/Slack/Telegram. Use um modelo confiável para chamadas de ferramenta em sessões de grupo/canal, ou defina messages.groupChat.visibleReplies: "automatic" para restaurar as respostas finais visíveis legadas.

Se a ferramenta de mensagem estiver indisponível sob a política de ferramentas ativa, OpenClaw volta a respostas visíveis automáticas em vez de suprimir silenciosamente a resposta. openclaw doctor avisa sobre essa incompatibilidade.

Para chats diretos e qualquer outro turno de origem, use messages.visibleReplies: "message_tool" para aplicar globalmente o mesmo comportamento de resposta visível apenas por ferramenta. Harnesses também podem escolher isso como seu padrão não definido; o harness do Codex faz isso para chats diretos em modo Codex. messages.groupChat.visibleReplies continua sendo a substituição mais específica para salas de grupo/canal.

Isso substitui o antigo padrão de forçar o modelo a responder NO_REPLY na maioria dos turnos em modo de observação. No modo somente ferramenta, não fazer nada visível significa simplesmente não chamar a ferramenta de mensagem.

Indicadores de digitação ainda são enviados enquanto o agente trabalha em modo somente ferramenta. O modo padrão de digitação em grupo é elevado de "message" para "instant" nesses turnos porque pode nunca haver texto normal de mensagem do assistente antes que o agente decida chamar ou não a ferramenta de mensagem. A configuração explícita do modo de digitação ainda prevalece.

Para restaurar respostas finais automáticas legadas para salas de grupo/canal:

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

O Gateway recarrega a configuração de messages a quente depois que o arquivo é salvo. Reinicie somente quando a observação de arquivos ou o recarregamento de configuração estiver desativado na implantação.

Para exigir que a saída visível passe pela ferramenta de mensagem em todo chat de origem:

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

Comandos de barra nativos (Discord, Telegram e outras superfícies com suporte nativo a comandos) ignoram visibleReplies: "message_tool" e sempre respondem de forma visível para que a UI de comando nativa do canal receba a resposta esperada. Isso se aplica apenas a turnos de comando nativo validados; comandos /... digitados como texto e turnos de chat comuns ainda seguem o padrão de grupo configurado.

# Visibilidade de 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 de contexto: qual contexto suplementar é injetado no modelo (texto de resposta, citações, histórico de thread, metadados encaminhados).

Por padrão, OpenClaw prioriza o comportamento normal de chat e mantém o contexto principalmente como recebido. Isso significa que listas de permissões decidem principalmente quem pode acionar ações, não um limite universal de redação para cada trecho citado ou histórico.

Se você quer...

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

# Chaves de sessão

• Sessões de grupo usam chaves de sessão 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 o seu tráfego "pessoal" são DMs e o seu tráfego "público" são grupos.

Motivo: no modo de agente único, DMs normalmente chegam na 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 serão executadas no backend de sandbox configurado, enquanto sua sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um.

Isso dá a você um "cérebro" de agente (workspace + memória compartilhados), mas duas posturas de execução:

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

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

Relacionado:

• Chaves de configuração e padrões: Configuração do Gateway
• Depuração de por que uma ferramenta está bloqueada: Sandbox vs Política de ferramentas vs Elevado
• Detalhes de montagens de vinculação: Sandboxing

# Rótulos de exibição

• Rótulos da 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 -> -, manter #@+._-).

# 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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

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

# Controle por menção (padrão)

Mensagens de grupo exigem uma menção, salvo substituição por grupo. Os padrões ficam por subsistema em *.groups."*".

Responder a uma mensagem do bot conta como uma menção implícita quando o canal oferece suporte a metadados de resposta. Citar uma mensagem do bot também pode contar como uma menção implícita em canais que expõem metadados de citação. Os casos integrados atuais incluem Telegram, WhatsApp, Slack, Discord, Microsoft Teams e 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,
        },
      },
    ],
  },
}

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

Algumas configurações de canal oferecem suporte à restrição de quais ferramentas estão disponíveis dentro de um grupo/sala/canal específico.

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

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

Exemplo (Telegram):

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

# Allowlists de grupo

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

Intenções comuns (copiar/colar):

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

# Ativação (somente proprietário)

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

• /activation mention
• /activation always

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

# Campos de contexto

Payloads de entrada de grupo definem:

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

Notas específicas por canal:

• BlueBubbles pode, opcionalmente, enriquecer participantes de grupos macOS sem nome a partir do banco de dados local de Contatos antes de preencher GroupMembers. Isso fica desativado por padrão e só é executado depois que o controle normal de grupo passa.

O prompt do 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 uma pessoa, evitar tabelas Markdown, minimizar linhas vazias e seguir o espaçamento normal de chat, além de evitar digitar sequências literais \n. Nomes de grupos e rótulos de participantes vindos do canal são renderizados como metadados não confiáveis em bloco cercado, não como instruções de sistema inline.

# Especificidades do iMessage

• Prefira chat_id:<id> ao rotear ou colocar na allowlist.
• Listar chats: imsg chats --limit 20.
• Respostas de grupo sempre voltam para o mesmo chat_id.

# Prompts de sistema do WhatsApp

Consulte WhatsApp para as regras canônicas de prompt de sistema do WhatsApp, incluindo resolução de prompt de grupo e direto, comportamento de curinga e semântica de substituição de conta.

# Especificidades do WhatsApp

Consulte Mensagens de grupo para comportamento exclusivo do WhatsApp (injeção de histórico, detalhes de tratamento de menção).

# Relacionado

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