그룹

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

초보자용 소개(2분)

OpenClaw는 사용자의 자체 메시징 계정에서 “동작”합니다. 별도의 WhatsApp 봇 사용자는 없습니다. 당신이 그룹에 있다면, OpenClaw는 그 그룹을 볼 수 있고 այնտեղ에서 응답할 수 있습니다. 기본 동작:

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

즉, allowlist에 있는 발신자는 OpenClaw를 멘션하여 트리거할 수 있습니다.

요약

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

그룹 접근은 *.groupPolicy + allowlist(*.groups, *.groupAllowFrom)로 제어됩니다.

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

빠른 흐름(그룹 메시지에 어떤 일이 일어나는지):

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

컨텍스트 가시성과 allowlist

그룹 안전성에는 두 가지 서로 다른 제어가 관련됩니다.

트리거 권한 부여: 누가 에이전트를 트리거할 수 있는지(groupPolicy, groups, groupAllowFrom, 채널별 allowlist)
컨텍스트 가시성: 어떤 보조 컨텍스트가 모델에 주입되는지(답장 텍스트, 인용, 스레드 기록, 전달된 메타데이터)

기본적으로 OpenClaw는 일반적인 채팅 동작을 우선하며 컨텍스트를 대부분 수신된 그대로 유지합니다. 이는 allowlist가 주로 누가 작업을 트리거할 수 있는지를 결정하며, 인용되거나 기록에 남은 모든 조각에 대한 보편적인 리다크션 경계는 아니라는 뜻입니다. 현재 동작은 채널별로 다릅니다.

일부 채널은 특정 경로에서 이미 보조 컨텍스트에 발신자 기반 필터링을 적용합니다(예: Slack 스레드 시딩, Matrix 답장/스레드 조회).
다른 채널은 여전히 인용/답장/전달 컨텍스트를 수신된 그대로 전달합니다.

하드닝 방향(계획됨):

contextVisibility: "all"(기본값)은 현재의 수신 그대로 동작을 유지합니다.
contextVisibility: "allowlist"는 보조 컨텍스트를 allowlist 발신자로 필터링합니다.
contextVisibility: "allowlist_quote"는 allowlist에 하나의 명시적인 인용/답장 예외를 추가한 것입니다.

이 하드닝 모델이 채널 전반에 걸쳐 일관되게 구현되기 전까지는 표면별 차이가 있을 수 있습니다.

다음을 원한다면…

목표	설정할 값
모든 그룹을 허용하되 @멘션에서만 응답	`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>를 추가합니다.
직접 채팅은 메인 세션을 사용합니다(또는 구성된 경우 발신자별 세션).
Heartbeat는 그룹 세션에서 건너뜁니다.

패턴: 개인 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", // groups/channels are non-main -> sandboxed
        scope: "session", // strongest isolation (one container per group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // If allow is non-empty, everything else is blocked (deny still wins).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

“호스트 접근 없음” 대신 “그룹은 폴더 X만 볼 수 있음”을 원하나요? workspaceAccess: "none"을 유지하고 allowlist된 경로만 샌드박스에 마운트하세요.

{
  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"], // numeric Telegram user id (wizard can resolve @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["user@org.com"],
    },
    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"`	그룹이 allowlist를 우회하지만 멘션 게이팅은 계속 적용됩니다.
`"disabled"`	모든 그룹 메시지를 완전히 차단합니다.
`"allowlist"`	구성된 allowlist와 일치하는 그룹/룸만 허용합니다.

참고:

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

빠른 멘탈 모델(그룹 메시지 평가 순서):

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

멘션 게이팅(기본값)

그룹 메시지는 그룹별로 재정의하지 않는 한 멘션이 필요합니다. 기본값은 각 서브시스템 아래의 *.groups."*"에 있습니다. 봇 메시지에 답장하는 것도 암묵적 멘션으로 계산됩니다(채널이 답장 메타데이터를 지원하는 경우). 이는 Telegram, WhatsApp, Slack, Discord, Microsoft Teams에 적용됩니다.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { 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."*"에 있습니다(guild/channel별 재정의 가능).
그룹 기록 컨텍스트는 채널 전반에서 일관되게 래핑되며 pending-only입니다(멘션 게이팅으로 건너뛴 메시지). 전역 기본값에는 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.*, Microsoft Teams teams.*.channels.*).

그룹 allowlist

channels.whatsapp.groups, channels.telegram.groups, 또는 channels.imessage.groups가 구성되면 해당 키가 그룹 allowlist 역할을 합니다. 모든 그룹을 허용하면서 기본 멘션 동작을 계속 설정하려면 "*"를 사용하세요. 자주 발생하는 혼동: DM 페어링 승인은 그룹 권한 부여와 동일하지 않습니다. DM 페어링을 지원하는 채널에서 페어링 저장소는 DM만 잠금 해제합니다. 그룹 명령은 여전히 groupAllowFrom 또는 해당 채널에 문서화된 구성 대체 항목 같은 구성 allowlist를 통한 명시적인 그룹 발신자 권한 부여가 필요합니다. 일반적인 의도(복사/붙여넣기):

모든 그룹 응답 비활성화

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

특정 그룹만 허용(WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}

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

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

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

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

Activation(소유자 전용)

그룹 소유자는 그룹별 activation을 전환할 수 있습니다.

/activation mention
/activation always

소유자는 channels.whatsapp.allowFrom으로 결정됩니다(설정되지 않은 경우 봇 자신의 E.164). 명령은 독립된 메시지로 보내세요. 현재 다른 표면은 /activation을 무시합니다.

컨텍스트 필드

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

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

채널별 참고 사항:

BlueBubbles는 GroupMembers를 채우기 전에 로컬 Contacts 데이터베이스에서 이름 없는 macOS 그룹 참가자 정보를 선택적으로 보강할 수 있습니다. 이는 기본적으로 꺼져 있으며 일반적인 그룹 게이팅을 통과한 뒤에만 실행됩니다.

에이전트 시스템 프롬프트는 새 그룹 세션의 첫 턴에 그룹 소개를 포함합니다. 여기서는 인간처럼 응답하고, Markdown 표를 피하고, 리터럴 \n 시퀀스를 입력하지 말 것을 모델에 상기시킵니다.

iMessage 세부 사항

라우팅 또는 allowlist에는 chat_id:<id> 사용을 권장합니다.
채팅 나열: imsg chats --limit 20
그룹 응답은 항상 동일한 chat_id로 다시 전송됩니다.

WhatsApp 세부 사항

WhatsApp 전용 동작(기록 주입, 멘션 처리 세부 정보)은 Group messages를 참조하세요.

Overview

Messaging platforms

Configuration

그룹

그룹

초보자용 소개(2분)

컨텍스트 가시성과 allowlist

세션 키

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

표시 라벨

그룹 정책

멘션 게이팅(기본값)

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

그룹 allowlist

Activation(소유자 전용)

컨텍스트 필드

iMessage 세부 사항

WhatsApp 세부 사항

Overview

Messaging platforms

Configuration

​그룹

​초보자용 소개(2분)

​컨텍스트 가시성과 allowlist

​세션 키

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

​표시 라벨

​그룹 정책

​멘션 게이팅(기본값)

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

​그룹 allowlist

​Activation(소유자 전용)

​컨텍스트 필드

​iMessage 세부 사항

​WhatsApp 세부 사항

그룹

초보자용 소개(2분)

컨텍스트 가시성과 allowlist

세션 키

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

표시 라벨

그룹 정책

멘션 게이팅(기본값)

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

그룹 allowlist

Activation(소유자 전용)

컨텍스트 필드

iMessage 세부 사항

WhatsApp 세부 사항