OpenClaw 그룹 채팅 설정: 3분 만에 권한 및 멘션 제어하기

그룹(Groups)

OpenClaw는 Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo 등 다양한 플랫폼에서 그룹 채팅을 일관되게 처리합니다.

초보자 입문 (2분 소요)

OpenClaw는 사용자의 메시징 계정 위에서 직접 “실행”됩니다. 별도의 WhatsApp 봇 사용자가 존재하는 방식이 아닙니다. 여러분이 그룹에 참여하고 있다면, OpenClaw는 해당 그룹을 인식하고 그곳에서 응답할 수 있습니다.

기본 동작 방식은 다음과 같습니다:

그룹은 기본적으로 제한됩니다 (groupPolicy: "allowlist").
멘션 기능을 명시적으로 비활성화하지 않는 한, 응답을 위해서는 멘션이 필요합니다.

즉, 허용된 발신자만이 멘션을 통해 OpenClaw를 트리거할 수 있습니다.

요약

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

컨텍스트 가시성 및 허용 목록

그룹 안전성을 관리하기 위해 두 가지 제어 요소가 사용됩니다:

트리거 권한: 에이전트를 트리거할 수 있는 대상(groupPolicy, groups, groupAllowFrom, 채널별 허용 목록).
컨텍스트 가시성: 모델에 주입되는 보조 컨텍스트(응답 텍스트, 인용, 스레드 기록, 전달된 메타데이터).

기본적으로 OpenClaw는 일반적인 채팅 동작을 우선시하며 컨텍스트를 수신된 상태 그대로 유지합니다. 이는 허용 목록이 모든 인용이나 과거 스니펫에 대한 보편적인 삭제 경계가 아니라, 누가 작업을 트리거할 수 있는지를 결정한다는 것을 의미합니다.

현재 동작은 채널별로 다릅니다:

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

강화 방향(계획 중):

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

이 강화 모델이 모든 채널에 일관되게 구현되기 전까지는 플랫폼별로 차이가 있을 수 있습니다.

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"으로 샌드박스를 활성화하면, 그룹 세션은 구성된 샌드박스 백엔드에서 실행되고 메인 DM 세션은 호스트에서 유지됩니다. 별도의 백엔드를 선택하지 않으면 Docker가 기본값으로 사용됩니다.

이를 통해 하나의 에이전트 “두뇌”(공유 작업 공간 + 메모리)를 가지면서 두 가지 실행 환경을 구성할 수 있습니다:

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

작업 공간이나 페르소나를 완전히 분리해야 하는 경우(“개인”과 “공개”가 절대 섞이지 않아야 함), 두 번째 에이전트와 바인딩을 사용하세요. 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"을 유지하고 허용된 경로만 샌드박스에 마운트하세요:

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

표시 레이블(Display labels)

UI 레이블은 사용 가능한 경우 displayName을 사용하며, <channel>:<token> 형식으로 표시됩니다. #room은 방이나 채널을 위해 예약되어 있으며, 그룹 채팅은 g-<slug> 형식을 사용합니다(소문자 사용, 공백은 -로 대체, #@+._- 문자는 유지).

그룹 정책(Group policy)

채널별로 그룹 및 방 메시지를 처리하는 방식을 제어할 수 있습니다.

{
  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": { enabled: true },
        "#alias:example.org": { enabled: 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나 별칭을 사용하는 것이 좋으며, 참여 중인 방 이름 조회는 최선의 노력(best-effort)으로 수행되므로 확인되지 않은 이름은 런타임에 무시됩니다. 발신자를 제한하려면 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를 상속받는 대신 실패 시 차단(fail-closed) 모드(일반적으로 allowlist)로 작동합니다.

빠른 이해를 위한 평가 순서(그룹 메시지 평가 순서):

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

멘션 게이팅 (기본값)

그룹 메시지는 별도로 설정을 변경하지 않는 한 멘션이 필요하며, 기본값은 각 하위 시스템의 *.groups."*" 설정에서 관리합니다. OpenClaw는 멘션 게이팅 기능을 통해 그룹 내 대화 흐름을 효율적으로 제어합니다.

채널이 답장 메타데이터를 지원하는 경우, 봇 메시지에 답장하는 것은 암시적인 멘션으로 간주됩니다. 봇 메시지를 인용하는 것 또한 인용 메타데이터를 노출하는 채널에서 암시적인 멘션으로 처리될 수 있으며, 현재 이를 지원하는 내장 채널로는 Telegram, WhatsApp, Slack, Discord, Microsoft Teams, ZaloUser가 있습니다.

{
  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."*"에 위치하며, 길드나 채널별로 재정의할 수 있습니다.
그룹 기록 컨텍스트는 채널 전반에 걸쳐 균일하게 래핑되며 **대기 중인 메시지(pending-only)**에만 적용됩니다(멘션 게이팅으로 인해 건너뛴 메시지). 전역 기본값은 messages.groupChat.historyLimit를 사용하고, 재정의가 필요한 경우 channels.<channel>.historyLimit 또는 channels.<channel>.accounts.*.historyLimit를 사용하세요. 0으로 설정하면 비활성화됩니다.

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

일부 채널 설정은 특정 그룹, 대화방 또는 채널 내에서 사용할 수 있는 도구를 제한하는 기능을 지원합니다. OpenClaw의 도구 제한 설정을 통해 특정 환경에서 허용하거나 거부할 도구를 지정할 수 있습니다.

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

참고 사항:

그룹/채널 도구 제한은 전역 또는 에이전트 도구 정책에 추가로 적용되며, 거부 설정이 항상 우선합니다.
일부 채널은 대화방이나 채널을 위해 다른 중첩 구조를 사용합니다(예: Discord의 guilds.*.channels.*, Slack의 channels.*, Microsoft Teams의 teams.*.channels.*).

그룹 허용 목록 (Group allowlists)

channels.whatsapp.groups, channels.telegram.groups 또는 channels.imessage.groups를 설정할 때, 해당 키들은 그룹 허용 목록으로 작동합니다. 기본 멘션 동작을 설정하면서 모든 그룹을 허용하려면 "*"를 사용하세요.

많은 분이 혼동하시는 점이 있는데, DM 페어링 승인과 그룹 승인은 서로 다릅니다. DM 페어링을 지원하는 채널의 경우, 페어링 저장소는 DM만 잠금 해제합니다. 그룹 명령어는 여전히 groupAllowFrom과 같은 설정의 허용 목록이나 해당 채널에 문서화된 설정 폴백(fallback)을 통해 명시적인 그룹 발신자 승인을 받아야 합니다.

자주 사용하는 설정 예시입니다 (복사해서 사용하세요):

모든 그룹 응답 비활성화

{
  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 mention
/activation always

소유자는 channels.whatsapp.allowFrom 설정(설정되지 않은 경우 봇 자신의 E.164 번호)에 의해 결정됩니다. 이 명령어는 독립된 메시지로 전송해야 합니다. 현재 다른 인터페이스에서는 /activation 명령어를 무시합니다.

컨텍스트 필드(Context fields)

인바운드 페이로드 세트에는 다음과 같은 정보가 포함됩니다.

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

채널별 참고 사항은 다음과 같습니다.

BlueBubbles는 그룹 게이팅을 통과한 후, 로컬 연락처 데이터베이스를 사용하여 이름이 지정되지 않은 macOS 그룹 참가자 정보를 선택적으로 보강할 수 있습니다. 이 기능은 기본적으로 꺼져 있습니다.

에이전트 시스템 프롬프트에는 새로운 그룹 세션의 첫 번째 턴에서 그룹 소개가 포함됩니다. 이는 모델에게 사람처럼 응답하고, Markdown 표를 피하며, 빈 줄을 최소화하고, 일반적인 채팅 간격을 유지하며, \n 시퀀스를 그대로 입력하지 않도록 상기시킵니다.

iMessage 세부 정보(iMessage specifics)

라우팅이나 허용 목록을 설정할 때는 chat_id:<id> 형식을 사용하는 것이 좋습니다.

채팅 목록 확인: imsg chats --limit 20
그룹 답장은 항상 동일한 chat_id로 전송됩니다.

WhatsApp 세부 정보(WhatsApp specifics)

WhatsApp 전용 동작(히스토리 주입, 멘션 처리 세부 정보 등)은 그룹 메시지 문서를 확인해 주세요.

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.