​

Grupos

​

Introdução para iniciantes (2 minutos)

• Grupos são restritos (groupPolicy: "allowlist").
• Respostas exigem uma menção, a menos que você desative explicitamente o controle por menções.

TL;DR

• Acesso a DM é controlado por *.allowFrom.
• Acesso a grupos é controlado por *.groupPolicy + listas de permissões (*.groups, *.groupAllowFrom).
• Disparo de respostas é controlado pelo controle por menções (requireMention, /activation).

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

​

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)

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

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

{
  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
            "~/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

• 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 bind mounts: 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 grupos

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789", "@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 },
      },
    },
  },
}

• groupPolicy é separado do controle por menções (que exige @menções).
• WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: use groupAllowFrom (fallback: allowFrom explícito).
• Discord: a lista de permissões usa channels.discord.guilds.<id>.channels.
• Slack: a lista de permissões usa channels.slack.channels.
• Matrix: a lista de permissões usa channels.matrix.groups (IDs de sala, aliases ou nomes). Use channels.matrix.groupAllowFrom para restringir remetentes; listas de permissões por sala users também são suportadas.
• DMs em grupo são controladas separadamente (channels.discord.dm.*, channels.slack.dm.*).
• A lista de permissões do Telegram pode corresponder a IDs de usuário ("123456789", "telegram:123456789", "tg:123456789") ou nomes de usuário ("@alice" ou "alice"); prefixos não diferenciam maiúsculas/minúsculas.
• O padrão é groupPolicy: "allowlist"; se sua lista de permissões de grupos estiver vazia, mensagens de grupo são bloqueadas.

1. groupPolicy (open/disabled/allowlist)
2. listas de permissões de grupo (*.groups, *.groupAllowFrom, lista específica do canal)
3. controle por menções (requireMention, /activation)

​

Mencionar gating (padrão)

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

• mentionPatterns são regexes que não diferenciam maiúsculas/minúsculas.
• Superfícies que fornecem menções explícitas ainda passam; os padrões são um fallback.
• Substituição por agente: agents.list[].groupChat.mentionPatterns (útil quando vários agentes compartilham um grupo).
• O controle por menções só é aplicado quando a detecção de menções é possível (menções nativas ou mentionPatterns configurados).
• Os padrões do Discord vivem em channels.discord.guilds."*" (substituíveis por guild/canal).
• O contexto de histórico de grupo é encapsulado de forma uniforme entre canais e é apenas pendente (mensagens ignoradas por causa do controle por menções); 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)

• tools: permitir/negar ferramentas para o grupo inteiro.
• toolsBySender: substituições por remetente dentro do grupo (as chaves são IDs de remetente/nomes de usuário/emails/números de telefone, dependendo do canal). Use "*" como curinga.

1. correspondência de toolsBySender do grupo/canal
2. tools do grupo/canal
3. correspondência padrão ("*") toolsBySender
4. padrão ("*") tools

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

• Restrições de ferramentas por grupo/canal são aplicadas além da política global/do agente (negação ainda vence).
• Alguns canais usam aninhamento diferente para salas/canais (por exemplo, Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

​

Listas de permissões de grupos

1. Desativar todas as respostas em grupos

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

2. Permitir apenas grupos específicos (WhatsApp)

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

3. Permitir todos os grupos, mas exigir menção (explícito)

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

4. Apenas o proprietário pode acionar em grupos (WhatsApp)

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

​

Ativação (apenas proprietário)

• /activation mention
• /activation always

​

Campos de contexto

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

​

Especificidades do iMessage

• Prefira chat_id:<id> ao rotear ou criar listas de permissões.
• Listar chats: imsg chats --limit 20.
• Respostas em grupo sempre retornam ao mesmo chat_id.

​

Especificidades do WhatsApp