OpenClaw WhatsApp 통합 완전 가이드

페어링 코드는 1시간 후에 만료되며, 대기 중인 요청은 채널당 최대 3개로 제한됩니다.

허용 목록 모드

channels.whatsapp.allowFrom 에 나열된 전화번호만 채팅을 시작할 수 있습니다.

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

개방 모드

channels.whatsapp.allowFrom 에 "*" 를 포함해야 합니다.

참고: 연결된 WhatsApp 번호는 암시적으로 신뢰됩니다 — 자기 자신의 메시지는 dmPolicy 와 allowFrom 검사를 건너뜁니다.

읽음 확인

기본적으로 게이트웨이는 수신된 WhatsApp 메시지를 수락하면 읽음 처리(파란색 체크 표시)합니다.

전역 비활성화:

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

계정별 비활성화:

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

셀프챗 모드는 항상 읽음 확인을 건너뜁니다.

그룹 채팅 지원

그룹은 전용 세션에 매핑됩니다. 다음으로 그룹 동작을 구성합니다:

• 그룹 정책: channels.whatsapp.groupPolicy — open , disabled , 또는 allowlist (기본값: allowlist )
• 활성화 모드:
  • mention (기본값): @멘션 또는 정규식 일치 필요
  • always : 항상 응답 트리거

소유자 전용 명령으로 활성화를 전환합니다 (단독 메시지여야 함):

/activation mention
/activation always

소유자는 channels.whatsapp.allowFrom 으로 결정됩니다 (설정되지 않은 경우 자신의 E.164 번호).

그룹 히스토리 컨텍스트

최근 처리되지 않은 메시지(기본 50개)가 자동으로 컨텍스트로 주입됩니다:

[Chat messages since your last reply - for context]
...
[Current message - respond to this]

각 메시지에는 발신자 접미사가 포함됩니다: [from: Name (+E164)] .

그룹 메타데이터(제목 + 참가자)는 5분간 캐시됩니다.

확인 리액션

WhatsApp은 수신 메시지에 자동으로 이모지 리액션을 보내어 봇이 응답을 생성하기 전에 즉각적인 피드백을 제공할 수 있습니다.

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

옵션:

• emoji : 리액션할 이모지 (예: "👀", "✅"). 비어 있거나 생략하면 기능이 비활성화됩니다.
• direct (기본값: true ): DM 채팅에서 리액션을 보냅니다.
• group (기본값: "mentions" ):
  • "always" : 모든 그룹 메시지에 리액션
  • "mentions" : 봇이 @멘션될 때만 리액션
  • "never" : 그룹에서 리액션하지 않음

계정별 오버라이드:

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

리액션은 수신 즉시, 타이핑 표시나 봇 응답 전에 전송됩니다. 실패가 기록되지만 봇의 응답을 방해하지 않습니다.

메시지 처리

인바운드 메시지

• 메시지는 Baileys messages.upsert 이벤트를 통해 도착
• 상태/브로드캐스트 채팅은 무시됨
• 다이렉트 채팅은 E.164 형식 사용; 그룹은 group JID 사용
• 인용 답장 컨텍스트는 대화 컨텍스트 제공을 위해 항상 추가됨
• 미디어 전용 메시지는 플레이스홀더 사용: <media:image|video|audio|document|sticker>

아웃바운드 메시지

• 텍스트는 기본 4,000자 로 분할됨 ( channels.whatsapp.textChunkLimit 으로 설정 가능)
• 선택적 줄바꿈 분할: channels.whatsapp.chunkMode="newline" 로 설정하면 길이 분할 전에 문단 경계에서 분할
• 지원되는 미디어 유형: image, video, audio, document
• 오디오는 음성 메모(PTT)로 전송됨. OGG/Opus 형식이 최적
• 캡션은 첫 번째 미디어 항목에만 적용
• 애니메이션 GIF: WhatsApp은 인라인 반복을 위해 gifPlayback: true 가 설정된 MP4를 기대함

미디어 제한

• 인바운드 미디어 저장 상한: 50 MB ( channels.whatsapp.mediaMaxMb 로 설정 가능)
• 아웃바운드 미디어 상한: 항목당 5 MB ( agents.defaults.mediaMaxMb 로 설정 가능)
• 이미지는 상한 이하일 때 JPEG로 자동 최적화됨 (리사이즈 + 품질 조정)
• 초과 미디어는 오류 발생; 미디어 응답이 텍스트 경고로 대체됨

인증 정보 및 저장소

• 인증 정보 저장 위치: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• creds.json.bak 에 자동 백업 (손상 시 복원)
• 로그아웃: openclaw channels logout (또는 --account <id> )은 WhatsApp 인증 상태를 삭제하지만 공유 oauth.json 은 유지

다중 계정 지원

단일 Gateway 프로세스에서 여러 WhatsApp 계정을 실행할 수 있습니다. 구성에서 계정 식별자를 사용합니다:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* 계정별 설정 */ },
        work: { /* 계정별 설정 */ },
      },
    },
  },
}

계정별 설정은 sendReadReceipts , ackReaction , mediaMaxMb , historyLimit 등의 오버라이드를 지원합니다.

Twilio / WhatsApp Business API를 사용하지 않는 이유

초기 OpenClaw 빌드는 Twilio의 WhatsApp Business 통합을 지원했지만, 다음과 같은 이유로 제거되었습니다:

• WhatsApp Business 번호는 개인 어시스턴트에 적합하지 않음
• Meta는 24시간 응답 윈도우 를 강제함 — 최근 24시간 내에 응답하지 않으면 비즈니스 번호로 새 메시지를 보낼 수 없음
• 대량 또는 "수다스러운" 사용은 적극적인 차단을 트리거함. 비즈니스 계정은 개인 어시스턴트 스타일의 메시징용으로 설계되지 않았기 때문
• 결과: 불안정한 전송과 빈번한 차단

설정 빠른 참조

| 설정 키 | 설명 | |---|---| | channels.whatsapp.dmPolicy | DM 정책: pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | 개인 번호 설정 시 활성화 | | channels.whatsapp.allowFrom | DM 허용 목록 (E.164 전화번호) | | channels.whatsapp.sendReadReceipts | 자동 읽음 확인 (기본값: true) | | channels.whatsapp.ackReaction | 메시지 수신 시 자동 리액션 | | channels.whatsapp.groupPolicy | 그룹 정책: open / disabled / allowlist | | channels.whatsapp.textChunkLimit | 아웃바운드 텍스트 분할 크기 (기본값: 4000) | | channels.whatsapp.mediaMaxMb | 인바운드 미디어 상한 (기본값: 50 MB) | | channels.whatsapp.configWrites | /config 명령을 통한 설정 쓰기 허용 | | agents.defaults.mediaMaxMb | 아웃바운드 미디어 상한 (기본값: 5 MB) |

문제 해결

연결되지 않음 / QR 로그인 필요

증상: channels status 에서 linked: false 로 표시되거나 "Not linked" 경고가 나타남.

해결: 게이트웨이 호스트에서 openclaw channels login 을 실행하고 QR 코드를 스캔하세요 (WhatsApp > 설정 > 연결된 기기).

연결됨이지만 끊김 / 재연결 루프

증상: channels status 에서 running, disconnected 로 표시되거나 "Linked but disconnected" 경고가 나타남.

해결: openclaw doctor 를 실행하거나 게이트웨이를 재시작하세요. 지속되면 openclaw channels login 으로 다시 연결하고 openclaw logs --follow 로 확인하세요.

Bun 런타임 문제

Bun은 권장하지 않습니다 . WhatsApp (Baileys)과 Telegram은 Bun에서 불안정합니다. 게이트웨이는 Node.js 로 실행하세요.

재연결 동작

게이트웨이는 initialMs , maxMs , factor , jitter , maxAttempts 를 설정할 수 있는 백오프 정책 ( web.reconnect )을 사용합니다. 최대 시도 횟수에 도달하면 웹 모니터링이 중지됩니다 (저하 모드). 로그아웃된 소켓은 중지되며 다시 연결해야 합니다.

다음 단계

• Telegram 통합 가이드
• Discord 통합 가이드
• 공식 WhatsApp 문서