​

WhatsApp (웹 채널)

​

설치(필요 시)

• 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

​

빠른 설정

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

openclaw channels login --channel whatsapp

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 소켓과 재연결 루프를 소유합니다.
• 아웃바운드 전송은 대상 계정에 대해 활성 WhatsApp 리스너가 있어야 합니다.
• 상태 및 브로드캐스트 채팅은 무시됩니다(@status, @broadcast).
• 다이렉트 채팅은 DM 세션 규칙을 사용합니다(session.dmScope; 기본값 main은 DM을 agent 메인 세션으로 병합함).
• 그룹 세션은 격리됩니다(agent:<agentId>:whatsapp:group:<jid>).

​

접근 제어 및 활성화

​

개인 번호 및 self-chat 동작

• self-chat 턴에서는 읽음 확인 생략
• 그렇지 않으면 자신에게 핑을 보낼 수 있는 mention-JID 자동 트리거 동작 무시
• messages.responsePrefix가 설정되지 않은 경우, self-chat 응답의 기본값은 [{identity.name}] 또는 [openclaw]

​

메시지 정규화 및 컨텍스트

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

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

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

​

전달, 분할, 미디어

​

반응 수준

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

​

확인 반응

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

• 수신이 허용된 직후 즉시 전송됨(응답 전)
• 실패는 로그에 기록되지만 일반 응답 전달을 막지 않음
• 그룹 모드 mentions는 멘션으로 트리거된 턴에 반응하며, 그룹 활성화 always는 이 검사를 우회하는 역할을 함
• WhatsApp는 channels.whatsapp.ackReaction을 사용합니다(레거시 messages.ackReaction은 여기서 사용되지 않음)

​

멀티 계정 및 자격 증명

​

도구, 작업, config 쓰기

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

​

문제 해결

openclaw channels login --channel whatsapp
openclaw channels status

openclaw doctor
openclaw logs --follow

​

구성 참조 포인터

• 구성 참조 - 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.*
• 세션 동작: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

​

관련 항목

• 페어링
• 그룹
• 보안
• 채널 라우팅
• 멀티 agent 라우팅
• 문제 해결