docs/channels/broadcast-groups.md
Broadcast Groups enable multiple agents to process and respond to the same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number.
Current scope: WhatsApp only (web channel).
Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when OpenClaw would normally reply (for example: on mention, depending on your group settings).
```
Group: "Development Team"
Agents:
- CodeReviewer (reviews code snippets)
- DocumentationBot (generates docs)
- SecurityAuditor (checks for vulnerabilities)
- TestGenerator (suggests test cases)
```
Each agent processes the same message and provides its specialized perspective.
Add a top-level broadcast section (next to bindings). Keys are WhatsApp peer ids:
[email protected])+15551234567){
"broadcast": {
"[email protected]": ["alfred", "baerbel", "assistant3"]
}
}
Result: When OpenClaw would reply in this chat, it will run all three agents.
Control how agents process messages:
<Tabs> <Tab title="parallel (default)"> All agents process simultaneously:```json
{
"broadcast": {
"strategy": "parallel",
"[email protected]": ["alfred", "baerbel"]
}
}
```
```json
{
"broadcast": {
"strategy": "sequential",
"[email protected]": ["alfred", "baerbel"]
}
}
```
{
"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"]
}
}
Each agent in a broadcast group maintains completely separate:
agent:alfred:whatsapp:group:120363... vs agent:baerbel:whatsapp:group:120363...)This allows each agent to have:
In group [email protected] with agents ["alfred", "baerbel"]:
```json
{
"broadcast": {
"DEV_GROUP": ["formatter", "linter", "tester"]
}
}
```
✅ **Good:** Each agent has one job. ❌ **Bad:** One generic "dev-helper" agent.
```json
{
"agents": {
"security-scanner": { "name": "Security Scanner" },
"code-formatter": { "name": "Code Formatter" },
"test-generator": { "name": "Test Generator" }
}
}
```
```json
{
"agents": {
"reviewer": {
"tools": { "allow": ["read", "exec"] }
},
"fixer": {
"tools": { "allow": ["read", "write", "edit", "exec"] }
}
}
}
```
`reviewer` is read-only. `fixer` can read and write.
- Using `"strategy": "parallel"` (default) for speed
- Limiting broadcast groups to 5-10 agents
- Using faster models for simpler agents
```
Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
Result: Agent A and C respond, Agent B logs error
```
Broadcast groups currently work with:
Broadcast groups work alongside existing routing:
{
"bindings": [
{
"match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
"agentId": "alfred"
}
],
"broadcast": {
"GROUP_B": ["agent1", "agent2"]
}
}
GROUP_A: Only alfred responds (normal routing).GROUP_B: agent1 AND agent2 respond (broadcast).1. Agent IDs exist in `agents.list`.
2. Peer ID format is correct (e.g., `[email protected]`).
3. Agents are not in deny lists.
**Debug:**
```bash
tail -f ~/.openclaw/logs/gateway.log | grep broadcast
```
**Fix:** Add to broadcast config or remove from bindings.
- Reduce number of agents per group.
- Use lighter models (sonnet instead of opus).
- Check sandbox startup time.
**User sends:** Code snippet.
**Responses:**
- code-formatter: "Fixed indentation and added type hints"
- security-scanner: "⚠️ SQL injection vulnerability in line 12"
- test-coverage: "Coverage is 45%, missing tests for error cases"
- docs-checker: "Missing docstring for function `process_data`"
interface OpenClawConfig {
broadcast?: {
strategy?: "parallel" | "sequential";
[peerId: string]: string[];
};
}
Planned features: