​

WhatsApp (웹 채널)

​

설치(필요 시)

• 온보딩(openclaw onboard) 및 openclaw channels add --channel whatsapp는 처음 선택할 때 WhatsApp 플러그인 설치를 안내합니다.
• openclaw channels login --channel whatsapp도 플러그인이 아직 없으면 설치 흐름을 제공합니다.
• 개발 채널 + git checkout: 기본값은 로컬 플러그인 경로입니다.
• 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:<agentId>:whatsapp:group:<jid>).
• WhatsApp Web 전송은 gateway 호스트의 표준 프록시 환경 변수(HTTPS_PROXY, HTTP_PROXY, NO_PROXY / 소문자 변형)를 따릅니다. 채널별 WhatsApp 프록시 설정보다 호스트 수준 프록시 구성을 권장합니다.

​

액세스 제어 및 활성화

​

개인 번호 및 self-chat 동작

• self-chat 턴에 대해 읽음 확인 건너뜀
• 자기 자신을 다시 호출할 수 있는 mention-JID 자동 트리거 동작 무시
• messages.responsePrefix가 설정되지 않은 경우 self-chat 응답은 기본적으로 [{identity.name}] 또는 [openclaw] 사용

​

메시지 정규화 및 컨텍스트

[<sender> id:<stanzaId>에 대한 응답]
<인용된 본문 또는 미디어 플레이스홀더>
[/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은 여기서 사용되지 않음)

​

다중 계정 및 자격 증명

​

도구, 액션 및 구성 쓰기

• 에이전트 도구 지원에는 WhatsApp 반응 액션(react)이 포함됩니다.
• 액션 게이트:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 채널 시작 구성 쓰기는 기본적으로 활성화됩니다(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

​

관련 항목

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