Grupos de difusión

Resumen

Los grupos de difusión permiten que múltiples agentes procesen y respondan al mismo mensaje simultáneamente. Esto le permite crear equipos de agentes especializados que trabajan juntos en un solo grupo de WhatsApp o mensaje directo — todo usando un número de teléfono.

Alcance actual: Solo WhatsApp (canal web).

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, esto significa que las difusiones ocurren cuando OpenClaw normalmente respondería (por ejemplo: al mencionar, dependiendo de la configuración de su grupo).

Casos de uso

1. Equipos de agentes especializados

Implemente varios agentes con responsabilidades atómicas y enfocadas:

Group: "Development Team"
Agents:
  - CodeReviewer (reviews code snippets)
  - DocumentationBot (generates docs)
  - SecurityAuditor (checks for vulnerabilities)
  - TestGenerator (suggests test cases)

Cada agente procesa el mismo mensaje y proporciona su perspectiva especializada.

2. Soporte multilingüe

Group: "International Support"
Agents:
  - Agent_EN (responds in English)
  - Agent_DE (responds in German)
  - Agent_ES (responds in Spanish)

3. Flujos de trabajo de control de calidad

Group: "Customer Support"
Agents:
  - SupportAgent (provides answer)
  - QAAgent (reviews quality, only responds if issues found)

4. Automatización de tareas

Group: "Project Management"
Agents:
  - TaskTracker (updates task database)
  - TimeLogger (logs time spent)
  - ReportGenerator (creates summaries)

Configuración

Configuración básica

Añada una sección broadcast de nivel superior (junto a bindings). Las claves son IDs de pares de WhatsApp:

chats de grupo: JID de grupo (ej. [email protected])
Mensajes directos (DM): número de teléfono E.164 (ej. +15551234567)

{
  "broadcast": {
    "[email protected]": ["alfred", "baerbel", "assistant3"]
  }
}

Resultado: Cuando OpenClaw vaya a responder en este chat, ejecutará los tres agentes.

Estrategia de procesamiento

Controle cómo los agentes procesan los mensajes:

Todos los agentes procesan simultáneamente:

{
  "broadcast": {
    "strategy": "parallel",
    "[email protected]": ["alfred", "baerbel"]
  }
}

Los agentes procesan en orden (uno espera a que el anterior termine):

{
  "broadcast": {
    "strategy": "sequential",
    "[email protected]": ["alfred", "baerbel"]
  }
}

Ejemplo completo

{
  "agents": {
    "list": [
      {
        "id": "code-reviewer",
        "name": "Code Reviewer",
        "workspace": "/path/to/code-reviewer",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "security-auditor",
        "name": "Security Auditor",
        "workspace": "/path/to/security-auditor",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "docs-generator",
        "name": "Documentation Generator",
        "workspace": "/path/to/docs-generator",
        "sandbox": { "mode": "all" }
      }
    ]
  },
  "broadcast": {
    "strategy": "parallel",
    "[email protected]": ["code-reviewer", "security-auditor", "docs-generator"],
    "[email protected]": ["support-en", "support-de"],
    "+15555550123": ["assistant", "logger"]
  }
}

Cómo funciona

Flujo de mensajes

Llega el mensaje entrante
Llega un mensaje de grupo o mensaje directo de WhatsApp.
Verificación de difusión
El sistema verifica si el ID del par está en broadcast.
Si está en la lista de difusión
- Todos los agentes listados procesan el mensaje.
- Cada agente tiene su propia clave de sesión y contexto aislado.
- Los agentes procesan en paralelo (predeterminado) o secuencialmente.
Si no está en la lista de difusión
Se aplica el enrutamiento normal (primer enlace coincidente).

Aislamiento de sesión

Cada agente en 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 (el agente no ve los mensajes de otros agentes)
Espacio de trabajo (sandboxes separados si están configurados)
Acceso a herramientas (diferentes listas de permitir/denegar)
Memoria/contexto (IDENTITY.md, SOUL.md, etc. separados)
Búfer de contexto de grupo (mensajes recientes del grupo utilizados para el contexto) se comparte por par, por lo que todos los agentes de difusión ven el mismo contexto cuando se activan

Esto permite que cada agente tenga:

Diferentes personalidades
Diferentes accesos a herramientas (ej., solo lectura frente a lectura-escritura)
Diferentes modelos (ej., opus frente a sonnet)
Diferentes habilidades instaladas

Ejemplo: sesiones aisladas

En el grupo [email protected] con los agentes ["alfred", "baerbel"]:

Session: agent:alfred:whatsapp:group:[email protected] History: [user message, alfred's previous responses] Workspace: /Users/user/openclaw-alfred/ Tools: read, write, exec

Session: agent:baerbel:whatsapp:group:[email protected] History: [user message, baerbel's previous responses] Workspace: /Users/user/openclaw-baerbel/ Tools: read only

Mejores prácticas

1. Mantenga a los agentes enfocados

Diseñe cada agente con una única y clara responsabilidad:

{
  "broadcast": {
    "DEV_GROUP": ["formatter", "linter", "tester"]
  }
}

✅ Bueno: Cada agente tiene un trabajo. ❌ Malo: Un agente genérico de “ayudante de desarrollo”.

2. Use nombres descriptivos

Deje claro qué hace cada agente:

{
  "agents": {
    "security-scanner": { "name": "Security Scanner" },
    "code-formatter": { "name": "Code Formatter" },
    "test-generator": { "name": "Test Generator" }
  }
}

3. Configure el acceso a diferentes herramientas

Dé a los agentes solo las herramientas que necesitan:

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

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

4. Monitorear el rendimiento

Con muchos agentes, considere:

Usar "strategy": "parallel" (predeterminado) para mayor velocidad
Limitar los grupos de difusión a 5-10 agentes
Usar modelos más rápidos para agentes más simples

5. Manejar fallos con elegancia

Los agentes fallan de forma independiente. El error de un agente no bloquea a los demás:

Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
Result: Agent A and C respond, Agent B logs error

Compatibilidad

Proveedores

Los grupos de transmisión actualmente funcionan con:

✅ WhatsApp (implementado)
🚧 Telegram (planificado)
🚧 Discord (planificado)
🚧 Slack (planificado)

Enrutamiento

Los grupos de transmisió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 alfred responde (enrutamiento normal).
GROUP_B: agent1 Y agent2 responden (difusión).

Solución de problemas

Agentes que no responden

Verificar:

Los IDs de los agentes existen en agents.list.
El formato del ID del par es correcto (ej., [email protected]).
Los agentes no están en listas de denegación.

Depurar:

tail -f ~/.openclaw/logs/gateway.log | grep broadcast

Solo un agente responde

Causa: Es posible que el ID del par esté en bindings pero no en broadcast.

Solución: Agregar a la configuración de difusión o eliminar de los enlaces.

Problemas de rendimiento

Si es lento con muchos agentes:

Reduce el número de agentes por grupo.
Usa modelos más ligeros (sonnet en lugar de opus).
Verifica el tiempo de inicio del sandbox.

Ejemplos

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

{
  "broadcast": {
    "strategy": "parallel",
    "[email protected]": [
      "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"] } }
    ]
  }
}

Usuario envía: Fragmento de código.

Respuestas:

code-formatter: “Sangría corregida y sugerencias de tipo añadidas”
security-scanner: “⚠️ Vulnerabilidad de inyección SQL en la línea 12”
test-coverage: “La cobertura es del 45%, faltan pruebas para casos de error”
docs-checker: “Falta el docstring para la función process_data”

Ejemplo 2: Soporte 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

Cómo procesar los agentes. `parallel` ejecuta todos los agentes simultáneamente; `sequential` los ejecuta en orden de matriz. JID de grupo de WhatsApp, número E.164 u otro ID de par. El valor es la matriz de IDs de agentes que deben procesar mensajes.

Limitaciones

Máximo de agentes: Sin límite estricto, pero 10 o más agentes pueden ser lentos.
Contexto compartido: Los agentes no ven las respuestas de los demás (por diseño).
Orden de mensajes: Las respuestas paralelas pueden llegar en cualquier orden.
Límites de velocidad: Todos los agentes cuentan hacia los límites de velocidad de WhatsApp.

Mejoras futuras

Funcionalidades planificadas:

Modo de contexto compartido (los agentes ven las respuestas de los demás)
Coordinación de agentes (los agentes pueden señalarse entre sí)
Selección dinámica de agentes (elegir agentes basándose en el contenido del mensaje)
Prioridades de agentes (algunos agentes responden antes que otros)