Ir al contenido

Grupos

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

Para salas permanentes que deben proporcionar un contexto silencioso a menos que el agente envíe explícitamente un mensaje visible, consulte Eventos de sala ambiental.

Introducción para principiantes (2 minutos)

Sección titulada «Introducción para principiantes (2 minutos)»

OpenClaw “vive” en sus propias cuentas de mensajería. No hay un usuario de bot de WhatsApp separado. Si usted está 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 desactive explícitamente el filtrado de menciones.
  • Las respuestas visibles en grupos/canales utilizan la herramienta message de manera predeterminada.

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

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
mention/reply/command/DM -> user request
always-on group chatter -> user request, or room event when configured

Para solicitudes normales de grupos/canales, OpenClaw utiliza de forma predeterminada messages.groupChat.visibleReplies: "automatic". El texto final del asistente se publica a través de la ruta de respuesta visible heredada, a menos que configure la sala para usar solo la salida de la herramienta de mensaje.

Use messages.groupChat.visibleReplies: "message_tool" cuando una sala compartida debe permitir que el agente decida cuándo hablar llamando a message(action=send). Esto funciona mejor para salas grupales respaldadas por modelos de última generación confiables con herramientas, como GPT 5.5. Si el modelo omite esa herramienta y devuelve un texto final sustantivo, OpenClaw mantiene ese texto final como privado en lugar de publicarlo en la sala.

Use "automatic" para modelos más débiles o entornos de ejecución que no entienden de manera confiable la entrega solo a través de herramientas. En modo automático, el texto final del asistente es la ruta de respuesta fuente visible, por lo que un modelo que no pueda llamar consistentemente a message(action=send) aún puede responder con normalidad.

Si la herramienta de mensaje 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 incompatibilidad.

Para chats directos y cualquier otro evento de origen, use messages.visibleReplies: "message_tool" para aplicar globalmente el mismo comportamiento de respuesta visible solo para herramientas. Los turnos directos de WebChat interno por defecto entregan automáticamente la respuesta final para que Pi y Codex reciban el mismo contrato de respuesta visible. Establezca messages.visibleReplies: "message_tool" para requerir intencionalmente message(action=send) para la salida visible. messages.groupChat.visibleReplies sigue siendo la anulación más específica para salas de grupos/canales.

Esto reemplaza el antiguo patrón de forzar al modelo a responder NO_REPLY para la mayoría de los turnos en modo de observación. En el modo solo para herramientas, el prompt no define un contrato NO_REPLY. No hacer nada visible simplemente significa no llamar a la herramienta de mensaje.

Los enlaces de conversación propiedad del complemento son la excepción. Una vez que un complemento vincula un hilo y reclama el turno entrante, la respuesta devuelta por el complemento es la respuesta de vinculación visible; no necesita message(action=send). Esa respuesta es la salida del tiempo de ejecución del complemento, no el texto final privado del modelo.

Los indicadores de escritura aún se envían para solicitudes directas de grupo. Los eventos ambiente de salas siempre activas, cuando están habilitados, se mantienen estrictos y silenciosos a menos que el agente llame a la herramienta de mensaje.

Las sesiones suprimen los resúmenes detallados de herramientas/progreso de forma predeterminada. Use /verbose on para mostrar esos resúmenes para la sesión actual mientras depura, y /verbose off para volver al comportamiento de solo respuesta final. El mismo estado detallado se aplica a través de chats directos, grupos, canales y temas del foro.

Para enviar conversaciones de grupo siempre activas sin mención como contexto de sala silencioso en lugar de solicitudes de usuario, use Ambient room events:

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

El valor predeterminado es unmentionedInbound: "user_request".

Los mensajes mencionados, comandos, solicitudes de aborto y MDs se mantienen como solicitudes de usuario.

Para requerir que la salida visible pase a través de la herramienta de mensaje para solicitudes de grupo/canal:

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

La puerta de enlace recarga en caliente la configuración messages después de guardar el archivo. Reinicie solo cuando la observación de archivos o la recarga de la configuración están deshabilitadas en el despliegue.

Para requerir que la salida visible pase a través de la herramienta de mensaje para cada chat de origen:

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

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

Visibilidad del contexto y listas de permitidos

Sección titulada «Visibilidad del contexto y listas de permitidos»

En la seguridad de los grupos intervienen dos controles diferentes:

  • 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 hilos, metadatos reenviados).

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

El comportamiento actual es específico del canal
  • Algunos canales ya aplican un filtrado basado en el remitente para el contexto complementario en rutas específicas (por ejemplo, siembra de hilos de Slack, búsquedas de respuestas/hilos de Matrix).
  • Otros canales siguen pasando el contexto de cita/respaldo/reenvío tal como se recibe.
Dirección de endurecimiento (planificada)
  • contextVisibility: "all" (predeterminado) mantiene el comportamiento actual tal como se recibe.
  • contextVisibility: "allowlist" filtra el contexto complementario para los remitentes en la lista de permitidos.
  • contextVisibility: "allowlist_quote" es allowlist más una excepción explícita de cita/respaldo.

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

Flujo de mensajes de grupo

Si desea…

ObjetivoQué configurar
Permitir todos los grupos pero responder solo en @mencionesgroups: { "*": { requireMention: true } }
Deshabilitar todas las respuestas de grupogroupPolicy: "disabled"
Solo grupos específicosgroups: { "<group-id>": { ... } } (sin clave "*")
Solo usted puede activar en gruposgroupPolicy: "allowlist", groupAllowFrom: ["+1555..."]
Reutilizar un conjunto de remitentes de confianza en todos los canalesgroupAllowFrom: ["accessGroup:operators"]

Para listas de permitidos (allowlists) de remitentes reutilizables, consulte Grupos de acceso.

  • Las sesiones de grupo usan claves de sesión 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 latidos (heartbeats) se omiten para las sesiones de grupo.

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

Sección titulada «Patrón: MDs personales + grupos públicos (agente único)»

Sí; esto funciona bien si su tráfico “personal” son MDs y su tráfico “público” son grupos.

Por qué: en el modo de agente único, los MDs generalmente aterrizan en la clave de sesión main (agent:main:main), mientras que los grupos siempre usan claves de sesión no main (agent:main:<channel>:group:<id>). Si habilita el sandbox (aislamiento) con mode: "non-main", esas sesiones de grupo se ejecutan en el backend de sandbox configurado mientras que su sesión principal de MD se mantiene en el host. Docker es el backend predeterminado si no elige uno.

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

  • MDs: herramientas completas (host)
  • Grupos: sandbox + 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"],
},
},
},
}

Relacionado:

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

Controle 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": { enabled: true },
"#alias:example.org": { enabled: true },
},
},
},
}
PolíticaComportamiento
"open"Los grupos omiten las listas de permitidos; el filtrado de menciones aún se aplica.
"disabled"Bloquear todos los mensajes de grupo por completo.
"allowlist"Permitir solo grupos/salas que coincidan con la lista de permitidos configurada.
Notas por canal
  • groupPolicy está separado del filtrado de menciones (que requiere @menciones).
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use groupAllowFrom (alternativa: allowFrom explícito).
  • Signal: groupAllowFrom puede coincidir con el ID del grupo de Signal entrante o con el teléfono/UUID del remitente.
  • Las aprobaciones de emparejamiento de MD (entradas de la tienda *-allowFrom) se aplican solo al acceso de MD; la autorización del remitente del grupo permanece explícita en las listas permitidas del grupo.
  • Discord: la lista de permitidos usa `channels.discord.guilds.

.channels. - Slack: la lista de permitidos usa channels.slack.channels. - Matrix: la lista de permitidos usa channels.matrix.groups. Se prefieren los ID de sala o los 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. Use channels.matrix.groupAllowFrompara restringir remitentes; las listas permitidasusers por sala también son compatibles. - Los MD de grupo se controlan por separado (channels.discord.dm., channels.slack.dm.). - La lista de permitidos de Telegram puede coincidir con los ID de usuario (”123456789”, ”telegram:123456789”, ”tg:123456789”) o nombres de usuario (”@alice”o”alice”); los prefijos no distinguen mayúsculas de minúsculas. - El valor predeterminado es groupPolicy: “allowlist”; si su lista de permitidos de grupo está vacía, los mensajes del grupo se bloquean. - Seguridad en tiempo de ejecución: cuando falta completamente un bloque de proveedor (channels.

ausente), la política de grupo vuelve a un modo de cierre seguro (típicamenteallowlist) en lugar de heredar channels.defaults.groupPolicy`.

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

  1. groupPolicy

    groupPolicy (open/disabled/allowlist).

  2. Listas permitidas de grupo

    Listas permitidas de grupo (*.groups, *.groupAllowFrom, lista permitida específica del canal).

  3. Filtrado de menciones

    Filtrado de menciones (requireMention, /activation).

Los mensajes de grupo requieren una mención a menos que se anule para cada grupo. Los valores predeterminados residen por subsistema bajo *.groups."*".

Responder a un mensaje de bot cuenta como una mención implícita cuando el canal admite metadatos de respuesta. Citar un mensaje de bot también puede contar como una mención implícita en los 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,
},
},
],
},
}

Alcance de los patrones de mención configurados

Sección titulada «Alcance de los patrones de mención configurados»

Los mentionPatterns configurados son disparadores alternativos de expresiones regulares. Úselos cuando la plataforma no exponga una mención nativa del bot, o cuando desee que texto plano como openclaw: cuente como una mención. Las menciones nativas de la plataforma son separadas: cuando Discord, Slack, Telegram, Matrix u otro canal pueden probar que el mensaje mencionó explícitamente al bot, esa mención nativa todavía se activa incluso si los patrones de expresiones regulares configurados están denegados.

De forma predeterminada, los patrones de mención configurados se aplican en todas partes donde el canal pasa los datos del proveedor y la conversación a la detección de menciones. Para evitar que los patrones amplios activen el agente en cada grupo, delimítelos por canal con channels.<channel>.mentionPatterns.

Use mode: "deny" cuando los patrones de mención de regex deben estar desactivados de forma predeterminada para un canal, luego active salas específicas 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 de regex deban aplicarse ampliamente, luego desactívelos en salas ruidosas con denyIn:

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

Resolución de políticas:

CampoEfecto
mode: "allow"Los patrones de mención de regex están habilitados a menos que el ID de conversación esté en denyIn. Este es el valor predeterminado.
mode: "deny"Los patrones de mención de regex están deshabilitados a menos que el ID de conversación esté en allowIn.
allowInID de conversación donde los patrones de mención de regex están habilitados en modo de denegación.
denyInID de conversación donde los patrones de mención de expresiones regulares están desactivados. denyIn tiene prioridad sobre allowIn si ambos incluyen el mismo ID.

Política de expresión regular con ámbito admitida actualmente:

CanalID utilizados en allowIn / denyIn
DiscordID de canales de Discord.
MatrixID de salas de Matrix.
SlackID de canales de Slack.
TelegramID de chat de grupo, o chatId:topic:threadId para temas de foro.
WhatsAppID de conversación de WhatsApp como [email protected].

Las configuraciones de canal a nivel de cuenta pueden establecer la misma política bajo channels.<channel>.accounts.<accountId>.mentionPatterns cuando ese canal admite múltiples cuentas. La política de cuenta tiene prioridad sobre la política de canal de nivel superior para esa cuenta.

Notas sobre el filtrado de menciones
  • 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 superficies que proporcionan menciones explícitas todavía pasan; los patrones de regex configurados son un respaldo.
  • `channels.

.mentionPatterns.mode: “deny”deshabilita los patrones de mención configurados por defecto para ese canal; vuelva a activar las conversaciones seleccionadas conallowIn. - channels.

.mentionPatterns.denyIndeshabilita los patrones de mención configurados para IDs de conversación específicos, mientras que las @menciones nativas de la plataforma todavía pasan. - Invalidación por agente:agents.list[].groupChat.mentionPatterns(útil cuando varios agentes comparten un grupo). - El filtrado de menciones solo se aplica cuando la detección de menciones es posible (las menciones nativas omentionPatternsestán configuradas). - Permitir un grupo o remitente no deshabilita el filtrado de menciones; establezca elrequireMentionde ese grupo enfalsecuando todos los mensajes deberían activarse. - El contexto del prompt de chat grupal automático lleva la instrucción de respuesta silenciosa resuelta en cada turno; los archivos del espacio de trabajo no deben duplicar la mecánica deNO_REPLY. - Los grupos donde se permiten respuestas silenciosas automáticas tratan los turnos de modelo vacíos limpios o solo de razonamiento como silenciosos, equivalente a NO_REPLY. Los chats directos nunca reciben la guía de NO_REPLY, y las respuestas grupales solo de herramienta de mensaje se mantienen silenciosas al no llamar a message(action=send). - El chat ambiental siempre activo en grupos utiliza semántica de solicitud de usuario de forma predeterminada. Establezca messages.groupChat.unmentionedInbound: “room_event”para enviarlo como contexto silencioso en su lugar. Consulte [Ambient room events](/es/channels/ambient-room-events) para ver ejemplos de configuración. - Los eventos de sala no se almacenan como solicitudes de usuario falsas, y el texto del asistente privado de eventos de sala sin herramienta de mensaje no se reproduce como historial de chat. - Los valores predeterminados de Discord se encuentran enchannels.discord.guilds.”*“(modificables por gremio/canal). - El contexto del historial de grupos se envuelve de manera uniforme en todos los canales. Los grupos con filtrado de menciones mantienen los mensajes omitidos pendientes; los grupos siempre activos también pueden retener mensajes de sala procesados recientes cuando el canal lo admite. Usemessages.groupChat.historyLimitpara el valor predeterminado global ychannels.

.historyLimit(ochannels.

.accounts.*.historyLimit) para las invalidaciones. Establezca 0` para deshabilitar.

Restricciones de herramientas de grupo/canal (opcional)

Sección titulada «Restricciones de herramientas de grupo/canal (opcional)»

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

  • tools: permitir/denegar herramientas para todo el grupo.
  • toolsBySender: anulaciones por remitente dentro del grupo. Utilice prefijos de clave explícitos: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> y el comodín "*". Los identificadores de canal utilizan identificadores de canal canónicos de OpenClaw; los alias como teams se normalizan a msteams. Las claves heredadas sin prefijo todavía se aceptan y coinciden solo como id:.

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

  1. Group toolsBySender

    Coincidencia de toolsBySender de grupo/canal.

  2. Group tools

    tools de grupo/canal.

  3. Default toolsBySender

    Coincidencia de toolsBySender predeterminada ("*").

  4. Default tools

    tools predeterminada ("*").

Ejemplo (Telegram):

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

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 mientras se establece el comportamiento de mención predeterminado.

Intenciones comunes (copiar/pegar):

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

Los propietarios del 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íe el comando como un mensaje independiente. Otras superficies actualmente ignoran /activation.

Las cargas útiles entrantes del grupo establecen:

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

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

  • Prefiera chat_id:<id> al enrutar o permitir listas.
  • Listar chats: imsg chats --limit 20.
  • Las respuestas del grupo siempre vuelven al mismo chat_id.

Consulte WhatsApp para conocer las reglas canónicas del sistema de instrucciones de WhatsApp, incluida la resolución de instrucciones grupales y directas, el comportamiento de los comodines y la semántica de anulación de la cuenta.

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