Grupos de difusión

Estado: Experimental. Añadido en 2026.1.9. Solo para WhatsApp (canal web).

Descripción general

Los grupos de difusión ejecutan varios agentes con el mismo mensaje entrante. Cada agente procesa el mensaje en su propia sesión aislada y publica su propia respuesta, por lo que un número de WhatsApp puede alojar un equipo de agentes especializados en un único chat grupal o mensaje directo. Los grupos de difusión se evalúan después de las listas de permitidos del canal y las reglas de activación de grupos. En los grupos de WhatsApp, la difusión se produce cuando OpenClaw respondería normalmente (por ejemplo, al recibir una mención, según la configuración del grupo). Solo cambia qué agentes se ejecutan, nunca si un mensaje cumple los requisitos para procesarse. La vía activa de control de calidad de WhatsApp incluye whatsapp-broadcast-group-fanout, que verifica que un mensaje de grupo con una mención pueda producir respuestas visibles distintas de dos agentes configurados.

Configuración

Configuración básica

Añada una sección broadcast de nivel superior (junto a bindings). Las claves son identificadores de pares de WhatsApp y los valores son matrices de identificadores de agentes:

chats grupales: JID del grupo (p. ej., 120363403215116621@g.us)
mensajes directos: número de teléfono E.164 del remitente (p. ej., +15551234567)

{
  "broadcast": {
    "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
  }
}

Resultado: cuando OpenClaw respondería en este chat, ejecuta los tres agentes. Cada identificador de agente indicado debe existir en agents.entries: la validación de la configuración informa de los identificadores desconocidos y el entorno de ejecución los omite con una advertencia Broadcast agent <id> not found in agents.entries; skipping.

Estrategia de procesamiento

broadcast.strategy establece cómo procesan los agentes el mensaje:

Estrategia	Comportamiento
`parallel` (predeterminada)	Todos los agentes procesan simultáneamente; las respuestas llegan en cualquier orden.
`sequential`	Los agentes procesan en el orden de la matriz; cada uno espera a que termine el anterior.

{
  "broadcast": {
    "strategy": "sequential",
    "120363403215116621@g.us": ["alfred", "baerbel"]
  }
}

Ejemplo completo

{
  "agents": {
    "list": [
      {
        "id": "code-reviewer",
        "name": "Revisor de código",
        "workspace": "/path/to/code-reviewer",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "security-auditor",
        "name": "Auditor de seguridad",
        "workspace": "/path/to/security-auditor",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "docs-generator",
        "name": "Generador de documentación",
        "workspace": "/path/to/docs-generator",
        "sandbox": { "mode": "all" }
      }
    ]
  },
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
    "120363424282127706@g.us": ["support-en", "support-de"],
    "+15555550123": ["assistant", "logger"]
  }
}

Funcionamiento

Flujo de mensajes

Llega un mensaje entrante

Llega un mensaje de un grupo o mensaje directo de WhatsApp.

Enrutamiento y admisión

OpenClaw aplica las listas de permitidos del canal, las reglas de activación de grupos y la propiedad de los enlaces ACP configurados.

Comprobación de difusión

Si ningún enlace ACP configurado es propietario de la ruta, OpenClaw comprueba si el identificador del par está en broadcast.

Si se aplica la difusión

Todos los agentes indicados procesan el mensaje.
Cada agente tiene su propia clave de sesión y contexto aislado.
Los agentes procesan en paralelo (opción predeterminada) o secuencialmente.
Los archivos adjuntos de audio se transcriben una vez antes de la distribución, por lo que los agentes comparten una transcripción en lugar de realizar llamadas STT independientes.

Si no se aplica la difusión

OpenClaw despacha la ruta ordinaria o la ruta de sesión ACP configurada seleccionada durante el enrutamiento.

Los grupos de difusión no omiten las listas de permitidos del canal ni las reglas de activación de grupos (menciones, comandos, etc.). Solo cambian qué agentes se ejecutan cuando un mensaje cumple los requisitos para procesarse.

Aislamiento de sesiones

Cada agente de un grupo de difusión mantiene completamente separados:

Claves de sesión (agent:alfred:whatsapp:group:120363... frente a agent:baerbel:whatsapp:group:120363...)
Historial de conversación (un agente no ve las respuestas de otros agentes)
Espacio de trabajo (entornos aislados separados si están configurados)
Acceso a herramientas (listas de permitidos y denegados diferentes)
Memoria/contexto (IDENTITY.md, SOUL.md, etc. separados)

Hay una excepción que se comparte deliberadamente: el búfer de contexto del grupo (mensajes recientes del grupo utilizados como contexto) se comparte por par, por lo que todos los agentes de difusión ven el mismo contexto cuando se activan. Se borra una vez después de que finalice la distribución. Esto permite que cada agente tenga distintas personalidades, modelos, Skills y acceso a herramientas (por ejemplo, solo lectura frente a lectura y escritura).

Ejemplo: sesiones aisladas

En el grupo 120363403215116621@g.us con los agentes ["alfred", "baerbel"]:

Contexto de Alfred
Contexto de Baerbel

Sesión: agent:alfred:whatsapp:group:120363403215116621@g.us
Historial: [mensaje del usuario, respuestas anteriores de alfred]
Espacio de trabajo: ~/openclaw-alfred/
Herramientas: lectura, escritura, ejecución

Sesión: agent:baerbel:whatsapp:group:120363403215116621@g.us
Historial: [mensaje del usuario, respuestas anteriores de baerbel]
Espacio de trabajo: ~/openclaw-baerbel/
Herramientas: solo lectura

Casos de uso

Equipos de agentes especializados: un grupo de desarrollo donde code-reviewer, security-auditor, test-generator y docs-checker responden al mismo mensaje cada uno desde su propia perspectiva.
Compatibilidad multilingüe: un chat de soporte con support-en, support-de y support-es respondiendo en sus respectivos idiomas.
Control de calidad: support-agent responde mientras qa-agent revisa y solo responde cuando encuentra problemas.
Automatización de tareas: task-tracker, time-logger y report-generator consumen la misma actualización de estado.

Prácticas recomendadas

1. Mantenga los agentes centrados

Asigne a cada agente una única responsabilidad clara (formatter, linter, tester) en lugar de un agente genérico “dev-helper”.

2. Use identificadores y nombres descriptivos

{
  "agents": {
    "list": [
      { "id": "security-scanner", "name": "Analizador de seguridad" },
      { "id": "code-formatter", "name": "Formateador de código" },
      { "id": "test-generator", "name": "Generador de pruebas" }
    ]
  }
}

3. Configure accesos distintos a las herramientas

{
  "agents": {
    "list": [
      { "id": "reviewer", "tools": { "allow": ["read", "exec"] } },
      { "id": "fixer", "tools": { "allow": ["read", "write", "edit", "exec"] } }
    ]
  }
}

reviewer es de solo lectura. fixer puede leer y escribir.

4. Supervise el rendimiento

Con muchos agentes, prefiera "strategy": "parallel" (opción predeterminada), limite los grupos de difusión a unos pocos agentes y utilice modelos más rápidos para los agentes más sencillos.

5. Los fallos permanecen aislados

Los agentes fallan de forma independiente. El error de un agente se registra (Broadcast agent <id> failed: ...) y no bloquea a los demás.

Compatibilidad

Proveedores

Actualmente, los grupos de difusión solo están implementados para WhatsApp (canal web). Los demás canales ignoran la configuración broadcast.

Enrutamiento

Los grupos de difusión funcionan junto con el enrutamiento existente:

{
  "bindings": [
    {
      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
      "agentId": "alfred"
    }
  ],
  "broadcast": {
    "GROUP_B": ["agent1", "agent2"]
  }
}

GROUP_A: solo responde alfred (enrutamiento normal).
GROUP_B: responden agent1 Y agent2 (difusión).

Precedencia: broadcast tiene prioridad sobre los enlaces de rutas ordinarias. Los enlaces ACP configurados (bindings[].type="acp") son exclusivos: cuando uno coincide, OpenClaw despacha a la sesión ACP configurada en lugar de realizar una difusión distribuida.

Solución de problemas

Los agentes no responden

Compruebe lo siguiente:

Los identificadores de los agentes existen en agents.entries (la validación de la configuración rechaza los identificadores desconocidos).
El formato del identificador del par es correcto (un JID de grupo como 120363403215116621@g.us o un número E.164 como +15551234567 para mensajes directos).
El mensaje superó los filtros normales (las reglas de mención y activación siguen aplicándose).

Depuración:

openclaw logs --follow | grep -i broadcast

Una distribución correcta registra Broadcasting message to <n> agents (<strategy>).

Solo responde un agente

Causa: es posible que el identificador del par esté en los enlaces de rutas ordinarias, pero no en broadcast, o que coincida con un enlace ACP configurado exclusivo.Solución: añada a la configuración de difusión los pares vinculados a rutas ordinarias o elimine/cambie el enlace ACP configurado si se desea una difusión distribuida.

Problemas de rendimiento

Si el funcionamiento es lento con muchos agentes: reduzca el número de agentes por grupo, utilice modelos más ligeros y compruebe el tiempo de inicio del entorno aislado.

Ejemplos

Ejemplo 1: Equipo de revisión de código

{
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": [
      "code-formatter",
      "security-scanner",
      "test-coverage",
      "docs-checker"
    ]
  },
  "agents": {
    "list": [
      {
        "id": "code-formatter",
        "workspace": "~/agents/formatter",
        "tools": { "allow": ["read", "write"] }
      },
      {
        "id": "security-scanner",
        "workspace": "~/agents/security",
        "tools": { "allow": ["read", "exec"] }
      },
      {
        "id": "test-coverage",
        "workspace": "~/agents/testing",
        "tools": { "allow": ["read", "exec"] }
      },
      { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
    ]
  }
}

Un fragmento de código en el grupo produce cuatro respuestas: correcciones de formato, un hallazgo de seguridad, una carencia de cobertura y una observación menor sobre la documentación.

Ejemplo 2: Pipeline multilingüe

{
  "broadcast": {
    "strategy": "sequential",
    "+15555550123": ["detect-language", "translator-en", "translator-de"]
  },
  "agents": {
    "list": [
      { "id": "detect-language", "workspace": "~/agents/lang-detect" },
      { "id": "translator-en", "workspace": "~/agents/translate-en" },
      { "id": "translator-de", "workspace": "~/agents/translate-de" }
    ]
  }
}

Referencia de la API

Esquema de configuración

interface OpenClawConfig {
  broadcast?: {
    strategy?: "parallel" | "sequential";
    [peerId: string]: string[];
  };
}

Campos

"parallel" | "sequential"

predeterminado:"\"parallel\""

Cómo procesar los agentes. parallel ejecuta todos los agentes simultáneamente; sequential los ejecuta en el orden de la matriz.

string[]

JID de grupo de WhatsApp o número de teléfono E.164. El valor es la matriz de identificadores de agentes que deben procesar todos los mensajes de ese par.

Limitaciones

Máximo de agentes: no hay un límite estricto, pero muchos agentes (10+) pueden ralentizar el funcionamiento.
Contexto compartido: los agentes no ven las respuestas de los demás (por diseño).
Orden de los mensajes: las respuestas en paralelo pueden llegar en cualquier orden.
Límites de frecuencia: todas las respuestas proceden de una sola cuenta de WhatsApp, por lo que la respuesta de cada agente cuenta para los mismos límites de frecuencia de WhatsApp.

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Grupos de difusión

Descripción general

Configuración

Configuración básica

Estrategia de procesamiento

Ejemplo completo

Funcionamiento

Flujo de mensajes

Aislamiento de sesiones

Ejemplo: sesiones aisladas

Casos de uso

Prácticas recomendadas

Compatibilidad

Proveedores

Enrutamiento

Solución de problemas

Ejemplos

Referencia de la API

Esquema de configuración

Campos

Limitaciones

Contenido relacionado

​Descripción general

​Configuración

​Configuración básica

​Estrategia de procesamiento

​Ejemplo completo

​Funcionamiento

​Flujo de mensajes

​Aislamiento de sesiones

​Ejemplo: sesiones aisladas

​Casos de uso

​Prácticas recomendadas

​Compatibilidad

​Proveedores

​Enrutamiento

​Solución de problemas

​Ejemplos

​Referencia de la API

​Esquema de configuración

​Campos

​Limitaciones

​Contenido relacionado

Descripción general

Configuración

Configuración básica

Estrategia de procesamiento

Ejemplo completo

Funcionamiento

Flujo de mensajes

Aislamiento de sesiones

Ejemplo: sesiones aisladas

Casos de uso

Prácticas recomendadas

Compatibilidad

Proveedores

Enrutamiento

Solución de problemas

Ejemplos

Referencia de la API

Esquema de configuración

Campos

Limitaciones

Contenido relacionado