그룹

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

# 초보자 소개(2분)

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

기본 동작:

• 그룹은 제한됩니다(groupPolicy: "allowlist").
• 명시적으로 멘션 게이팅을 비활성화하지 않는 한, 응답에는 멘션이 필요합니다.
• 그룹/채널의 일반 최종 응답은 기본적으로 비공개입니다. 방에 보이는 출력은 message 도구를 사용합니다.

해석: 허용 목록에 있는 발신자는 OpenClaw를 멘션하여 트리거할 수 있습니다.

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

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

# 보이는 응답

그룹/채널 방에서 OpenClaw의 기본값은 messages.groupChat.visibleReplies: "message_tool"입니다. openclaw doctor --fix는 이 값을 생략한 구성된 채널 설정에 이 기본값을 기록합니다. 즉, 에이전트는 여전히 턴을 처리하고 메모리/세션 상태를 업데이트할 수 있지만, 일반 최종 답변은 방에 자동으로 게시되지 않습니다. 보이게 말하려면 에이전트가 message(action=send)를 사용합니다.

이 기본값은 도구를 안정적으로 호출하는 모델/런타임에 의존합니다. 로그에 어시스턴트 텍스트가 표시되지만 didSendViaMessagingTool: false라면, 모델이 메시지 도구를 호출하는 대신 비공개로 답변한 것입니다. 이는 Discord/Slack/Telegram 전송 실패가 아닙니다. 그룹/채널 세션에는 도구 호출이 안정적인 모델을 사용하거나, messages.groupChat.visibleReplies: "automatic"을 설정하여 기존의 보이는 최종 응답을 복원하세요.

활성 도구 정책에서 메시지 도구를 사용할 수 없으면 OpenClaw는 응답을 조용히 억제하는 대신 자동 보이는 응답으로 폴백합니다. openclaw doctor는 이 불일치에 대해 경고합니다.

직접 채팅과 기타 모든 소스 턴에는 messages.visibleReplies: "message_tool"을 사용하여 동일한 도구 전용 보이는 응답 동작을 전역으로 적용하세요. 하네스도 이를 미설정 기본값으로 선택할 수 있으며, Codex 하네스는 Codex 모드 직접 채팅에서 이렇게 합니다. messages.groupChat.visibleReplies는 그룹/채널 방에 대한 더 구체적인 오버라이드로 남습니다.

이는 대부분의 대기 모드 턴에서 모델이 NO_REPLY로 답하도록 강제하던 이전 패턴을 대체합니다. 도구 전용 모드에서 보이는 동작을 하지 않는다는 것은 단순히 메시지 도구를 호출하지 않는다는 뜻입니다.

도구 전용 모드에서 에이전트가 작업하는 동안에도 입력 표시기는 계속 전송됩니다. 이러한 턴에서는 에이전트가 메시지 도구를 호출할지 결정하기 전에 일반 어시스턴트 메시지 텍스트가 없을 수 있으므로, 기본 그룹 입력 모드는 "message"에서 "instant"로 업그레이드됩니다. 명시적인 입력 모드 설정은 여전히 우선합니다.

그룹/채널 방에서 기존 자동 최종 응답을 복원하려면:

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

파일이 저장되면 Gateway는 messages 설정을 핫 리로드합니다. 배포에서 파일 감시 또는 설정 리로드가 비활성화된 경우에만 다시 시작하세요.

모든 소스 채팅의 보이는 출력이 메시지 도구를 통해 전달되도록 요구하려면:

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

네이티브 슬래시 명령(Discord, Telegram 및 네이티브 명령 지원이 있는 기타 표면)은 visibleReplies: "message_tool"을 우회하고 항상 보이게 응답하므로 채널 네이티브 명령 UI가 예상하는 응답을 받습니다. 이는 검증된 네이티브 명령 턴에만 적용됩니다. 텍스트로 입력한 /... 명령과 일반 채팅 턴은 여전히 구성된 그룹 기본값을 따릅니다.

# 컨텍스트 표시와 허용 목록

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

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

기본적으로 OpenClaw는 일반 채팅 동작을 우선시하며 컨텍스트를 대부분 수신된 그대로 유지합니다. 즉, 허용 목록은 주로 누가 작업을 트리거할 수 있는지를 결정하며, 인용되거나 과거에 기록된 모든 스니펫에 대한 보편적인 수정 경계는 아닙니다.

원하는 경우...

재사용 가능한 발신자 허용 목록은 액세스 그룹을 참조하세요.

# 세션 키

• 그룹 세션은 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"으로 샌드박싱을 활성화하면, 해당 그룹 세션은 구성된 샌드박스 백엔드에서 실행되고 메인 DM 세션은 호스트에 남습니다. 백엔드를 선택하지 않으면 Docker가 기본 백엔드입니다.

이를 통해 하나의 에이전트 "두뇌"(공유 워크스페이스 + 메모리)를 사용하면서도 두 가지 실행 태세를 갖게 됩니다.

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

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

관련 항목:

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

# 표시 레이블

• 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: ["[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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

빠르게 이해하는 모델(그룹 메시지 평가 순서):

# 멘션 게이팅(기본값)

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

채널이 답장 메타데이터를 지원하는 경우, 봇 메시지에 답장하면 암시적 멘션으로 간주됩니다. 인용 메타데이터를 노출하는 채널에서는 봇 메시지를 인용하는 것도 암시적 멘션으로 간주될 수 있습니다. 현재 기본 제공 사례에는 Telegram, WhatsApp, Slack, Discord, Microsoft Teams, ZaloUser가 포함됩니다.

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

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

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

• tools: 전체 그룹에 대해 도구를 허용/거부합니다.
• toolsBySender: 그룹 내 보낸 사람별 재정의입니다. 명시적 키 접두사를 사용하세요: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, "*" 와일드카드. 레거시 무접두사 키도 여전히 허용되며 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: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

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

{
  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도 포함됩니다.

채널별 참고 사항:

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

에이전트 시스템 프롬프트는 새 그룹 세션의 첫 턴에 그룹 소개를 포함합니다. 이는 모델에게 사람처럼 응답하고, Markdown 표를 피하며, 빈 줄을 최소화하고 일반적인 채팅 간격을 따르며, 리터럴 \n 시퀀스를 입력하지 않도록 상기시킵니다. 채널에서 가져온 그룹 이름과 참가자 레이블은 인라인 시스템 지시가 아니라 펜스 처리된 신뢰할 수 없는 메타데이터로 렌더링됩니다.

# iMessage 세부 사항

• 라우팅하거나 허용 목록에 추가할 때는 chat_id:<id>를 선호하세요.
• 채팅 목록: imsg chats --limit 20.
• 그룹 답장은 항상 같은 chat_id로 돌아갑니다.

# WhatsApp 시스템 프롬프트

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

# WhatsApp 세부 사항

WhatsApp 전용 동작(기록 주입, 멘션 처리 세부 정보)은 그룹 메시지를 참조하세요.

# 관련 항목

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