WhatsApp

상태: WhatsApp Web(Baileys)을 통해 프로덕션 준비 완료. Gateway가 연결된 세션을 소유합니다.

# 설치(필요 시)

• 온보딩(openclaw onboard) 및 openclaw channels add --channel whatsapp는 처음 선택할 때 WhatsApp Plugin 설치를 안내합니다.
• openclaw channels login --channel whatsapp도 아직 Plugin이 없으면 설치 흐름을 제공합니다.
• 개발 채널 + git 체크아웃: 기본값은 로컬 Plugin 경로입니다.
• Stable/Beta: 현재 공식 릴리스 태그의 npm 패키지 @openclaw/whatsapp를 사용합니다.

수동 설치도 계속 사용할 수 있습니다.

openclaw plugins install @openclaw/whatsapp

현재 공식 릴리스 태그를 따르려면 기본 패키지를 사용하세요. 재현 가능한 설치가 필요할 때만 정확한 버전을 고정하세요.

Windows에서는 WhatsApp Plugin이 npm 설치 중 PATH의 Git을 필요로 합니다. Baileys/libsignal 종속성 중 하나가 git URL에서 가져와지기 때문입니다. Git for Windows를 설치한 다음, 셸을 다시 시작하고 설치를 다시 실행하세요.

winget install --id Git.Git -e

Portable Git도 해당 bin 디렉터리가 PATH에 있으면 작동합니다.

# 빠른 설정

{
channels: {
whatsapp: {
  dmPolicy: "pairing",
  allowFrom: ["+15551234567"],
  groupPolicy: "allowlist",
  groupAllowFrom: ["+15551234567"],
},
},
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# 배포 패턴

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

# 런타임 모델

• Gateway가 WhatsApp 소켓과 재연결 루프를 소유합니다.
• 재연결 watchdog은 인바운드 앱 메시지 양만이 아니라 WhatsApp Web 전송 활동을 사용하므로, 조용한 연결된 기기 세션은 최근 메시지를 보낸 사람이 없다는 이유만으로 다시 시작되지 않습니다. 더 긴 애플리케이션 침묵 상한은 전송 프레임이 계속 도착하지만 watchdog 창 동안 처리된 애플리케이션 메시지가 없을 때 여전히 재연결을 강제합니다. 최근 활성 세션의 일시적 재연결 후에는 해당 애플리케이션 침묵 검사가 첫 복구 창에 정상 메시지 제한 시간을 사용합니다.
• Baileys 소켓 타이밍은 web.whatsapp.* 아래에서 명시적입니다. keepAliveIntervalMs는 WhatsApp Web 애플리케이션 ping을 제어하고, connectTimeoutMs는 열기 핸드셰이크 제한 시간을 제어하며, defaultQueryTimeoutMs는 Baileys 쿼리 제한 시간을 제어합니다.
• 아웃바운드 전송에는 대상 계정에 대한 활성 WhatsApp 리스너가 필요합니다.
• 그룹 전송은 텍스트와 미디어 캡션의 @+<digits> 및 @<digits> 토큰에 대해, 토큰이 LID 기반 그룹을 포함한 현재 WhatsApp 참가자 메타데이터와 일치할 때 네이티브 멘션 메타데이터를 첨부합니다.
• 상태 및 브로드캐스트 채팅은 무시됩니다(@status, @broadcast).
• 재연결 watchdog은 인바운드 앱 메시지 양만이 아니라 WhatsApp Web 전송 활동을 따릅니다. 조용한 연결된 기기 세션은 전송 프레임이 계속되는 동안 유지되지만, 전송 중단은 더 늦은 원격 연결 해제 경로보다 훨씬 전에 재연결을 강제합니다.
• 직접 채팅은 DM 세션 규칙을 사용합니다(session.dmScope; 기본값 main은 DM을 에이전트 기본 세션으로 합칩니다).
• 그룹 세션은 격리됩니다(agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters는 네이티브 @newsletter JID로 명시적 아웃바운드 대상이 될 수 있습니다. 아웃바운드 뉴스레터 전송은 DM 세션 의미 체계가 아니라 채널 세션 메타데이터(agent:<agentId>:whatsapp:channel:<jid>)를 사용합니다.
• WhatsApp Web 전송은 Gateway 호스트의 표준 프록시 환경 변수(HTTPS_PROXY, HTTP_PROXY, NO_PROXY / 소문자 변형)를 따릅니다. 채널별 WhatsApp 프록시 설정보다는 호스트 수준 프록시 구성을 선호하세요.
• messages.removeAckAfterReply가 활성화되면, OpenClaw는 표시되는 답장이 전달된 후 WhatsApp ack 반응을 지웁니다.

# Plugin 훅과 개인정보 보호

WhatsApp 인바운드 메시지에는 개인 메시지 내용, 전화번호, 그룹 식별자, 발신자 이름, 세션 상관 필드가 포함될 수 있습니다. 이러한 이유로 WhatsApp은 명시적으로 옵트인하지 않는 한 인바운드 message_received 훅 페이로드를 Plugin에 브로드캐스트하지 않습니다.

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

옵트인을 하나의 계정으로 범위 지정할 수 있습니다.

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

인바운드 WhatsApp 메시지 내용과 식별자를 수신해도 된다고 신뢰하는 Plugin에만 이를 활성화하세요.

# 액세스 제어 및 활성화

# 개인 번호 및 셀프 채팅 동작

연결된 자기 번호가 allowFrom에도 있으면, WhatsApp 셀프 채팅 보호가 활성화됩니다.

• 셀프 채팅 턴의 읽음 확인 건너뛰기
• 자신을 ping하게 될 멘션 JID 자동 트리거 동작 무시
• messages.responsePrefix가 설정되지 않은 경우, 셀프 채팅 답장은 기본적으로 [{identity.name}] 또는 [openclaw]를 사용합니다.

# 메시지 정규화 및 컨텍스트

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

# 전달, 청킹 및 미디어

# 답장 인용

WhatsApp은 아웃바운드 답장이 인바운드 메시지를 눈에 보이게 인용하는 네이티브 답장 인용을 지원합니다. channels.whatsapp.replyToMode로 제어합니다.

기본값은 "off"입니다. 계정별 재정의는 channels.whatsapp.accounts.<id>.replyToMode를 사용합니다.

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

# 반응 수준

channels.whatsapp.reactionLevel은 에이전트가 WhatsApp에서 이모지 반응을 얼마나 넓게 사용할지 제어합니다.

기본값: "minimal".

계정별 재정의는 channels.whatsapp.accounts.<id>.reactionLevel을 사용합니다.

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

# 확인 반응

WhatsApp은 channels.whatsapp.ackReaction을 통해 인바운드 수신 시 즉시 확인 반응을 지원합니다. 확인 반응은 reactionLevel에 의해 제어됩니다. reactionLevel이 "off"이면 억제됩니다.

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

동작 참고 사항:

• 인바운드가 수락된 직후 전송됩니다(답장 전).
• 실패는 기록되지만 정상 답장 전달을 차단하지 않습니다.
• 그룹 모드 mentions는 멘션으로 트리거된 턴에 반응합니다. 그룹 활성화 always는 이 확인을 우회합니다.
• WhatsApp은 channels.whatsapp.ackReaction을 사용합니다(레거시 messages.ackReaction은 여기에서 사용되지 않습니다).

# 다중 계정 및 자격 증명

# 도구, 작업 및 설정 쓰기

• 에이전트 도구 지원에는 WhatsApp 반응 작업(react)이 포함됩니다.
• 작업 게이트:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 채널 시작 설정 쓰기는 기본적으로 활성화됩니다(channels.whatsapp.configWrites=false로 비활성화).

# 문제 해결

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# 시스템 프롬프트

WhatsApp은 groups 및 direct 맵을 통해 그룹과 직접 채팅에 Telegram 스타일 시스템 프롬프트를 지원합니다.

그룹 메시지의 해석 계층:

유효한 groups 맵이 먼저 결정됩니다. 계정이 자체 groups를 정의하면 루트 groups 맵을 완전히 대체합니다(깊은 병합 없음). 그런 다음 프롬프트 조회가 결과로 나온 단일 맵에서 실행됩니다.

1. 그룹별 시스템 프롬프트(groups["<groupId>"].systemPrompt): 특정 그룹 항목이 맵에 존재하고 그 systemPrompt 키가 정의되어 있을 때 사용됩니다. systemPrompt가 빈 문자열("")이면 와일드카드는 억제되고 시스템 프롬프트가 적용되지 않습니다.
2. 그룹 와일드카드 시스템 프롬프트(groups["*"].systemPrompt): 특정 그룹 항목이 맵에 전혀 없거나, 존재하지만 systemPrompt 키를 정의하지 않을 때 사용됩니다.

직접 메시지의 해석 계층:

유효한 direct 맵이 먼저 결정됩니다. 계정이 자체 direct를 정의하면 루트 direct 맵을 완전히 대체합니다(깊은 병합 없음). 그런 다음 프롬프트 조회가 결과로 나온 단일 맵에서 실행됩니다.

1. 특정 direct 시스템 프롬프트 (direct["<peerId>"].systemPrompt): 특정 피어 항목이 맵에 존재하고 그리고 그 systemPrompt 키가 정의되어 있을 때 사용됩니다. systemPrompt가 빈 문자열("")이면 와일드카드가 억제되고 시스템 프롬프트가 적용되지 않습니다.
2. direct 와일드카드 시스템 프롬프트 (direct["*"].systemPrompt): 특정 피어 항목이 맵에 전혀 없거나, 존재하지만 systemPrompt 키를 정의하지 않을 때 사용됩니다.

Telegram 다중 계정 동작과의 차이: Telegram에서는 다중 계정 설정에서 모든 계정에 대해 루트 groups가 의도적으로 억제됩니다. 자체 groups를 정의하지 않은 계정도 포함됩니다. 이는 봇이 속하지 않은 그룹의 그룹 메시지를 받지 못하게 하기 위한 것입니다. WhatsApp은 이 보호 장치를 적용하지 않습니다. 구성된 계정 수와 관계없이, 루트 groups와 루트 direct는 계정 수준 재정의를 정의하지 않은 계정에 항상 상속됩니다. 다중 계정 WhatsApp 설정에서 계정별 그룹 또는 direct 프롬프트를 원한다면 루트 수준 기본값에 의존하지 말고 각 계정 아래에 전체 맵을 명시적으로 정의하세요.

중요 동작:

• channels.whatsapp.groups는 그룹별 구성 맵이면서 채팅 수준 그룹 허용 목록입니다. 루트 또는 계정 범위에서 groups["*"]는 해당 범위에서 "모든 그룹이 허용됨"을 의미합니다.
• 해당 범위에서 이미 모든 그룹을 허용하려는 경우에만 와일드카드 그룹 systemPrompt를 추가하세요. 여전히 고정된 그룹 ID 집합만 대상이 되도록 하려면 프롬프트 기본값에 groups["*"]를 사용하지 마세요. 대신 명시적으로 허용 목록에 올린 각 그룹 항목에 프롬프트를 반복해서 지정하세요.
• 그룹 허용과 발신자 승인은 별도의 검사입니다. groups["*"]는 그룹 처리에 도달할 수 있는 그룹 집합을 넓히지만, 그 자체만으로 해당 그룹의 모든 발신자를 승인하지는 않습니다. 발신자 접근은 여전히 channels.whatsapp.groupPolicy와 channels.whatsapp.groupAllowFrom으로 별도로 제어됩니다.
• channels.whatsapp.direct에는 DM에 대해 같은 부작용이 없습니다. direct["*"]는 DM이 이미 dmPolicy와 allowFrom 또는 페어링 저장소 규칙에 의해 허용된 뒤에 기본 direct 채팅 구성만 제공합니다.

예:

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# 구성 참조 포인터

기본 참조:

• 구성 참조 - WhatsApp

핵심 WhatsApp 필드:

• 접근: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• 전달: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• 다중 계정: accounts.<id>.enabled, accounts.<id>.authDir, 계정 수준 재정의
• 운영: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• 세션 동작: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• 프롬프트: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# 관련 항목

• 페어링
• 그룹
• 보안
• 채널 라우팅
• 다중 에이전트 라우팅
• 문제 해결