그룹

OpenClaw는 WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo 등 모든 채널에서 그룹 채팅을 일관되게 처리합니다.

입문 가이드 (2분)

OpenClaw는 여러분의 메시징 계정 위에서 동작합니다. 별도의 WhatsApp 봇 사용자가 존재하지 않습니다. 여러분이 그룹에 속해 있으면, OpenClaw도 해당 그룹을 볼 수 있고 거기서 응답할 수 있습니다.

기본 동작:

그룹은 제한됨 (groupPolicy: "allowlist").
멘션 게이팅을 명시적으로 비활성화하지 않는 한 응답에 멘션이 필요합니다.

요약하면: 허용 목록에 등록된 발신자가 멘션을 통해 OpenClaw를 트리거할 수 있습니다.

TL;DR

DM 접근은 *.allowFrom으로 제어합니다.

그룹 접근은 *.groupPolicy + 허용 목록(*.groups, *.groupAllowFrom)으로 제어합니다.

응답 트리거는 멘션 게이팅(requireMention, /activation)으로 제어합니다.

그룹 메시지 처리 흐름:

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

Group message flow

원하는 동작에 따른 설정:

목표	설정할 항목
모든 그룹 허용, @멘션에만 응답	`groups: { "*": { requireMention: true } }`
모든 그룹 응답 비활성화	`groupPolicy: "disabled"`
특정 그룹만 허용	`groups: { "<group-id>": { ... } }` (`"*"` 키 없이)
그룹에서 본인만 트리거 가능	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

세션 키

그룹 세션은 agent:<agentId>:<channel>:group:<id> 세션 키를 사용합니다(방/채널은 agent:<agentId>:<channel>:channel:<id> 사용).
Telegram 포럼 토픽은 그룹 ID에 :topic:<threadId>를 추가하여 각 토픽이 고유한 세션을 갖습니다.
다이렉트 채팅은 메인 세션(또는 발신자별 세션으로 설정 가능)을 사용합니다.
그룹 세션에서는 하트비트가 건너뛰어집니다.

패턴: 개인 DM + 공개 그룹 (단일 에이전트)

네, DM이 “개인” 트래픽이고 그룹이 “공개” 트래픽인 경우 잘 작동합니다.

이유: 단일 에이전트 모드에서 DM은 일반적으로 메인 세션 키(agent:main:main)에 도달하고, 그룹은 항상 비메인 세션 키(agent:main:<channel>:group:<id>)를 사용합니다. mode: "non-main"으로 샌드박싱을 활성화하면 그룹 세션은 Docker에서 실행되고 메인 DM 세션은 호스트에서 유지됩니다.

이를 통해 하나의 에이전트 “두뇌”(공유 워크스페이스 + 메모리)를 가지되, 두 가지 실행 체계를 구성할 수 있습니다:

DM: 전체 도구 (호스트)
그룹: 샌드박스 + 제한된 도구 (Docker)

워크스페이스/페르소나를 완전히 분리해야 하는 경우(“개인”과 “공개”가 절대 섞이면 안 됨), 두 번째 에이전트 + 바인딩을 사용하세요. Multi-Agent Routing 참조.

예시 (DM은 호스트, 그룹은 샌드박스 + 메시징 전용 도구):

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // 그룹/채널은 비메인 -> 샌드박스
        scope: "session", // 가장 강력한 격리 (그룹/채널당 하나의 컨테이너)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // allow가 비어 있지 않으면 나머지는 모두 차단됨 (deny가 우선).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

“호스트 접근 없음” 대신 “그룹이 폴더 X만 볼 수 있게” 하려면 workspaceAccess: "none"을 유지하고 허용된 경로만 샌드박스에 마운트합니다:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

표시 레이블

UI 레이블은 사용 가능한 경우 displayName을 사용하며, <channel>:<token> 형식으로 포맷됩니다.
#room은 방/채널 전용이며, 그룹 채팅은 g-<slug>를 사용합니다(소문자, 공백 -> -, #@+._- 유지).

그룹 정책

채널별 그룹/방 메시지 처리 방식을 제어합니다:

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // 숫자 Telegram 사용자 ID (마법사가 @username을 변환 가능)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["[email protected]"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

정책	동작
`"open"`	그룹이 허용 목록을 우회하지만 멘션 게이팅은 적용됩니다.
`"disabled"`	모든 그룹 메시지를 완전히 차단합니다.
`"allowlist"`	설정된 허용 목록과 일치하는 그룹/방만 허용합니다.

참고:

groupPolicy는 멘션 게이팅(@멘션 필요)과 별개입니다.
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: groupAllowFrom을 사용합니다(폴백: 명시적 allowFrom).
DM 페어링 승인(*-allowFrom 저장소 항목)은 DM 접근에만 적용됩니다. 그룹 발신자 인가는 그룹 허용 목록에 명시적으로 유지됩니다.
Discord: 허용 목록은 channels.discord.guilds.<id>.channels를 사용합니다.
Slack: 허용 목록은 channels.slack.channels를 사용합니다.
Matrix: 허용 목록은 channels.matrix.groups(방 ID, 별칭 또는 이름)를 사용합니다. 발신자를 제한하려면 channels.matrix.groupAllowFrom을 사용하고, 방별 users 허용 목록도 지원됩니다.
그룹 DM은 별도로 제어됩니다(channels.discord.dm.*, channels.slack.dm.*).
Telegram 허용 목록은 사용자 ID("123456789", "telegram:123456789", "tg:123456789") 또는 사용자 이름("@alice" 또는 "alice")으로 매칭할 수 있으며, 접두사는 대소문자를 구분하지 않습니다.
기본값은 groupPolicy: "allowlist"이며, 그룹 허용 목록이 비어 있으면 그룹 메시지가 차단됩니다.
런타임 안전성: 제공자 블록이 완전히 없는 경우(channels.<provider> 부재), 그룹 정책은 channels.defaults.groupPolicy를 상속하는 대신 실패 시 차단 모드(일반적으로 allowlist)로 폴백합니다.

그룹 메시지 평가 순서(정신 모델):

groupPolicy (open/disabled/allowlist)
그룹 허용 목록 (*.groups, *.groupAllowFrom, 채널별 허용 목록)
멘션 게이팅 (requireMention, /activation)

멘션 게이팅 (기본)

그룹 메시지는 그룹별로 재정의하지 않는 한 멘션이 필요합니다. 기본값은 *.groups."*" 아래 각 하위 시스템에 있습니다.

봇 메시지에 대한 답장은 암묵적 멘션으로 인식됩니다(채널이 답장 메타데이터를 지원하는 경우). Telegram, WhatsApp, Slack, Discord, Microsoft Teams에 적용됩니다.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

참고:

mentionPatterns는 대소문자를 구분하지 않는 정규식입니다.
명시적 멘션을 제공하는 채널에서는 여전히 통과합니다. 패턴은 폴백입니다.
에이전트별 재정의: agents.list[].groupChat.mentionPatterns (여러 에이전트가 그룹을 공유할 때 유용).
멘션 게이팅은 멘션 감지가 가능한 경우(네이티브 멘션 또는 mentionPatterns 설정 시)에만 적용됩니다.
Discord 기본값은 channels.discord.guilds."*"에 있습니다(길드/채널별 재정의 가능).
그룹 히스토리 컨텍스트는 채널 간에 균일하게 래핑되며 보류 중인 메시지만(멘션 게이팅으로 건너뛴 메시지) 포함됩니다. 전역 기본값은 messages.groupChat.historyLimit를, 재정의는 channels.<channel>.historyLimit(또는 channels.<channel>.accounts.*.historyLimit)를 사용합니다. 0으로 비활성화합니다.

그룹/채널 도구 제한 (선택)

일부 채널 설정은 특정 그룹/방/채널 내에서 사용 가능한 도구를 제한할 수 있습니다.

tools: 전체 그룹에 대한 도구 허용/거부.
toolsBySender: 그룹 내 발신자별 재정의. 명시적 키 접두사 사용: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, "*" 와일드카드. 레거시 접두사 없는 키도 수용되며 id:로만 매칭됩니다.

해석 순서 (가장 구체적인 것이 우선):

그룹/채널 toolsBySender 매칭
그룹/채널 tools
기본값("*") toolsBySender 매칭
기본값("*") tools

예시 (Telegram):

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

참고:

그룹/채널 도구 제한은 전역/에이전트 도구 정책에 추가로 적용됩니다(deny가 우선).
일부 채널은 방/채널에 다른 중첩 구조를 사용합니다(예: Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

그룹 허용 목록

channels.whatsapp.groups, channels.telegram.groups 또는 channels.imessage.groups가 설정되면, 키가 그룹 허용 목록으로 작동합니다. "*"를 사용하여 기본 멘션 동작을 설정하면서 모든 그룹을 허용할 수 있습니다.

일반적인 의도 (복사/붙여넣기):

모든 그룹 응답 비활성화

{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}

특정 그룹만 허용 (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

모든 그룹 허용하되 멘션 필요 (명시적)

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

그룹에서 소유자만 트리거 가능 (WhatsApp)

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

활성화 (소유자 전용)

그룹 소유자는 그룹별 활성화를 전환할 수 있습니다:

/activation mention
/activation always

소유자는 channels.whatsapp.allowFrom(미설정 시 봇의 자체 E.164 번호)으로 결정됩니다. 명령은 독립된 메시지로 전송해야 합니다. 다른 채널에서는 현재 /activation을 무시합니다.

컨텍스트 필드

그룹 인바운드 페이로드는 다음을 설정합니다:

ChatType=group
GroupSubject (알려진 경우)
GroupMembers (알려진 경우)
WasMentioned (멘션 게이팅 결과)
Telegram 포럼 토픽은 MessageThreadId와 IsForum도 포함합니다.

에이전트 시스템 프롬프트는 새 그룹 세션의 첫 번째 턴에 그룹 안내를 포함합니다. 모델에게 사람처럼 응답하고, 마크다운 테이블을 피하며, 리터럴 \n 시퀀스를 입력하지 않도록 알려줍니다.

iMessage 관련 사항

라우팅이나 허용 목록 작성 시 chat_id:<id>를 선호합니다.
채팅 목록: imsg chats --limit 20.
그룹 응답은 항상 동일한 chat_id로 돌아갑니다.

WhatsApp 관련 사항

WhatsApp 전용 동작(히스토리 주입, 멘션 처리 세부사항)은 Group messages를 참조하세요.