Broadcast Groups

상태: 실험적 기능
버전: 2026.1.9에 추가됨

개요

Broadcast Groups를 사용하면 여러 Agent가 동일한 메시지를 동시에 처리하고 응답할 수 있습니다. 이를 통해 단일 WhatsApp 그룹 또는 DM에서 함께 작동하는 특수 Agent 팀을 만들 수 있습니다 — 모두 하나의 전화번호를 사용합니다.

현재 범위: WhatsApp 전용 (web channel).

Broadcast 그룹은 Channel allowlist 및 그룹 활성화 규칙 이후에 평가됩니다. WhatsApp 그룹에서는 OpenClaw가 일반적으로 응답하는 경우(예: 멘션 시, 그룹 설정에 따라)에 브로드캐스트가 발생합니다.

사용 사례

1. 특수 Agent 팀

원자적이고 집중된 책임을 가진 여러 Agent를 배포합니다:

Group: "Development Team"
Agents:
  - CodeReviewer (코드 스니펫 검토)
  - DocumentationBot (문서 생성)
  - SecurityAuditor (취약점 검사)
  - TestGenerator (테스트 케이스 제안)

각 Agent는 동일한 메시지를 처리하고 전문적인 관점을 제공합니다.

2. 다국어 지원

Group: "International Support"
Agents:
  - Agent_EN (영어로 응답)
  - Agent_DE (독일어로 응답)
  - Agent_ES (스페인어로 응답)

3. 품질 보증 워크플로

Group: "Customer Support"
Agents:
  - SupportAgent (답변 제공)
  - QAAgent (품질 검토, 문제 발견 시에만 응답)

4. 작업 자동화

Group: "Project Management"
Agents:
  - TaskTracker (작업 데이터베이스 업데이트)
  - TimeLogger (소요 시간 기록)
  - ReportGenerator (요약 생성)

설정

기본 설정

최상위 broadcast 섹션을 추가합니다 (bindings 옆에). 키는 WhatsApp peer ID입니다:

  • 그룹 채팅: 그룹 JID (예: [email protected])
  • DM: E.164 전화번호 (예: +15551234567)
{
  "broadcast": {
    "[email protected]": ["alfred", "baerbel", "assistant3"]
  }
}

결과: OpenClaw가 이 채팅에서 응답할 때 세 Agent 모두를 실행합니다.

처리 전략

Agent가 메시지를 처리하는 방법을 제어합니다:

Parallel (기본값)

모든 Agent가 동시에 처리합니다:

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

Sequential

Agent가 순서대로 처리합니다 (이전 Agent가 완료될 때까지 대기):

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

작동 방식

메시지 흐름

  1. 수신 메시지가 WhatsApp 그룹에 도착합니다
  2. Broadcast 확인: 시스템이 peer ID가 broadcast에 있는지 확인합니다
  3. Broadcast 목록에 있는 경우:
    • 나열된 모든 Agent가 메시지를 처리합니다
    • 각 Agent는 자체 Session 키와 격리된 컨텍스트를 가집니다
    • Agent는 병렬(기본값) 또는 순차적으로 처리합니다
  4. Broadcast 목록에 없는 경우:
    • 일반 라우팅이 적용됩니다 (첫 번째 일치하는 binding)

참고: broadcast 그룹은 Channel allowlist 또는 그룹 활성화 규칙(멘션/명령 등)을 우회하지 않습니다. 메시지가 처리 대상인 경우 어떤 Agent가 실행되는지만 변경합니다.

Session 격리

Broadcast 그룹의 각 Agent는 다음을 완전히 분리하여 유지합니다:

  • Session 키 (agent:alfred:whatsapp:group:120363... vs agent:baerbel:whatsapp:group:120363...)
  • 대화 기록 (Agent는 다른 Agent의 메시지를 보지 못함)
  • Workspace (구성된 경우 별도의 Sandbox)
  • Tool 액세스 (다른 허용/거부 목록)
  • 메모리/컨텍스트 (별도의 IDENTITY.md, SOUL.md 등)
  • 그룹 컨텍스트 버퍼 (컨텍스트에 사용되는 최근 그룹 메시지)는 peer별로 공유되므로 모든 broadcast Agent가 트리거될 때 동일한 컨텍스트를 볼 수 있습니다

이를 통해 각 Agent는 다음을 가질 수 있습니다:

  • 다른 성격
  • 다른 Tool 액세스 (예: 읽기 전용 vs. 읽기-쓰기)
  • 다른 모델 (예: opus vs. sonnet)
  • 다른 Skill 설치

예시: 격리된 Session

Agent ["alfred", "baerbel"]가 있는 그룹 [email protected]:

Alfred의 컨텍스트:

Session: agent:alfred:whatsapp:group:[email protected]
History: [사용자 메시지, alfred의 이전 응답]
Workspace: /Users/pascal/openclaw-alfred/
Tools: read, write, exec

Bärbel의 컨텍스트:

Session: agent:baerbel:whatsapp:group:[email protected]  
History: [사용자 메시지, baerbel의 이전 응답]
Workspace: /Users/pascal/openclaw-baerbel/
Tools: read only

모범 사례

1. Agent를 집중적으로 유지

각 Agent를 단일하고 명확한 책임으로 설계합니다:

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

✅ 좋은 예: 각 Agent가 하나의 작업을 수행
❌ 나쁜 예: 하나의 일반 "dev-helper" Agent

2. 설명적인 이름 사용

각 Agent가 무엇을 하는지 명확하게 합니다:

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

3. 다른 Tool 액세스 구성

Agent에게 필요한 Tool만 제공합니다:

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

4. 성능 모니터링

많은 Agent가 있는 경우 고려사항:

  • 속도를 위해 "strategy": "parallel" (기본값) 사용
  • Broadcast 그룹을 5-10개 Agent로 제한
  • 단순한 Agent에는 더 빠른 모델 사용

5. 실패를 우아하게 처리

Agent는 독립적으로 실패합니다. 한 Agent의 오류가 다른 Agent를 차단하지 않습니다:

메시지 → [Agent A ✓, Agent B ✗ 오류, Agent C ✓]
결과: Agent A와 C가 응답, Agent B는 오류 로깅

호환성

Provider

Broadcast 그룹은 현재 다음과 함께 작동합니다:

  • ✅ WhatsApp (구현됨)
  • 🚧 Telegram (계획됨)
  • 🚧 Discord (계획됨)
  • 🚧 Slack (계획됨)

라우팅

Broadcast 그룹은 기존 라우팅과 함께 작동합니다:

{
  "bindings": [
    { "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } }, "agentId": "alfred" }
  ],
  "broadcast": {
    "GROUP_B": ["agent1", "agent2"]
  }
}
  • GROUP_A: alfred만 응답 (일반 라우팅)
  • GROUP_B: agent1과 agent2 모두 응답 (broadcast)

우선순위: broadcast가 bindings보다 우선합니다.

문제 해결

Agent가 응답하지 않음

확인:

  1. Agent ID가 agents.list에 존재
  2. Peer ID 형식이 올바른지 (예: [email protected])
  3. Agent가 거부 목록에 없는지

디버그:

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

한 Agent만 응답함

원인: Peer ID가 bindings에는 있지만 broadcast에는 없을 수 있습니다.

해결: Broadcast 설정에 추가하거나 bindings에서 제거합니다.

성능 문제

많은 Agent로 인해 느린 경우:

  • 그룹당 Agent 수 줄이기
  • 더 가벼운 모델 사용 (opus 대신 sonnet)
  • Sandbox 시작 시간 확인

예시

예시 1: 코드 리뷰 팀

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

사용자가 보냄: 코드 스니펫
응답:

  • code-formatter: "들여쓰기를 수정하고 타입 힌트를 추가했습니다"
  • security-scanner: "⚠️ 12번 줄에 SQL injection 취약점이 있습니다"
  • test-coverage: "커버리지가 45%입니다. 오류 케이스에 대한 테스트가 누락되었습니다"
  • docs-checker: "함수 process_data에 대한 docstring이 누락되었습니다"

예시 2: 다국어 지원

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

API 참조

설정 스키마

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

필드

  • strategy (선택): Agent 처리 방법

    • "parallel" (기본값): 모든 Agent가 동시에 처리
    • "sequential": Agent가 배열 순서로 처리

  • [peerId]: WhatsApp 그룹 JID, E.164 번호 또는 기타 peer ID

    • 값: 메시지를 처리해야 하는 Agent ID 배열

제한 사항

  1. 최대 Agent 수: 엄격한 제한은 없지만 10개 이상의 Agent는 느릴 수 있습니다
  2. 공유 컨텍스트: Agent는 서로의 응답을 보지 못합니다 (의도적 설계)
  3. 메시지 순서: 병렬 응답은 임의의 순서로 도착할 수 있습니다
  4. 속도 제한: 모든 Agent는 WhatsApp 속도 제한에 포함됩니다

향후 개선 사항

계획된 기능:

  • 공유 컨텍스트 모드 (Agent가 서로의 응답을 볼 수 있음)
  • Agent 조정 (Agent가 서로 신호를 보낼 수 있음)
  • 동적 Agent 선택 (메시지 내용에 따라 Agent 선택)
  • Agent 우선순위 (일부 Agent가 다른 Agent보다 먼저 응답)

참고

← 문서로 돌아가기