Grupos

OpenClaw trata los chats de grupo 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 separado de WhatsApp. 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 control por 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 de grupo):

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

# Respuestas visibles

Para salas de grupo/canal, 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 de vuelta en la sala. Para hablar de forma visible, el agente usa message(action=send).

Este valor predeterminado depende de un modelo/runtime que llame herramientas de forma fiable. Si los registros muestran texto del asistente pero didSendViaMessagingTool: false, el modelo respondió en privado en lugar de llamar la herramienta de mensajes. Eso no es un fallo de envío de Discord/Slack/Telegram. Usa un modelo fiable para llamadas a herramientas en sesiones de grupo/canal, 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 vuelve a respuestas visibles automáticas en lugar de suprimir la respuesta silenciosamente. 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 herramientas. Los harnesses también pueden elegir esto como su valor predeterminado cuando no está configurado; el harness de Codex lo hace para chats directos en modo Codex. messages.groupChat.visibleReplies sigue siendo la anulación más específica para salas de grupo/canal.

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

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

Para restaurar las respuestas finales automáticas heredadas en salas de grupo/canal:

{
  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é desactivada en el despliegue.

Para exigir que la salida visible pase por la herramienta de mensajes en 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 nativa de comandos del canal reciba la respuesta que espera. Esto se aplica solo a turnos de comandos nativos validados; los comandos /... escritos como texto y los turnos de chat ordinarios siguen usando el valor predeterminado de grupo configurado.

# Visibilidad de contexto y listas de permitidos

Hay dos controles distintos implicados en la seguridad de grupos:

• Autorización de activación: quién puede activar al agente (groupPolicy, groups, groupAllowFrom, listas de permitidos específicas del canal).
• Visibilidad de 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 normal de chat y mantiene el contexto casi como se recibió. Esto significa que las listas de permitidos deciden principalmente quién puede activar acciones, no un límite universal de censura para cada fragmento citado o histórico.

Si quieres...

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

# Claves de sesión

• 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 foros de Telegram agregan :topic:<threadId> al id del grupo para que cada tema tenga su propia sesión.
• Los chats directos usan la sesión principal (o una por remitente si está configurado).
• Los Heartbeats se omiten en las sesiones de grupo.

# Patrón: DM personales + grupos públicos (un solo agente)

Sí: esto funciona bien si tu tráfico "personal" son DMs y tu tráfico "público" son grupos.

Por qué: en modo de un solo agente, los DMs suelen llegar 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 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 + memoria compartidos), pero dos posturas de ejecución:

• DMs: 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"],
      },
    },
  },
}

{
  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: Sandbox frente a política de herramientas frente a elevado
• Detalles de montajes bind: 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 de grupo usan g-<slug> (minúsculas, espacios -> -, conserva #@+._-).

# Política de grupos

Controla cómo se gestionan 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 },
      },
    },
  },
}

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 anule por grupo. Los valores predeterminados viven por subsistema en *.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 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 el comodín "*". Las claves heredadas sin prefijo todavía se aceptan y se comparan solo como id:.

Orden de resolución (gana 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 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 establecer 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 propietarios)

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á configurado). Envía el comando como un mensaje independiente. Actualmente, otras superficies ignoran /activation.

# Campos de contexto

Las cargas útiles entrantes de grupo establecen:

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

Notas específicas del canal:

• BlueBubbles puede enriquecer opcionalmente los participantes de grupos macOS sin nombre desde la base de datos local de Contactos antes de rellenar GroupMembers. Esto está desactivado de forma predeterminada y solo se ejecuta después de que pase el control normal de grupo.

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 responder como una persona, evitar tablas Markdown, minimizar las líneas vacías y seguir el espaciado normal de chat, y evitar escribir secuencias literales \n. Los nombres de grupo y las etiquetas de participantes provenientes del canal se renderizan como metadatos no confiables delimitados por vallas, no como instrucciones del sistema en línea.

# Aspectos específicos de iMessage

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

# Prompts del sistema de WhatsApp

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

# Aspectos específicos de WhatsApp

Consulta Mensajes de grupo para ver 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