Broadcast Groups

Trạng thái: Thử nghiệm Phiên bản: Thêm vào 2026.1.9

Tổng quan

Broadcast Groups cho phép nhiều Agent xử lý và phản hồi cùng một tin nhắn đồng thời. Điều này giúp các bạn tạo ra các nhóm Agent chuyên biệt làm việc cùng nhau trong một nhóm WhatsApp hoặc DM — tất cả chỉ dùng một số điện thoại.

Phạm vi hiện tại: Chỉ WhatsApp (web channel).

Broadcast groups được đánh giá sau channel allowlists và group activation rules. Trong các nhóm WhatsApp, điều này có nghĩa là broadcast xảy ra khi OpenClaw thường phản hồi (ví dụ: khi được mention, tùy thuộc vào cài đặt nhóm của các bạn).

Các trường hợp sử dụng

1. Nhóm Agent chuyên biệt

Triển khai nhiều Agent với trách nhiệm tập trung, rõ ràng:

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

Mỗi Agent xử lý cùng một tin nhắn và đưa ra góc nhìn chuyên môn của riêng mình.

2. Hỗ trợ đa ngôn ngữ

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

3. Quy trình đảm bảo chất lượng

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

4. Tự động hóa tác vụ

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

Cấu hình

Cài đặt cơ bản

Thêm phần broadcast ở cấp cao nhất (cạnh bindings). Các key là WhatsApp peer ids:

  • group chats: group JID (ví dụ [email protected])
  • DMs: số điện thoại E.164 (ví dụ +15551234567)
{
  "broadcast": {
    "[email protected]": ["alfred", "baerbel", "assistant3"]
  }
}

Kết quả: Khi OpenClaw phản hồi trong chat này, nó sẽ chạy cả ba Agent.

Chiến lược xử lý

Kiểm soát cách các Agent xử lý tin nhắn:

Parallel (Mặc định)

Tất cả Agent xử lý đồng thời:

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

Sequential

Các Agent xử lý theo thứ tự (Agent sau đợi Agent trước hoàn thành):

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

Ví dụ đầy đủ

{
  "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ách hoạt động

Luồng tin nhắn

  1. Tin nhắn đến từ nhóm WhatsApp
  2. Kiểm tra broadcast: Hệ thống kiểm tra xem peer ID có trong broadcast không
  3. Nếu có trong danh sách broadcast:
    • Tất cả Agent được liệt kê sẽ xử lý tin nhắn
    • Mỗi Agent có session key riêng và context độc lập
    • Các Agent xử lý song song (mặc định) hoặc tuần tự
  4. Nếu không có trong danh sách broadcast:
    • Áp dụng routing thông thường (binding khớp đầu tiên)

Lưu ý: broadcast groups không bỏ qua channel allowlists hoặc group activation rules (mentions/commands/etc). Chúng chỉ thay đổi Agent nào chạy khi tin nhắn đủ điều kiện xử lý.

Cô lập Session

Mỗi Agent trong broadcast group duy trì hoàn toàn riêng biệt:

  • Session keys (agent:alfred:whatsapp:group:120363... vs agent:baerbel:whatsapp:group:120363...)
  • Lịch sử hội thoại (Agent không thấy tin nhắn của Agent khác)
  • Workspace (các sandbox riêng biệt nếu được cấu hình)
  • Quyền truy cập công cụ (danh sách allow/deny khác nhau)
  • Bộ nhớ/context (các file IDENTITY.md, SOUL.md riêng biệt, v.v.)
  • Group context buffer (tin nhắn nhóm gần đây dùng cho context) được chia sẻ theo peer, nên tất cả broadcast Agent thấy cùng context khi được kích hoạt

Điều này cho phép mỗi Agent có:

  • Tính cách khác nhau
  • Quyền truy cập công cụ khác nhau (ví dụ: chỉ đọc vs. đọc-ghi)
  • Model khác nhau (ví dụ: opus vs. sonnet)
  • Các Skill được cài đặt khác nhau

Ví dụ: Session độc lập

Trong nhóm [email protected] với các Agent ["alfred", "baerbel"]:

Context của Alfred:

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

Context của Bärbel:

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

Thực hành tốt nhất

1. Giữ Agent tập trung

Thiết kế mỗi Agent với một trách nhiệm duy nhất, rõ ràng:

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

✅ Tốt: Mỗi Agent có một nhiệm vụ ❌ Không tốt: Một Agent chung chung kiểu “dev-helper”

2. Dùng tên mô tả rõ ràng

Làm rõ mỗi Agent làm gì:

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

3. Cấu hình quyền truy cập công cụ khác nhau

Chỉ cho Agent những công cụ cần thiết:

{
  "agents": {
    "reviewer": {
      "tools": { "allow": ["read", "exec"] } // Chỉ đọc
    },
    "fixer": {
      "tools": { "allow": ["read", "write", "edit", "exec"] } // Đọc-ghi
    }
  }
}

4. Theo dõi hiệu suất

Với nhiều Agent, các bạn nên:

  • Dùng "strategy": "parallel" (mặc định) để tăng tốc
  • Giới hạn broadcast groups ở 5-10 Agent
  • Dùng model nhẹ hơn cho các Agent đơn giản

5. Xử lý lỗi một cách khéo léo

Các Agent lỗi độc lập. Lỗi của một Agent không chặn Agent khác:

Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
Kết quả: Agent A và C phản hồi, Agent B ghi log lỗi

Tương thích

Providers

Broadcast groups hiện hoạt động với:

  • ✅ WhatsApp (đã triển khai)
  • 🚧 Telegram (đang lên kế hoạch)
  • 🚧 Discord (đang lên kế hoạch)
  • 🚧 Slack (đang lên kế hoạch)

Routing

Broadcast groups hoạt động cùng với routing hiện có:

{
  "bindings": [
    {
      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
      "agentId": "alfred"
    }
  ],
  "broadcast": {
    "GROUP_B": ["agent1", "agent2"]
  }
}
  • GROUP_A: Chỉ alfred phản hồi (routing thông thường)
  • GROUP_B: agent1 VÀ agent2 phản hồi (broadcast)

Ưu tiên: broadcast được ưu tiên hơn bindings.

Khắc phục sự cố

Agent không phản hồi

Kiểm tra:

  1. Agent IDs có tồn tại trong agents.list không
  2. Định dạng Peer ID có đúng không (ví dụ [email protected])
  3. Các Agent không nằm trong deny lists

Debug:

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

Chỉ một Agent phản hồi

Nguyên nhân: Peer ID có thể nằm trong bindings nhưng không có trong broadcast.

Sửa: Thêm vào broadcast config hoặc xóa khỏi bindings.

Vấn đề hiệu suất

Nếu chậm với nhiều Agent:

  • Giảm số lượng Agent mỗi nhóm
  • Dùng model nhẹ hơn (sonnet thay vì opus)
  • Kiểm tra thời gian khởi động sandbox

Ví dụ

Ví dụ 1: Nhóm Code Review

{
  "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"] } }
    ]
  }
}

User gửi: Code snippet Phản hồi:

  • 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”

Ví dụ 2: Hỗ trợ đa ngôn ngữ

{
  "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" }
    ]
  }
}

Tham khảo API

Config Schema

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

Các trường

  • strategy (tùy chọn): Cách xử lý Agent
    • "parallel" (mặc định): Tất cả Agent xử lý đồng thời
    • "sequential": Các Agent xử lý theo thứ tự mảng
  • [peerId]: WhatsApp group JID, số E.164, hoặc peer ID khác
    • Giá trị: Mảng các Agent ID cần xử lý tin nhắn

Giới hạn

  1. Số Agent tối đa: Không có giới hạn cứng, nhưng 10+ Agent có thể chậm
  2. Context chia sẻ: Các Agent không thấy phản hồi của nhau (theo thiết kế)
  3. Thứ tự tin nhắn: Phản hồi song song có thể đến theo bất kỳ thứ tự nào
  4. Giới hạn tốc độ: Tất cả Agent đều tính vào giới hạn tốc độ WhatsApp

Cải tiến trong tương lai

Các tính năng đang lên kế hoạch:

  • Chế độ context chia sẻ (các Agent thấy phản hồi của nhau)
  • Phối hợp Agent (các Agent có thể báo hiệu cho nhau)
  • Chọn Agent động (chọn Agent dựa trên nội dung tin nhắn)
  • Ưu tiên Agent (một số Agent phản hồi trước những Agent khác)

Xem thêm