Configura grupos en OpenClaw: Guía de control y acceso

Introducción para principiantes (2 minutos)

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

Comportamiento predeterminado:

Los grupos están restringidos (groupPolicy: "allowlist").
Las respuestas requieren una mención a menos que desactives explícitamente el bloqueo por mención.

Traducción: los remitentes en la lista de permitidos pueden activar OpenClaw mencionándolo.

TL;DR

El acceso a DM se controla mediante *.allowFrom.

El acceso a grupos se controla mediante *.groupPolicy + listas de permitidos (*.groups, *.groupAllowFrom).

La activación de respuestas se controla mediante el bloqueo por mención (requireMention, /activation).

Flujo rápido (qué sucede con un mensaje de grupo):

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

Visibilidad de contexto y listas de permitidos

Existen dos controles diferentes involucrados en la seguridad de los grupos:

Autorización de activación: quién puede activar el agente (groupPolicy, groups, groupAllowFrom, listas de permitidos específicas por canal).
Visibilidad de contexto: qué contexto suplementario se inyecta en el modelo (texto de respuesta, citas, historial de hilos, metadatos reenviados).

De forma predeterminada, OpenClaw prioriza el comportamiento normal del chat y mantiene el contexto mayormente tal como se recibe. Esto significa que las listas de permitidos deciden principalmente quién puede activar acciones, no actúan como un límite de redacción universal para cada fragmento citado o histórico.

El comportamiento actual es específico del canal:

Algunos canales ya aplican filtrado basado en el remitente para el contexto suplementario en rutas específicas (por ejemplo, alimentación de hilos en Slack, búsquedas de respuesta/hilo en Matrix).
Otros canales aún pasan el contexto de cita/respuesta/reenvío tal como se recibe.

Dirección de endurecimiento (planificada):

contextVisibility: "all" (predeterminado) mantiene el comportamiento actual de “tal como se recibe”.
contextVisibility: "allowlist" filtra el contexto suplementario para permitir solo a los remitentes en la lista.
contextVisibility: "allowlist_quote" es igual a allowlist más una excepción explícita de cita/respuesta.

Hasta que este modelo de endurecimiento se implemente de manera consistente en todos los canales, espera diferencias según la superficie.

Group message flow

Si quieres…

Objetivo	Qué configurar
Permitir todos los grupos pero solo responder con @menciones	`groups: { "*": { requireMention: true } }`
Desactivar todas las respuestas en grupos	`groupPolicy: "disabled"`
Solo grupos específicos	`groups: { "<group-id>": { ... } }` (sin la clave `"*"` )
Solo tú puedes activar en grupos	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Claves de sesión

Las sesiones de grupo utilizan claves de sesión agent:<agentId>:<channel>:group:<id> (las salas/canales utilizan 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 utilizan la sesión principal (o por remitente si está configurado).
Los latidos (heartbeats) se omiten para las 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 el modo de agente único, los DMs normalmente aterrizan en la clave de sesión principal (agent:main:main), mientras que los grupos siempre utilizan claves de sesión no principales (agent:main:<channel>:group:<id>). Si habilitas el sandboxing con mode: "non-main", esas sesiones de grupo se ejecutan en el backend de sandbox configurado mientras tu sesión principal de DM permanece en el host. Docker es el backend predeterminado si no eliges uno.

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

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

Si necesitas espacios de trabajo/personas verdaderamente separados (lo “personal” y lo “público” nunca deben mezclarse), usa un segundo agente + enlaces. Consulta Multi-Agent Routing.

Ejemplo (DMs en host, grupos en sandbox + herramientas solo 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:

Claves de configuración y valores predeterminados: Gateway configuration
Depurar por qué una herramienta está bloqueada: Sandbox vs Tool Policy vs Elevated
Detalles de montajes de enlace: Sandboxing

AI Setup Assistant

Etiquetas de visualización

Las etiquetas de interfaz de usuario utilizan displayName cuando está disponible, formateadas como <channel>:<token>.

El símbolo #room está reservado para salas o canales.
Los chats grupales utilizan g-<slug> (en minúsculas, reemplazando espacios por -, manteniendo los caracteres #@+._-).

Política de grupos

Puedes controlar cómo se gestionan los mensajes de grupos o salas para cada canal específico configurando las reglas de acceso en tu OpenClaw Gateway.

{
  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: ["user@org.com"],
    },
    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 },
      },
    },
  },
}

Política	Comportamiento
`"open"`	Los grupos omiten las listas de permitidos; el filtrado por menciones sigue activo.
`"disabled"`	Bloquea todos los mensajes de grupo por completo.
`"allowlist"`	Solo permite grupos o salas que coincidan con la lista configurada.

Notas importantes:

groupPolicy es independiente del filtrado por menciones (que requiere @menciones).
Para WhatsApp, Telegram, Signal, iMessage, Microsoft Teams y Zalo: utiliza groupAllowFrom (alternativa: allowFrom explícito).
Las aprobaciones de emparejamiento de DM (entradas de almacenamiento *-allowFrom) solo aplican al acceso por DM; la autorización del remitente en grupos permanece explícita para las listas de permitidos de grupos.
Discord: la lista de permitidos utiliza channels.discord.guilds.<id>.channels.
Slack: la lista de permitidos utiliza channels.slack.channels.
Matrix: la lista de permitidos utiliza channels.matrix.groups. Es preferible usar IDs de sala o alias; la búsqueda de nombres de salas unidas es de mejor esfuerzo y los nombres no resueltos se ignoran en tiempo de ejecución. Usa channels.matrix.groupAllowFrom para restringir remitentes; también se admiten listas de permitidos de users por sala.
Los DM grupales se controlan por separado (channels.discord.dm.*, channels.slack.dm.*).
La lista de permitidos de Telegram puede coincidir con IDs de usuario ("123456789", "telegram:123456789", "tg:123456789") o nombres de usuario ("@alice" o "alice"); los prefijos no distinguen entre mayúsculas y minúsculas.
El valor predeterminado es groupPolicy: "allowlist"; si tu lista de permitidos de grupo está vacía, los mensajes de grupo se bloquearán.
Seguridad en tiempo de ejecución: cuando falta por completo el bloque de un proveedor (channels.<provider> ausente), la política de grupo vuelve a un modo de fallo cerrado (típicamente allowlist) en lugar de heredar channels.defaults.groupPolicy.

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

groupPolicy (open/disabled/allowlist)
Listas de permitidos de grupo (*.groups, *.groupAllowFrom, lista de permitidos específica del canal)
Filtrado por menciones (requireMention, /activation)

AI Setup Assistant

Control de menciones (predeterminado)

Los mensajes en grupos requieren una mención a menos que se modifique la configuración por grupo. Los valores predeterminados se definen por subsistema bajo *.groups."*".

Responder a un mensaje del bot cuenta como una mención implícita cuando el canal admite metadatos de respuesta. Citar un mensaje del bot también puede contar como una mención implícita en canales que exponen metadatos de cita. Los casos integrados actuales incluyen Telegram, WhatsApp, Slack, Discord, Microsoft Teams y ZaloUser.

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

Notas:

Los mentionPatterns son patrones de regex seguros que no distinguen entre mayúsculas y minúsculas; los patrones no válidos y las formas de repetición anidada inseguras se ignoran.
Las interfaces que proporcionan menciones explícitas siguen funcionando; los patrones actúan como respaldo.
Sustitución por agente: agents.list[].groupChat.mentionPatterns (útil cuando varios agentes comparten un grupo).
El control de menciones solo se aplica cuando la detección de menciones es posible (se configuran menciones nativas o mentionPatterns).
Los valores predeterminados de Discord se encuentran en channels.discord.guilds."*" (se pueden anular por servidor o canal).
El contexto del historial del grupo se envuelve de manera uniforme en todos los canales y es solo pendiente (los mensajes se omiten debido al control de menciones); usa messages.groupChat.historyLimit para el valor predeterminado global y channels.<channel>.historyLimit (o channels.<channel>.accounts.*.historyLimit) para las sustituciones. 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 o canal específico.

tools: permite o deniega herramientas para todo el grupo.
toolsBySender: sustituciones por remitente dentro del grupo. Usa prefijos de clave explícitos: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> y el comodín "*". Las claves heredadas sin prefijo todavía se aceptan y se comparan solo como id:.

Orden de resolución (gana la más específica):

Coincidencia de toolsBySender en grupo/canal.
tools de grupo/canal.
Coincidencia de toolsBySender predeterminada ("*").
tools predeterminadas ("*").

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 (la denegación siempre prevalece).
Algunos canales utilizan un anidamiento diferente para salas/canales (por ejemplo, Discord guilds.*.channels.*, Slack channels.*, Microsoft Teams teams.*.channels.*).

Listas de permitidos para grupos

Cuando configuras channels.whatsapp.groups, channels.telegram.groups o channels.imessage.groups, las claves funcionan como una lista de permitidos para grupos. Usa "*" para permitir todos los grupos mientras mantienes el comportamiento predeterminado de mención.

Es común confundirse, pero la aprobación de emparejamiento de DM no es lo mismo que la autorización de grupo. Para los canales que admiten el emparejamiento de DM, el almacén de emparejamiento desbloquea solo los DM. Los comandos de grupo aún requieren una autorización explícita del remitente del grupo desde las listas de permitidos de configuración, como groupAllowFrom o el respaldo de configuración documentado para ese canal. OpenClaw gestiona estas listas de permitidos para grupos de manera eficiente.

Aquí tienes algunas intenciones comunes que puedes copiar y pegar:

Deshabilitar todas las respuestas en grupos

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

Permitir solo grupos específicos (WhatsApp)

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

Permitir todos los grupos pero requerir mención (explícito)

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

Solo el propietario puede activar comandos en grupos (WhatsApp)

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

Activación (solo para el propietario)

Los propietarios de grupos pueden alternar la activación por grupo usando los siguientes comandos:

/activation mention
/activation always

El propietario se determina mediante channels.whatsapp.allowFrom (o el E.164 propio del bot cuando no está configurado). Envía el comando como un mensaje independiente. Actualmente, otras superficies ignoran /activation.

Campos de contexto

Cuando trabajas con OpenClaw y gestionas los campos de contexto, el conjunto de datos de entrada entrantes se organiza de la siguiente manera:

ChatType=group
GroupSubject (si se conoce)
GroupMembers (si se conoce)
WasMentioned (resultado del filtrado de menciones)
Los temas de foros de Telegram también incluyen MessageThreadId e IsForum.

Notas específicas sobre canales:

BlueBubbles puede enriquecer opcionalmente a los participantes de grupos de macOS sin nombre desde la base de datos de contactos local antes de completar GroupMembers. Esta función está desactivada por defecto y solo se ejecuta después de que se completan los procesos normales de filtrado de grupos.

El prompt del sistema del agente incluye una introducción de grupo en el primer turno de una nueva sesión grupal. Esto le recuerda al modelo que debe responder como un humano, evitar tablas en formato Markdown, minimizar las líneas vacías, seguir el espaciado de chat normal y evitar escribir secuencias literales de \n.

Especificaciones de iMessage

Para manejar correctamente tus mensajes en iMessage, sigue estas pautas de enrutamiento y configuración:

Prefiere chat_id:<id> al enrutar o al incluir en listas de permitidos.
Para listar chats, utiliza el comando: imsg chats --limit 20.
Las respuestas a grupos siempre regresan al mismo chat_id.

imsg chats --limit 20

Especificaciones de WhatsApp

Si necesitas información detallada sobre el comportamiento exclusivo de WhatsApp, consulta la documentación sobre mensajes de grupo, donde encontrarás detalles sobre la inyección de historial y el manejo de menciones.

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.