Grupos

OpenClaw aplica las mismas reglas de grupo en todos los canales que admiten grupos, incluidos Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp y Zalo.

Para salas siempre activas que deban proporcionar contexto silencioso, salvo que el agente envíe explícitamente un mensaje visible, consulte Eventos de sala ambientales.

Introducción para principiantes (2 minutos)

OpenClaw «vive» en sus propias cuentas de mensajería. No hay un usuario bot de WhatsApp independiente: si usted está en un grupo, OpenClaw puede ver ese grupo y responder allí.

Comportamiento predeterminado:

• Los grupos están restringidos (groupPolicy: "allowlist"); los remitentes de los grupos se bloquean hasta que se incluyan en la lista de permitidos.
• Las respuestas requieren una mención, salvo que se desactive el control por menciones para un grupo.
• El texto de la respuesta final se publica automáticamente en la sala (visibleReplies: "automatic").

En otras palabras: los remitentes incluidos en la lista de permitidos pueden activar OpenClaw mencionándolo.

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

¿groupPolicy? disabled -> descartar¿groupPolicy? allowlist -> ¿grupo permitido? no -> descartar¿requireMention? sí -> ¿se mencionó? no -> almacenar solo como contextomención/respuesta/comando/mensaje directo -> solicitud del usuarioconversación de grupo siempre activa -> solicitud del usuario o evento de sala cuando esté configurado

Respuestas visibles

Para las solicitudes normales de grupos/canales, OpenClaw utiliza de forma predeterminada messages.groupChat.visibleReplies: "automatic": el texto final del asistente se publica en la sala como respuesta visible.

Utilice messages.groupChat.visibleReplies: "message_tool" cuando una sala compartida deba permitir que el agente decida cuándo intervenir llamando a message(action=send). Esto funciona mejor con modelos que utilizan herramientas de forma fiable (por ejemplo, GPT-5.6 Sol). Si el modelo no utiliza la herramienta y devuelve un texto final sustancial, OpenClaw mantiene ese texto en privado en lugar de publicarlo en la sala.

Utilice "automatic" para modelos o entornos de ejecución que no sigan de forma fiable la entrega exclusiva mediante herramientas: los textos finales normales se publican directamente en la sala y el agente aún puede llamar a message(action=send) para enviar archivos, imágenes u otros adjuntos que no puedan incluirse con el texto final.

Si la herramienta de mensajes no está disponible conforme a la política de herramientas activa, OpenClaw recurre a respuestas visibles automáticas en lugar de suprimir la respuesta silenciosamente. openclaw doctor advierte de esta incompatibilidad.

Para los chats directos y cualquier otro evento de origen, messages.visibleReplies: "message_tool" aplica globalmente el mismo comportamiento exclusivo mediante herramientas; messages.groupChat.visibleReplies sigue siendo la anulación más específica para salas de grupos/canales. Los turnos directos internos de WebChat utilizan de forma predeterminada la entrega automática de la respuesta final para que Pi y Codex reciban el mismo contrato de respuesta visible.

El modo exclusivo mediante herramientas sustituye el patrón anterior de obligar al modelo a responder NO_REPLY en la mayoría de los turnos en modo observador. En el modo exclusivo mediante herramientas, el mensaje del sistema no define un contrato NO_REPLY; no mostrar nada visible significa simplemente no llamar a la herramienta de mensajes.

Las vinculaciones de conversaciones propiedad de Plugins son la excepción. Cuando un Plugin vincula un hilo y reclama el turno entrante, la respuesta devuelta por el Plugin es la respuesta visible de la vinculación; no necesita message(action=send). Esa respuesta es una salida del entorno de ejecución del Plugin, no texto final privado del modelo.

Los indicadores de escritura se siguen enviando para las solicitudes directas de grupo. Los eventos ambientales de salas siempre activas, cuando están habilitados, permanecen estrictos y silenciosos salvo que el agente llame a la herramienta de mensajes.

De forma predeterminada, las sesiones suprimen los resúmenes detallados de herramientas/progreso. Utilice /verbose on (o /verbose full) para mostrarlos en la sesión actual durante la depuración y /verbose off para volver al comportamiento de mostrar únicamente la respuesta final. El estado detallado se configura por sesión y funciona igual en chats directos, grupos, canales y temas de foros.

Para enviar conversaciones de grupos siempre activos sin menciones como contexto silencioso de la sala en lugar de solicitudes del usuario, utilice Eventos de sala ambientales:

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

El valor predeterminado es unmentionedInbound: "user_request". Los mensajes con menciones, los comandos, las solicitudes de interrupción y los mensajes directos siguen siendo solicitudes del usuario.

Para exigir que la salida visible de las solicitudes de grupos/canales pase por la herramienta de mensajes:

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

Para exigirlo en todos los chats de origen:

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

El Gateway detecta los cambios de configuración de messages sin reiniciarse una vez guardado el archivo. Reinicie únicamente cuando la recarga de configuración esté deshabilitada (gateway.reload.mode: "off").

Los turnos de comandos omiten visibleReplies: "message_tool" y siempre responden de forma visible: tanto los comandos de barra nativos (Discord, Telegram y otras superficies compatibles con comandos nativos) como los comandos de texto /... autorizados publican su respuesta en el chat de origen. Los turnos de texto /... no autorizados en grupos siguen siendo exclusivos de la herramienta de mensajes; los turnos de chat normales siguen el valor predeterminado configurado.

Visibilidad del contexto y listas de permitidos

La seguridad de los grupos implica dos controles diferentes:

• Autorización de activación: quién puede activar el agente (groupPolicy, groups, groupAllowFrom, listas de permitidos específicas de cada canal).
• Visibilidad del contexto: qué contexto complementario se inyecta en el modelo (texto de respuestas/citas, historial del hilo, metadatos reenviados).

De forma predeterminada, OpenClaw conserva el contexto tal como se recibe: las listas de permitidos determinan quién puede activar acciones, no qué fragmentos citados o históricos ve el modelo. Para filtrar también el contexto complementario, establezca contextVisibility:

Establézcalo por canal (channels.<channel>.contextVisibility), por cuenta (channels.<channel>.accounts.<accountId>.contextVisibility) o globalmente (channels.defaults.contextVisibility). Los canales que obtienen contexto complementario (Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp) aplican la política al crear el contexto entrante; las combinaciones de políticas desconocidas se cierran de forma segura y omiten el contexto.

Si desea...

Para obtener información sobre las listas de remitentes permitidos reutilizables, consulte Grupos de acceso.

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 foros 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 sesiones por remitente si se configura session.dmScope).
• Los Heartbeats se ejecutan en la sesión de heartbeat configurada (valor predeterminado: la sesión principal del agente); las sesiones de grupo no ejecutan sus propios heartbeats.

Patrón: mensajes directos personales + grupos públicos (un solo agente)

Sí: esto funciona bien si el tráfico «personal» son mensajes directos y el tráfico «público» son grupos.

Motivo: en el modo de un solo agente, los mensajes directos suelen llegar a 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 habilita el aislamiento con mode: "non-main", esas sesiones de grupo se ejecutan en el backend de aislamiento configurado mientras que la sesión principal de mensajes directos permanece en el host. Docker es el backend predeterminado si no se elige otro.

Esto proporciona un único «cerebro» de agente (espacio de trabajo + memoria compartidos), pero dos modalidades de ejecución:

• Mensajes directos: herramientas completas (host)
• Grupos: entorno aislado + herramientas restringidas

{  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:

• Claves de configuración y valores predeterminados: Configuración del Gateway
• Depuración del motivo por el que se bloquea una herramienta: Entorno aislado frente a política de herramientas frente a privilegios elevados
• Detalles sobre los montajes enlazados: Aislamiento

Etiquetas de visualización

• Las etiquetas de la interfaz de usuario utilizan displayName cuando está disponible, con el formato <channel>:<token>.
• #room está reservado para salas/canales; los chats de grupo utilizan g-<slug> (minúsculas, espacios -> -, conservar #@+._-). Los ids opacos muy largos se acortan en un token estable en lugar de exponer ids completos de rutas en la interfaz de usuario.

Política de grupos

Controle cómo se gestionan los mensajes de grupos/salas en cada canal:

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // id numérico de usuario de Telegram (la configuración resuelve @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 (orden de evaluación de los mensajes de grupo):

Requisito de mención (predeterminado)

Los mensajes de grupo requieren una mención, salvo que se sustituya este comportamiento para un grupo concreto. Los valores predeterminados se encuentran por subsistema en *.groups."*".

Responder a un mensaje del bot cuenta como una mención implícita cuando el canal proporciona metadatos de respuesta; citar un mensaje del bot también puede contar en los canales que proporcionan metadatos de citas. Casos integrados actuales: Discord, Microsoft Teams, QQBot, Slack, Telegram, WhatsApp y Zalo personal.

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

Limitar el alcance de los patrones de mención configurados

Los mentionPatterns configurados son activadores alternativos mediante expresiones regulares. Úselos cuando la plataforma no proporcione una mención nativa al bot o cuando se quiera que texto sin formato como openclaw: cuente como una mención. Las menciones nativas de la plataforma son independientes: cuando Discord, Slack, Telegram, Matrix, Signal u otro canal puede demostrar que el mensaje mencionó explícitamente al bot, esa mención nativa sigue activándolo aunque se denieguen los patrones de expresiones regulares configurados.

De forma predeterminada, los patrones de mención configurados se aplican en todos los lugares donde el canal transmite datos del proveedor y de la conversación a la detección de menciones. Para evitar que los patrones amplios activen al agente en todos los grupos, limite su alcance por canal con channels.<channel>.mentionPatterns.

Use mode: "deny" cuando los patrones de mención mediante expresiones regulares deban estar desactivados de forma predeterminada para un canal y, después, actívelos en salas concretas con allowIn:

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

Use el valor predeterminado mode: "allow" (u omita mode) cuando los patrones de mención mediante expresiones regulares deban aplicarse de forma general y, después, desactívelos en salas con mucho tráfico mediante denyIn:

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

Resolución de políticas:

Política de alcance de expresiones regulares admitida actualmente:

Las configuraciones de canal a nivel de cuenta pueden establecer la misma política en channels.<channel>.accounts.<accountId>.mentionPatterns cuando ese canal admite varias cuentas. La política de la cuenta prevalece sobre la política de nivel superior del canal para esa cuenta.

Restricciones de herramientas por grupo/canal (opcional)

Algunas configuraciones de canales permiten restringir las herramientas disponibles dentro de un grupo/sala/canal concreto.

• tools: permite/deniega herramientas para todo el grupo (allow, alsoAllow, deny; la denegación prevalece).
• toolsBySender: sustituciones por remitente dentro del grupo. Use prefijos de clave explícitos: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> y el comodín "*". Los ids de canal usan los ids de canal canónicos de OpenClaw; los alias como teams se normalizan como msteams. Las claves heredadas sin prefijo todavía se aceptan, solo se comparan como id: y generan una advertencia de obsolescencia en el registro.

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

Ejemplo (Telegram):

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

Listas de permitidos de grupos

Cuando se configura channels.whatsapp.groups, channels.telegram.groups o channels.imessage.groups, las claves actúan como una lista de permitidos de grupos. Utilice "*" para permitir todos los grupos y seguir estableciendo el comportamiento predeterminado de las menciones.

Configuraciones habituales (copiar y pegar):

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

Activación (solo propietarios)

Los propietarios de grupos pueden alternar la activación de cada grupo mediante un mensaje independiente:

• /activation mention
• /activation always

/activation es un comando central restringido a propietarios y solo se aplica en chats de grupo. Se considera propietario al remitente que coincide con commands.ownerAllowFrom; las listas allowFrom del canal solo controlan el acceso ordinario al canal y a los comandos. El modo almacenado prevalece sobre el valor requireMention de ese grupo en los canales que lo consultan (Google Chat, QQBot, Telegram y WhatsApp), y la introducción del prompt del sistema del grupo refleja el modo activo en todas partes.

Campos de contexto

Las cargas útiles entrantes de grupos establecen:

• ChatType=group
• GroupSubject (si se conoce)
• GroupMembers (si se conoce)
• WasMentioned (resultado del control por mención)
• Los temas de los foros de Telegram también incluyen MessageThreadId y IsForum.

El prompt del sistema del agente incluye una introducción de grupo en el primer turno de una nueva sesión de grupo (y después de que cambie /activation). Recuerda al modelo que debe responder como una persona, minimizar las líneas vacías, seguir el espaciado habitual de los chats y evitar escribir secuencias literales \n. En los grupos que no son de Telegram también se desaconsejan las tablas Markdown; las directrices de texto enriquecido de Telegram proceden del prompt del canal de Telegram. Los nombres de grupos y las etiquetas de participantes procedentes del canal se representan como metadatos no fiables en bloques delimitados, no como instrucciones del sistema insertadas en línea.

Particularidades de iMessage

• Se recomienda chat_id:<id> para el enrutamiento o las listas de permitidos.
• Enumerar chats: imsg chats --limit 20.
• Las respuestas de grupo siempre se devuelven al mismo chat_id.

Prompts del sistema de WhatsApp

Consulte WhatsApp para conocer las reglas canónicas de los prompts del sistema de WhatsApp, incluida la resolución de prompts directos y de grupo, el comportamiento de los comodines y la semántica de las sustituciones específicas de cuenta.

Particularidades de WhatsApp

Consulte Mensajes de grupo para conocer el comportamiento exclusivo de WhatsApp (inyección del historial y detalles sobre la gestión de menciones).

Contenido relacionado

• Grupos de difusión
• Enrutamiento de canales
• Mensajes de grupo
• Emparejamiento