Grupos

OpenClaw maneja los chats grupales de forma consistente en todas las plataformas: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Introducción para principiantes (2 minutos)

OpenClaw “vive” en tus propias cuentas de mensajería. No existe un usuario bot de WhatsApp separado. Si tú estás en un grupo, OpenClaw puede ver ese grupo y responder ahí.

Comportamiento por defecto:

  • Los grupos están restringidos (groupPolicy: "allowlist").
  • Las respuestas requieren una mención a menos que desactives explícitamente la comprobación de mención.

En resumen: los remitentes en la lista permitida pueden activar OpenClaw mencionándolo.

TL;DR

  • Acceso a DMs se controla con *.allowFrom.
  • Acceso a grupos se controla con *.groupPolicy + listas permitidas (*.groups, *.groupAllowFrom).
  • Activación de respuestas se controla con la comprobación de mención (requireMention, /activation).

Flujo rápido (qué le pasa a un mensaje de grupo):

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

Group message flow

Si quieres…

ObjetivoQué configurar
Permitir todos los grupos pero solo responder con @mencióngroups: { "*": { requireMention: true } }
Desactivar todas las respuestas en gruposgroupPolicy: "disabled"
Solo grupos específicosgroups: { "<group-id>": { ... } } (sin clave "*")
Solo tú puedes activar en gruposgroupPolicy: "allowlist", groupAllowFrom: ["+1555..."]

Claves de sesión

  • Las sesiones de grupo usan claves agent:<agentId>:<channel>:group:<id> (las salas/canales usan agent:<agentId>:<channel>:channel:<id>).
  • Los temas de foro de Telegram añaden :topic:<threadId> al id del grupo para que cada tema tenga su propia sesión.
  • Los chats directos usan la sesión principal (o por remitente si está configurado).
  • Los heartbeats se omiten en sesiones de grupo.

Patrón: DMs personales + grupos públicos (agente único)

Sí — esto funciona bien si tu tráfico “personal” son DMs y tu tráfico “público” son grupos.

Por qué: en modo de agente único, los DMs normalmente llegan a la clave de sesión principal (agent:main:main), mientras que los grupos siempre usan claves de sesión no principales (agent:main:<channel>:group:<id>). Si activas el sandboxing con mode: "non-main", esas sesiones de grupo se ejecutan en Docker mientras tu sesión principal de DM permanece en el host.

Esto te da un “cerebro” de agente (workspace + memoria compartidos), pero dos posturas de ejecución:

  • DMs: herramientas completas (host)
  • Grupos: sandbox + herramientas restringidas (Docker)

Si necesitas workspaces/personas verdaderamente separados (“personal” y “público” nunca deben mezclarse), usa un segundo agente + bindings. Consulta Enrutamiento Multi-Agente.

Ejemplo (DMs en host, grupos en sandbox + solo herramientas de mensajería):

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

¿Quieres que “los grupos solo puedan ver la carpeta X” en lugar de “sin acceso al host”? Mantén workspaceAccess: "none" y monta solo las rutas permitidas en el sandbox:

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

Relacionado:

Etiquetas de visualización

  • Las etiquetas de UI usan displayName cuando está disponible, formateado como <channel>:<token>.
  • #room está reservado para salas/canales; los chats grupales usan g-<slug> (minúsculas, espacios → -, se mantienen #@+._-).

Política de grupo

Controla cómo se manejan los mensajes de grupo/sala 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íticaComportamiento
"open"Los grupos omiten las listas permitidas; la comprobación de mención sigue aplicándose.
"disabled"Bloquea todos los mensajes de grupo por completo.
"allowlist"Solo permite grupos/salas que coincidan con la lista permitida configurada.

Notas:

  • groupPolicy es independiente de la comprobación de mención (que requiere @menciones).
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: usan groupAllowFrom (respaldo: allowFrom explícito).
  • Las aprobaciones de emparejamiento de DM (entradas *-allowFrom del almacén) solo aplican al acceso por DM; la autorización del remitente en grupos permanece explícita en las listas permitidas del grupo.
  • Discord: la lista permitida usa channels.discord.guilds.<id>.channels.
  • Slack: la lista permitida usa channels.slack.channels.
  • Matrix: la lista permitida usa channels.matrix.groups (IDs de sala, alias o nombres). Usa channels.matrix.groupAllowFrom para restringir remitentes; también se admiten listas permitidas por sala con users.
  • Los DMs de grupo se controlan por separado (channels.discord.dm.*, channels.slack.dm.*).
  • La lista permitida de Telegram puede coincidir con IDs de usuario ("123456789", "telegram:123456789", "tg:123456789") o nombres de usuario ("@alice" o "alice"); los prefijos no distinguen mayúsculas.
  • El valor por defecto es groupPolicy: "allowlist"; si tu lista permitida de grupo está vacía, los mensajes de grupo se bloquean.
  • Seguridad en tiempo de ejecución: cuando un bloque de proveedor está completamente ausente (channels.<provider> no existe), la política de grupo recurre a un modo fail-closed (normalmente allowlist) en lugar de heredar channels.defaults.groupPolicy.

Modelo mental rápido (orden de evaluación para mensajes de grupo):

  1. groupPolicy (open/disabled/allowlist)
  2. Listas permitidas de grupo (*.groups, *.groupAllowFrom, lista permitida específica del canal)
  3. Comprobación de mención (requireMention, /activation)

Comprobación de mención (por defecto)

Los mensajes de grupo requieren mención a menos que se anule por grupo. Los valores por defecto se establecen por subsistema en *.groups."*".

Responder a un mensaje del bot cuenta como mención implícita (cuando el canal soporta metadatos de respuesta). Esto aplica a Telegram, WhatsApp, Slack, Discord y 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 son expresiones regulares que no distinguen mayúsculas y minúsculas.
  • Las plataformas que proporcionan menciones explícitas siguen funcionando; los patrones son un respaldo.
  • Anulación por agente: agents.list[].groupChat.mentionPatterns (útil cuando varios agentes comparten un grupo).
  • La comprobación de mención solo se aplica cuando la detección de mención es posible (menciones nativas o mentionPatterns configurados).
  • Los valores por defecto de Discord están en channels.discord.guilds."*" (se pueden anular por servidor/canal).
  • El contexto de historial de grupo se envuelve uniformemente entre canales y es solo pendiente (mensajes omitidos por la comprobación de mención); usa messages.groupChat.historyLimit para el valor global por defecto y channels.<channel>.historyLimit (o channels.<channel>.accounts.*.historyLimit) para anulaciones. Establece 0 para desactivar.

Restricciones de herramientas por grupo/canal (opcional)

Algunas configuraciones de canal permiten restringir qué herramientas están disponibles dentro de un grupo/sala/canal específico.

  • tools: permite/deniega herramientas para todo el grupo.
  • toolsBySender: anulaciones por remitente dentro del grupo. Usa prefijos de clave explícitos: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, y comodín "*". Las claves legacy sin prefijo siguen aceptándose y se emparejan solo como id:.

Orden de resolución (el más específico gana):

  1. toolsBySender del grupo/canal que coincida
  2. tools del grupo/canal
  3. toolsBySender por defecto ("*") que coincida
  4. tools por defecto ("*")

Ejemplo (Telegram):

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

Notas:

  • Las restricciones de herramientas de grupo/canal se aplican además de la política de herramientas global/agente (deny siempre gana).
  • Algunos canales usan anidación diferente para salas/canales (p. ej., Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Listas permitidas de grupo

Cuando se configura channels.whatsapp.groups, channels.telegram.groups o channels.imessage.groups, las claves actúan como lista permitida de grupo. Usa "*" para permitir todos los grupos mientras configuras el comportamiento de mención por defecto.

Patrones comunes (copiar/pegar):

  1. Desactivar todas las respuestas en grupos
{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}
  1. Permitir solo grupos específicos (WhatsApp)
{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}
  1. Permitir todos los grupos pero requerir mención (explícito)
{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  1. Solo el propietario puede activar en grupos (WhatsApp)
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Activación (solo propietario)

Los propietarios de grupo pueden alternar la activación por grupo:

  • /activation mention
  • /activation always

El propietario se determina por channels.whatsapp.allowFrom (o el E.164 propio del bot cuando no está configurado). Envía el comando como un mensaje independiente. Otras plataformas actualmente ignoran /activation.

Campos de contexto

Los payloads entrantes de grupo establecen:

  • ChatType=group
  • GroupSubject (si se conoce)
  • GroupMembers (si se conoce)
  • WasMentioned (resultado de la comprobación de mención)
  • Los temas de foro de Telegram también incluyen MessageThreadId e IsForum.

El prompt del sistema del agente incluye una introducción de grupo en el primer turno de una nueva sesión de grupo. Le recuerda al modelo que responda como un humano, evite tablas Markdown y evite escribir secuencias literales \n.

Especificaciones de iMessage

  • Prefiere chat_id:<id> al enrutar o configurar listas permitidas.
  • Listar chats: imsg chats --limit 20.
  • Las respuestas de grupo siempre van al mismo chat_id.

Especificaciones de WhatsApp

Consulta Mensajes de grupo para el comportamiento específico de WhatsApp (inyección de historial, detalles del manejo de menciones).

arrow_back
Anterior
Group Messages
Siguiente
Broadcast Groups
arrow_forward