Grupos

OpenClaw trata los chats grupales de forma coherente en todas las superficies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

Introducción para principiantes (2 minutos)

OpenClaw "vive" en tus propias cuentas de mensajería. No hay un usuario de bot de WhatsApp separado. 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 salvo que desactives explícitamente la barrera de menciones.
• Las respuestas finales normales en grupos/canales son privadas de forma predeterminada. La salida visible en la sala usa la herramienta message.

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

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

groupPolicy? disabled -> dropgroupPolicy? allowlist -> group allowed? no -> droprequireMention? yes -> mentioned? no -> store for context onlyotherwise -> reply

Respuestas visibles

Para salas de grupos/canales, OpenClaw usa de forma predeterminada messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix escribe este valor predeterminado en las configuraciones de canales configurados que lo omiten. Esto significa que el agente aún procesa el turno y puede actualizar el estado de memoria/sesión, pero su respuesta final normal no se publica automáticamente en la sala. Para hablar de forma visible, el agente usa message(action=send).

Este valor predeterminado depende de un modelo/runtime que invoque herramientas de forma fiable. Si los registros muestran texto del asistente pero didSendViaMessagingTool: false, el modelo respondió en privado en lugar de llamar a la herramienta de mensajes. Eso no es un fallo de envío de Discord/Slack/Telegram. Usa un modelo fiable en llamadas a herramientas para sesiones de grupos/canales, o establece messages.groupChat.visibleReplies: "automatic" para restaurar las respuestas finales visibles heredadas.

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

Para chats directos y cualquier otro turno de origen, usa messages.visibleReplies: "message_tool" para aplicar globalmente el mismo comportamiento de respuesta visible solo mediante herramienta. Los arneses también pueden elegir esto como su valor predeterminado no establecido; el arnés de Codex hace esto para chats directos en modo Codex. messages.groupChat.visibleReplies sigue siendo la anulación más específica para salas de grupos/canales.

Esto reemplaza el patrón antiguo de obligar al modelo a responder NO_REPLY para la mayoría de los turnos en modo de observación. En el modo solo herramienta, no hacer nada visible simplemente significa no llamar a la herramienta de mensajes.

Los indicadores de escritura se siguen enviando mientras el agente trabaja en modo solo herramienta. El modo de escritura grupal predeterminado se actualiza de "message" a "instant" para estos turnos porque puede que nunca haya texto normal de mensaje del asistente antes de que el agente decida si llamar a la herramienta de mensajes. La configuración explícita del modo de escritura sigue teniendo prioridad.

Para restaurar las respuestas finales automáticas heredadas para salas de grupos/canales:

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

El Gateway recarga en caliente la configuración de messages después de guardar el archivo. Reinicia solo cuando la observación de archivos o la recarga de configuración estén desactivadas en el despliegue.

Para exigir que la salida visible pase por la herramienta de mensajes para cada chat de origen:

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

Los comandos slash nativos (Discord, Telegram y otras superficies con soporte nativo de comandos) omiten visibleReplies: "message_tool" y siempre responden de forma visible para que la interfaz de comandos nativa del canal reciba la respuesta que espera. Esto solo se aplica a turnos de comandos nativos validados; los comandos /... escritos como texto y los turnos de chat ordinarios siguen el valor predeterminado grupal configurado.

Visibilidad del contexto y listas de permitidos

Hay dos controles diferentes implicados en la seguridad de grupos:

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

De forma predeterminada, OpenClaw prioriza el comportamiento normal de chat y mantiene el contexto mayormente como se recibió. Esto significa que las listas de permitidos deciden principalmente quién puede activar acciones, no una frontera universal de censura para cada fragmento citado o histórico.

Si quieres...

Para listas de remitentes permitidos reutilizables, consulta Grupos de acceso.

Claves de sesión

• Las sesiones grupales usan claves de sesión agent:<agentId>:<channel>:group:<id> (las salas/canales usan agent:<agentId>:<channel>:channel:<id>).
• Los temas de foros de Telegram agregan :topic:<threadId> al identificador 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 para sesiones grupales.

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

Sí, esto funciona bien si tu tráfico "personal" son mensajes directos y tu tráfico "público" son grupos.

Motivo: en modo de agente único, los mensajes directos 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 aislamiento con mode: "non-main", esas sesiones grupales se ejecutan en el backend de aislamiento configurado, mientras que tu sesión principal de mensajes directos permanece en el host. Docker es el backend predeterminado si no eliges uno.

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

• Mensajes directos: herramientas completas (host)
• Grupos: aislamiento + 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
• Depurar por qué una herramienta está bloqueada: Aislamiento frente a política de herramientas frente a elevado
• Detalles de montajes vinculados: Aislamiento

Etiquetas de visualización

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

Política de grupos

Controla cómo se manejan los mensajes de grupos/salas 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 (orden de evaluación para mensajes de grupo):

Control por menciones (predeterminado)

Los mensajes de grupo requieren una mención salvo que se sobrescriba por grupo. Los valores predeterminados viven 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 },        "[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,        },      },    ],  },}

Restricciones de herramientas por grupo/canal (opcional)

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

• tools: permite/deniega herramientas para todo el grupo.
• toolsBySender: sobrescrituras por remitente dentro del grupo. Usa 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 ids de canal canónicos de OpenClaw; alias como teams se normalizan a msteams. Las claves heredadas sin prefijo siguen aceptándose y se comparan solo como id:.

Orden de resolución (gana lo 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 grupo

Cuando se configura channels.whatsapp.groups, channels.telegram.groups o channels.imessage.groups, las claves actúan como una lista de permitidos de grupo. Usa "*" para permitir todos los grupos sin dejar de definir el comportamiento predeterminado de menciones.

Intenciones comunes (copiar/pegar):

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

Activación (solo propietario)

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

• /activation mention
• /activation always

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

Campos de contexto

Las cargas útiles entrantes de grupo establecen:

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

El prompt de sistema del agente incluye una introducción de grupo en el primer turno de una nueva sesión de grupo. Recuerda al modelo que responda como una persona, evite tablas de Markdown, minimice las líneas vacías y siga el espaciado normal de chat, y evite escribir secuencias literales \n. Los nombres de grupo y etiquetas de participantes procedentes del canal se representan como metadatos no confiables delimitados, no como instrucciones de sistema en línea.

Detalles de iMessage

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

Prompts de sistema de WhatsApp

Consulta WhatsApp para las reglas canónicas del prompt de sistema de WhatsApp, incluida la resolución de prompts de grupo y directos, el comportamiento de comodines y la semántica de sobrescritura de cuenta.

Detalles de WhatsApp

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

Relacionado

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