통합12 분 소요

OpenClaw WhatsApp 통합 완전 가이드

OpenClaw를 WhatsApp에 연결하는 단계별 가이드입니다. Baileys를 사용한 WhatsApp Web 프로토콜로 AI 어시스턴트와 채팅하세요.

OpenClaw Guides

Tutorial Authors

2025-02-04

개요

WhatsApp 통합을 사용하면 WhatsApp을 통해 OpenClaw AI 어시스턴트와 직접 채팅할 수 있습니다. OpenClaw는 Baileys를 통한 WhatsApp Web을 사용하며, 게이트웨이가 세션을 소유하고 모든 통신을 관리합니다. 브라우저에서 WhatsApp Web을 연결하는 것과 유사한 방식으로 WhatsApp 계정을 연결하게 됩니다.

사전 요구 사항

시작하기 전에 다음 사항을 확인하세요:

OpenClaw 설치 및 게이트웨이 실행 중
실제 휴대폰 번호가 있는 WhatsApp 계정 (VoIP 및 가상 번호는 WhatsApp에서 일반적으로 차단됨)
Node.js 런타임 (Bun은 권장하지 않음 — WhatsApp/Baileys는 Bun에서 불안정함)

전화번호 준비

WhatsApp은 인증을 위해 실제 휴대폰 번호가 필요합니다. 두 가지 지원 모드가 있습니다:

전용 번호 (권장)

OpenClaw에 별도의 전화번호를 사용하세요. 깔끔한 라우팅과 셀프챗 관련 문제가 없어 최상의 사용자 경험을 제공합니다. 이상적인 설정은 여분의/오래된 Android 폰 + eSIM입니다 — Wi-Fi와 전원에 연결해 두고 QR로 링크하면 됩니다.

번호 확보 팁:

현지 eSIM: 해당 국가의 이동통신사에서 구매 (가장 안정적)
선불 SIM: 저렴하며, 인증 SMS 한 번만 수신하면 됨
피해야 할 것: TextNow, Google Voice, 대부분의 "무료 SMS" 서비스 — WhatsApp이 이들을 적극적으로 차단함

번호는 인증 SMS를 한 번만 수신하면 됩니다. 이후 WhatsApp Web 세션은 creds.json을 통해 유지됩니다.

팁: 같은 기기에서 다른 번호로 WhatsApp Business를 사용할 수 있습니다. 개인 WhatsApp을 분리하기에 좋습니다 — WhatsApp Business를 설치하고 OpenClaw 번호를 거기에 등록하세요.

개인 번호 (대안)

빠른 대안: 자신의 번호로 OpenClaw를 실행합니다. 연락처에 스팸을 보내지 않도록 자신에게 메시지를 보내세요 (WhatsApp의 "나에게 메시지 보내기" 기능). 이 경우 셀프챗 모드를 반드시 활성화해야 합니다.

1단계: WhatsApp 구성

~/.openclaw/openclaw.json을 편집합니다.

전용 번호 구성

json5

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

+15551234567을 어시스턴트와 채팅을 허용할 전화번호로 교체하세요 (E.164 형식).

개인 번호 구성 (셀프챗 모드)

json

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

셀프챗 모드를 사용할 때는 메시지를 보내는 전화번호(소유자/발신자)를 입력하세요. 어시스턴트 번호가 아닙니다. 셀프챗 응답은 기본적으로 [{identity.name}]을 접두사로 사용합니다 (설정되지 않은 경우 [openclaw]). messages.responsePrefix로 커스터마이징하거나 ""로 설정하여 제거할 수 있습니다.

2단계: WhatsApp 계정 연결

로그인 명령을 실행합니다:

bash

openclaw channels login

터미널에 QR 코드가 표시됩니다. 휴대폰에서:

WhatsApp 열기
설정 > 연결된 기기로 이동
기기 연결 탭
터미널에 표시된 QR 코드 스캔

다중 계정 설정의 경우 계정을 지정합니다:

bash

openclaw channels login --account <accountId>

기본 계정 (--account 생략 시)은 default가 있으면 default이고, 그렇지 않으면 구성된 첫 번째 계정 ID(정렬 순)입니다.

3단계: 게이트웨이 시작

메시지 수신을 시작하려면 OpenClaw 게이트웨이를 시작합니다. 게이트웨이가 Baileys 소켓과 수신 루프를 소유합니다 — CLI와 macOS 앱은 게이트웨이와 통신하며, Baileys를 직접 사용하지 않습니다.

중요: 아웃바운드 전송에는 활성 리스너가 필요합니다. 그렇지 않으면 전송이 즉시 실패합니다.

DM 접근 제어

OpenClaw는 channels.whatsapp.dmPolicy를 통해 세 가지 DM 정책 모드를 제공합니다:

페어링 모드 (기본값)

알 수 없는 발신자에게 시간 제한이 있는 페어링 코드가 전송됩니다. 승인될 때까지 메시지는 처리되지 않습니다.

bash

# 페어링 요청 승인
openclaw pairing approve whatsapp <code>

# 대기 중인 페어링 요청 목록 확인
openclaw pairing list whatsapp

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

허용 목록 모드

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

json5

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

개방 모드

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

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

읽음 확인

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

전역 비활성화:

json5

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

계정별 비활성화:

json5

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

json

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

옵션:

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

계정별 오버라이드:

json

{
  "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 계정을 실행할 수 있습니다. 구성에서 계정 식별자를 사용합니다:

json5

{
  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)을 사용합니다. 최대 시도 횟수에 도달하면 웹 모니터링이 중지됩니다 (저하 모드). 로그아웃된 소켓은 중지되며 다시 연결해야 합니다.

개요

사전 요구 사항

전화번호 준비

전용 번호 (권장)

개인 번호 (대안)

1단계: WhatsApp 구성

전용 번호 구성

개인 번호 구성 (셀프챗 모드)

2단계: WhatsApp 계정 연결

3단계: 게이트웨이 시작

DM 접근 제어

페어링 모드 (기본값)

허용 목록 모드

개방 모드

읽음 확인

그룹 채팅 지원

그룹 히스토리 컨텍스트

확인 리액션

메시지 처리

인바운드 메시지

아웃바운드 메시지

미디어 제한

인증 정보 및 저장소

다중 계정 지원

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

설정 빠른 참조

문제 해결

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

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

Bun 런타임 문제

재연결 동작

다음 단계