Configuration

WhatsApp 그룹 메시지

크로스 채널 그룹 모델(Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo)은 그룹을 참고하세요. 이 페이지는 해당 모델 위에서 WhatsApp에만 적용되는 동작을 다룹니다. 활성화, 그룹 허용 목록, 그룹별 세션 키, 대기 중 메시지 컨텍스트 주입입니다.

목표: OpenClaw가 WhatsApp 그룹에 머물다가 호출될 때만 깨어나고, 해당 스레드를 개인 DM 세션과 분리해 유지하도록 합니다.

동작

활성화 모드: mention(기본값) 또는 always. mention은 호출이 필요합니다(실제 WhatsApp @멘션인 mentionedJids, 안전한 정규식 패턴, 또는 텍스트 어디에든 있는 봇의 E.164). always는 모든 메시지에서 에이전트를 깨우지만, 의미 있는 가치를 더할 수 있을 때만 답해야 합니다. 그렇지 않으면 정확한 무응답 토큰 NO_REPLY / no_reply를 반환합니다. 기본값은 설정(channels.whatsapp.groups)에서 지정할 수 있고, /activation으로 그룹별 재정의가 가능합니다. channels.whatsapp.groups가 설정되어 있으면 그룹 허용 목록으로도 동작합니다(모두 허용하려면 "*" 포함).
그룹 정책: channels.whatsapp.groupPolicy는 그룹 메시지를 허용할지 제어합니다(open|disabled|allowlist). allowlist는 channels.whatsapp.groupAllowFrom을 사용합니다(대체값: 명시적 channels.whatsapp.allowFrom). 기본값은 allowlist입니다(발신자를 추가할 때까지 차단).
그룹별 세션: 세션 키는 agent:<agentId>:whatsapp:group:<jid> 형식이므로 독립 메시지로 보낸 /verbose on, /trace on, /think high 같은 명령은 해당 그룹으로 범위가 제한됩니다. 개인 DM 상태는 변경되지 않습니다. Heartbeat는 그룹 스레드에서 건너뜁니다.
컨텍스트 주입: 실행을 트리거하지 않은 대기 중인 항목만 포함하는 그룹 메시지(기본값 50개)는 [Chat messages since your last reply - for context] 아래에 접두사로 추가되고, 트리거한 줄은 [Current message - respond to this] 아래에 놓입니다. 이미 세션에 있는 메시지는 다시 주입되지 않습니다.
발신자 표시: 이제 모든 그룹 배치는 [from: Sender Name (+E164)]로 끝나므로 Pi가 누가 말하고 있는지 알 수 있습니다.
임시/한 번 보기: 텍스트/멘션을 추출하기 전에 이를 풀어내므로, 그 안의 호출도 계속 트리거됩니다.
그룹 시스템 프롬프트: 그룹 세션의 첫 턴(그리고 /activation이 모드를 변경할 때마다)에 You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context. 같은 짧은 설명을 시스템 프롬프트에 주입합니다. 메타데이터를 사용할 수 없어도 에이전트에게 그룹 채팅이라는 사실은 알려줍니다.

설정 예시(WhatsApp)

WhatsApp이 텍스트 본문에서 시각적 @를 제거하더라도 표시 이름 호출이 동작하도록 ~/.openclaw/openclaw.json에 groupChat 블록을 추가하세요.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

참고:

정규식은 대소문자를 구분하지 않으며, 다른 설정 정규식 표면과 동일한 안전 정규식 보호 장치를 사용합니다. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다.
누군가 연락처를 탭하면 WhatsApp은 여전히 mentionedJids를 통해 표준 멘션을 보내므로, 번호 대체값은 거의 필요하지 않지만 유용한 안전망입니다.

활성화 명령(소유자 전용)

그룹 채팅 명령을 사용하세요.

/activation mention
/activation always

소유자 번호(channels.whatsapp.allowFrom, 설정되지 않은 경우 봇 자신의 E.164)만 이를 변경할 수 있습니다. 현재 활성화 모드를 보려면 그룹에서 /status를 독립 메시지로 보내세요.

사용 방법

WhatsApp 계정(OpenClaw를 실행 중인 계정)을 그룹에 추가합니다.
@openclaw …라고 말하거나 번호를 포함합니다. groupPolicy: "open"을 설정하지 않는 한 허용 목록에 있는 발신자만 트리거할 수 있습니다.
에이전트 프롬프트에는 최근 그룹 컨텍스트와 뒤따르는 [from: …] 마커가 포함되어, 올바른 사람에게 응답할 수 있습니다.
세션 수준 지시문(/verbose on, /trace on, /think high, /new 또는 /reset, /compact)은 해당 그룹의 세션에만 적용됩니다. 등록되도록 독립 메시지로 보내세요. 개인 DM 세션은 독립적으로 유지됩니다.

테스트 / 검증

수동 스모크:
- 그룹에서 @openclaw 호출을 보내고, 발신자 이름을 참조하는 답변이 오는지 확인합니다.
- 두 번째 호출을 보내고 히스토리 블록이 포함된 뒤 다음 턴에서 지워지는지 확인합니다.
Gateway 로그(--verbose로 실행)를 확인하여 from: <groupJid>와 [from: …] 접미사가 표시된 inbound web message 항목을 볼 수 있습니다.

알려진 고려 사항

Heartbeat는 시끄러운 브로드캐스트를 피하기 위해 그룹에서 의도적으로 건너뜁니다.
에코 억제는 결합된 배치 문자열을 사용합니다. 멘션 없이 동일한 텍스트를 두 번 보내면 첫 번째만 응답을 받습니다.
세션 저장소 항목은 기본적으로 세션 저장소(~/.openclaw/agents/<agentId>/sessions/sessions.json)에 agent:<agentId>:whatsapp:group:<jid>로 표시됩니다. 항목이 없다는 것은 해당 그룹이 아직 실행을 트리거하지 않았다는 뜻일 뿐입니다.
그룹의 입력 표시기는 agents.defaults.typingMode를 따릅니다. 보이는 응답이 기본 메시지 도구 전용 모드를 사용할 때는 기본적으로 입력이 즉시 시작되므로, 자동 최종 응답이 게시되지 않더라도 그룹 구성원이 에이전트가 작업 중임을 볼 수 있습니다. 명시적 입력 모드 설정이 있으면 여전히 그 설정이 우선합니다.

WhatsApp 그룹 메시지

동작

설정 예시(WhatsApp)

활성화 명령(소유자 전용)

사용 방법

테스트 / 검증

알려진 고려 사항

관련 항목

Ask OpenClaw

# 동작

# 설정 예시(WhatsApp)

# 활성화 명령(소유자 전용)

# 사용 방법

# 테스트 / 검증

# 알려진 고려 사항

# 관련 항목

동작

설정 예시(WhatsApp)

활성화 명령(소유자 전용)

사용 방법

테스트 / 검증

알려진 고려 사항

관련 항목