그룹

OpenClaw는 Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo를 비롯하여 그룹을 지원하는 모든 채널에 동일한 그룹 규칙을 적용합니다.

에이전트가 명시적으로 표시되는 메시지를 보내지 않는 한 조용히 컨텍스트만 제공해야 하는 상시 활성 방에 대해서는 주변 방 이벤트를 참조하십시오.

초보자 소개(2분)

OpenClaw는 사용자의 메시징 계정에서 "동작"합니다. 별도의 WhatsApp 봇 사용자는 없습니다. 사용자가 그룹에 속해 있으면 OpenClaw는 해당 그룹을 확인하고 그곳에서 응답할 수 있습니다.

기본 동작:

• 그룹은 제한됩니다(groupPolicy: "allowlist"). 그룹 발신자는 허용 목록에 추가될 때까지 차단됩니다.
• 그룹의 멘션 게이팅을 비활성화하지 않는 한 응답하려면 멘션이 필요합니다.
• 최종 응답 텍스트는 방에 자동으로 게시됩니다(visibleReplies: "automatic").

즉, 허용 목록에 있는 발신자는 OpenClaw를 멘션하여 작동시킬 수 있습니다.

빠른 흐름(그룹 메시지가 처리되는 과정):

groupPolicy? disabled -> 삭제groupPolicy? allowlist -> 그룹이 허용되었는가? 아니요 -> 삭제requireMention? yes -> 멘션되었는가? 아니요 -> 컨텍스트용으로만 저장멘션/응답/명령/DM -> 사용자 요청상시 활성 그룹 대화 -> 사용자 요청 또는 구성된 경우 방 이벤트

표시되는 응답

일반적인 그룹/채널 요청의 경우 OpenClaw의 기본값은 messages.groupChat.visibleReplies: "automatic"이며, 최종 어시스턴트 텍스트가 표시되는 응답으로 방에 게시됩니다.

공유 방에서 에이전트가 message(action=send)을 호출하여 언제 말할지 결정하도록 하려면 messages.groupChat.visibleReplies: "message_tool"을 사용하십시오. 이는 도구를 안정적으로 사용하는 모델(예: GPT-5.6 Sol)에서 가장 잘 작동합니다. 모델이 도구를 사용하지 않고 실질적인 최종 텍스트를 반환하면 OpenClaw는 해당 텍스트를 방에 게시하지 않고 비공개로 유지합니다.

도구 전용 전달을 안정적으로 따르지 않는 모델이나 런타임에는 "automatic"을 사용하십시오. 일반적인 최종 텍스트는 방에 직접 게시되며, 에이전트는 최종 텍스트와 함께 전달할 수 없는 파일, 이미지 또는 기타 첨부 파일에 대해 여전히 message(action=send)을 호출할 수 있습니다.

활성 도구 정책에서 메시지 도구를 사용할 수 없으면 OpenClaw는 응답을 조용히 숨기는 대신 표시되는 자동 응답으로 대체합니다. openclaw doctor은 이러한 불일치를 경고합니다.

직접 채팅 및 기타 모든 소스 이벤트에는 messages.visibleReplies: "message_tool"이 동일한 도구 전용 동작을 전역으로 적용하며, messages.groupChat.visibleReplies은 그룹/채널 방에 대한 더 구체적인 재정의로 유지됩니다. 내부 WebChat 직접 턴은 Pi와 Codex가 동일한 표시 응답 계약을 받도록 기본적으로 최종 응답을 자동 전달합니다.

도구 전용 모드는 대부분의 잠복 모드 턴에서 모델이 NO_REPLY으로 응답하도록 강제하던 이전 패턴을 대체합니다. 도구 전용 모드에서는 프롬프트가 NO_REPLY 계약을 정의하지 않습니다. 아무것도 표시하지 않는다는 것은 단순히 메시지 도구를 호출하지 않는다는 뜻입니다.

Plugin이 소유하는 대화 바인딩은 예외입니다. Plugin이 스레드를 바인딩하고 수신 턴을 인계하면 Plugin이 반환한 응답이 표시되는 바인딩 응답이 되며, message(action=send)은 필요하지 않습니다. 해당 응답은 비공개 모델 최종 텍스트가 아니라 Plugin 런타임 출력입니다.

직접 그룹 요청에는 입력 중 표시기가 계속 전송됩니다. 주변 상시 활성 방 이벤트가 활성화된 경우 에이전트가 메시지 도구를 호출하지 않는 한 엄격하고 조용하게 유지됩니다.

세션은 기본적으로 자세한 도구/진행 상황 요약을 숨깁니다. 디버깅하는 동안 현재 세션에 이를 표시하려면 /verbose on(또는 /verbose full)을 사용하고, 최종 응답만 표시하는 동작으로 돌아가려면 /verbose off을 사용하십시오. 상세 상태는 세션별로 적용되며 직접 채팅, 그룹, 채널 및 포럼 주제에서 동일하게 작동합니다.

멘션되지 않은 상시 활성 그룹 대화를 사용자 요청 대신 조용한 방 컨텍스트로 제출하려면 주변 방 이벤트를 사용하십시오.

{  messages: {    groupChat: {      unmentionedInbound: "room_event",    },  },}

기본값은 unmentionedInbound: "user_request"입니다. 멘션된 메시지, 명령, 중단 요청 및 DM은 사용자 요청으로 유지됩니다.

그룹/채널 요청의 표시 출력을 메시지 도구를 통해서만 전달하도록 요구하려면 다음과 같이 설정하십시오.

{  messages: {    groupChat: {      visibleReplies: "message_tool",    },  },}

모든 소스 채팅에 이를 요구하려면 다음과 같이 설정하십시오.

{  messages: {    visibleReplies: "message_tool",  },}

파일을 저장하면 Gateway가 재시작 없이 messages 구성 변경 사항을 적용합니다. 구성 다시 로드가 비활성화된 경우(gateway.reload.mode: "off")에만 재시작하십시오.

명령 턴은 visibleReplies: "message_tool"을 우회하고 항상 표시되는 응답을 보냅니다. 네이티브 슬래시 명령(Discord, Telegram 및 네이티브 명령을 지원하는 기타 화면)과 승인된 텍스트 /... 명령은 모두 소스 채팅에 응답을 게시합니다. 그룹에서 승인되지 않은 텍스트 /... 턴은 메시지 도구 전용으로 유지되며, 일반 채팅 턴은 구성된 기본값을 따릅니다.

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

그룹 안전에는 서로 다른 두 가지 제어 기능이 관여합니다.

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

기본적으로 OpenClaw는 컨텍스트를 수신한 그대로 유지합니다. 허용 목록은 모델이 어떤 인용 또는 기록 조각을 볼 수 있는지가 아니라, 누가 작업을 트리거할 수 있는지를 결정합니다. 보조 컨텍스트도 필터링하려면 contextVisibility을 설정하십시오.

채널별(channels.<channel>.contextVisibility), 계정별(channels.<channel>.accounts.<accountId>.contextVisibility) 또는 전역(channels.defaults.contextVisibility)으로 설정하십시오. 보조 컨텍스트를 가져오는 채널(Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp)은 수신 컨텍스트를 구성할 때 이 정책을 적용합니다. 알 수 없는 정책 조합은 안전을 위해 차단되며 컨텍스트를 생략합니다.

원하는 작업...

재사용 가능한 발신자 허용 목록에 대해서는 액세스 그룹을 참조하십시오.

세션 키

• 그룹 세션은 agent:<agentId>:<channel>:group:<id> 세션 키를 사용합니다(방/채널은 agent:<agentId>:<channel>:channel:<id> 사용).
• Telegram 포럼 주제는 그룹 ID에 :topic:<threadId>을 추가하여 각 주제가 자체 세션을 갖도록 합니다.
• 직접 채팅은 기본 세션을 사용합니다(session.dmScope이 구성된 경우 발신자별 세션 사용).
• Heartbeat는 구성된 Heartbeat 세션(기본값: 에이전트 기본 세션)에서 실행됩니다. 그룹 세션은 자체 Heartbeat를 실행하지 않습니다.

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

예. "개인" 트래픽이 DM이고 "공개" 트래픽이 그룹인 경우 효과적으로 작동합니다.

이유: 단일 에이전트 모드에서 DM은 일반적으로 기본 세션 키(agent:main:main)로 전달되지만, 그룹은 항상 기본이 아닌 세션 키(agent:main:<channel>:group:<id>)를 사용합니다. mode: "non-main"을 사용하여 샌드박싱을 활성화하면 해당 그룹 세션은 구성된 샌드박스 백엔드에서 실행되는 반면, 기본 DM 세션은 호스트에서 계속 실행됩니다. 백엔드를 선택하지 않으면 Docker가 기본 백엔드입니다.

따라서 하나의 에이전트 "두뇌"(공유 작업 공간 + 메모리)를 사용하면서 두 가지 실행 방식을 적용할 수 있습니다.

• DM: 모든 도구(호스트)
• 그룹: 샌드박스 + 제한된 도구

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // 그룹/채널은 기본이 아님 -> 샌드박스에서 실행        scope: "session", // 가장 강력한 격리(그룹/채널마다 하나의 컨테이너)        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // 허용 목록이 비어 있지 않으면 다른 모든 항목이 차단됩니다(거부가 여전히 우선함).        allow: ["group:messaging", "group:sessions"],        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],      },    },  },}

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",        docker: {          binds: [            // 호스트 경로:컨테이너 경로:모드            "/home/user/FriendsShared:/data:ro",          ],        },      },    },  },}

관련 항목:

• 구성 키 및 기본값: Gateway 구성
• 도구가 차단되는 이유 디버깅: 샌드박스와 도구 정책 및 권한 상승 비교
• 바인드 마운트 세부 정보: 샌드박싱

표시 레이블

• UI 레이블은 사용 가능한 경우 displayName을 사용하며 <channel>:<token> 형식으로 지정됩니다.
• #room은 방/채널용으로 예약되어 있습니다. 그룹 채팅은 g-<slug>을 사용합니다(소문자, 공백 -> -, #@+._- 유지). 매우 긴 불투명 ID는 전체 경로 ID를 UI에 노출하는 대신 안정적인 토큰으로 단축됩니다.

그룹 정책

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

{  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: ["user@org.com"],    },    discord: {      groupPolicy: "allowlist",      guilds: {        GUILD_ID: { channels: { help: { enabled: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { enabled: true } },    },    matrix: {      groupPolicy: "allowlist",      groupAllowFrom: ["@owner:example.org"],      groups: {        "!roomId:example.org": { enabled: true },        "#alias:example.org": { enabled: true },      },    },  },}

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

멘션 게이팅(기본값)

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

채널이 답장 메타데이터를 제공하는 경우 봇 메시지에 답장하면 암시적 멘션으로 간주됩니다. 인용 메타데이터를 제공하는 채널에서는 봇 메시지를 인용하는 것도 멘션으로 간주될 수 있습니다. 현재 기본 제공 사례는 Discord, Microsoft Teams, QQBot, Slack, Telegram, WhatsApp 및 Zalo 개인 계정입니다.

{  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은 정규식 대체 트리거입니다. 플랫폼이 기본 봇 멘션을 제공하지 않거나 openclaw: 같은 일반 텍스트를 멘션으로 간주하려는 경우 사용하십시오. 플랫폼 기본 멘션은 별개입니다. Discord, Slack, Telegram, Matrix, Signal 또는 다른 채널이 메시지에서 봇이 명시적으로 멘션되었음을 확인할 수 있으면, 구성된 정규식 패턴이 거부된 경우에도 해당 기본 멘션이 트리거됩니다.

기본적으로 구성된 멘션 패턴은 채널이 공급자 및 대화 정보를 멘션 감지에 전달하는 모든 곳에 적용됩니다. 광범위한 패턴으로 인해 모든 그룹에서 에이전트가 활성화되지 않도록 하려면 channels.<channel>.mentionPatterns을 사용하여 채널별로 범위를 지정하십시오.

채널에서 정규식 멘션 패턴을 기본적으로 끄고 특정 방에서만 사용하려면 mode: "deny"을 사용한 다음 allowIn으로 특정 방을 포함하십시오.

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b", "\\bops bot\\b"],    },  },  channels: {    slack: {      mentionPatterns: {        mode: "deny",        allowIn: ["C0123OPS"],      },    },  },}

정규식 멘션 패턴을 광범위하게 적용하려면 기본값 mode: "allow"을 사용하거나 mode을 생략한 다음, denyIn을 사용하여 메시지가 많은 방에서는 끄십시오.

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b"],    },  },  channels: {    telegram: {      mentionPatterns: {        denyIn: ["-1001234567890", "-1001234567890:topic:42"],      },    },  },}

정책 결정:

현재 지원되는 범위 지정 정규식 정책:

채널이 여러 계정을 지원하는 경우 계정 수준 채널 구성에서 channels.<channel>.accounts.<accountId>.mentionPatterns 아래에 동일한 정책을 설정할 수 있습니다. 해당 계정에서는 계정 정책이 최상위 채널 정책보다 우선합니다.

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

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

• tools: 전체 그룹에 대해 도구를 허용/거부합니다(allow, alsoAllow, deny; 거부가 우선함).
• toolsBySender: 그룹 내 발신자별 재정의입니다. 명시적 키 접두사 channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> 및 "*" 와일드카드를 사용하십시오. 채널 ID에는 정식 OpenClaw 채널 ID를 사용합니다. teams 같은 별칭은 msteams로 정규화됩니다. 접두사가 없는 레거시 키도 계속 허용되지만 id:으로만 일치하며 지원 중단 경고가 기록됩니다.

결정 순서(가장 구체적인 항목이 우선함):

예시(Telegram):

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

그룹 허용 목록

channels.whatsapp.groups, channels.telegram.groups 또는 channels.imessage.groups이 구성된 경우 키가 그룹 허용 목록으로 작동합니다. 기본 멘션 동작을 설정하면서 모든 그룹을 허용하려면 "*"을 사용하십시오.

일반적인 사용 목적(복사/붙여넣기):

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

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

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

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

활성화(소유자 전용)

그룹 소유자는 독립된 메시지로 그룹별 활성화를 전환할 수 있습니다.

• /activation mention
• /activation always

/activation은 핵심 소유자 제한 명령이며 그룹 채팅에만 적용됩니다. 소유자는 발신자가 commands.ownerAllowFrom과 일치함을 의미합니다. 채널 allowFrom 목록은 일반적인 채널 및 명령 액세스만 제어합니다. 저장된 모드는 이를 참조하는 채널(Google Chat, QQBot, Telegram, WhatsApp)에서 해당 그룹의 requireMention을 재정의하며, 그룹 시스템 프롬프트 소개는 모든 곳에서 활성 모드를 반영합니다.

컨텍스트 필드

그룹 수신 페이로드는 다음을 설정합니다.

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

에이전트 시스템 프롬프트에는 새 그룹 세션의 첫 번째 턴에 그룹 소개가 포함됩니다(/activation 변경 후에도 포함됨). 이는 모델이 사람처럼 응답하고, 빈 줄을 최소화하며 일반적인 채팅 간격을 따르고, 리터럴 \n 시퀀스를 입력하지 않도록 상기시킵니다. 선언된 표 모드가 네이티브 또는 원시 표를 보존하지 않는 채널에서는 Markdown 표 사용도 권장하지 않습니다. 채널에서 가져온 그룹 이름과 참여자 레이블은 인라인 시스템 지침이 아니라 펜스로 구분된 신뢰할 수 없는 메타데이터로 렌더링됩니다.

iMessage 세부 사항

• 라우팅하거나 허용 목록에 추가할 때는 chat_id:<id>을 사용하는 것이 좋습니다.
• 채팅 목록 조회: imsg chats --limit 20.
• 그룹 답장은 항상 동일한 chat_id으로 전송됩니다.

WhatsApp 시스템 프롬프트

그룹 및 직접 프롬프트 결정, 와일드카드 동작, 계정 재정의 의미 체계를 포함한 표준 WhatsApp 시스템 프롬프트 규칙은 WhatsApp을 참조하십시오.

WhatsApp 세부 사항

WhatsApp 전용 동작(기록 삽입, 멘션 처리 세부 사항)은 그룹 메시지를 참조하십시오.

관련 항목

• 브로드캐스트 그룹
• 채널 라우팅
• 그룹 메시지
• 페어링