OpenClaw WhatsApp 연동 완벽 가이드: 설정부터 실전 활용까지

WhatsApp에서 AI와 대화하면 평소 가장 자주 쓰는 채팅 도구로 AI 어시스턴트를 바로 호출할 수 있어 앱을 번갈아 열 필요가 없습니다. WhatsApp 연동은 Telegram보다 조금 복잡하지만 원리를 이해하면 5~10분 만에 설정을 끝낼 수 있습니다.

저비용으로 OpenClaw를 쓰는 방법: ArkClaw로 AI Agent의 진입 장벽 낮추기

최근 큰 인기를 끈 OpenClaw는 유용하지만 설정이 너무 복잡하게 느껴질 수 있습니다. ByteDance의 Volcano Engine이 출시한 ArkClaw는 그 진입 장벽을 크게 낮췄습니다. 서버나 Token 설정을 씨름할 필요 없이 클릭 한 번으로 24시간 온라인 상태를 유지하며 브라우저 제어, 스크립트 실행, 캘린더 관리까지 하는 AI 도우미를 이용할 수 있습니다.

무엇보다 가격이 저렴합니다. 월 이용료는 9.9위안이며, 제 초대 코드 ZLKUK54M을 사용해 여기에서 가입하면 8.9위안에 이용할 수 있습니다. 프로그래머라면 Coding Plan Pro에 가입해 무료로 사용할 수도 있습니다.

WhatsApp에 AI를 연동하는 이유

시작하기 전에 이런 의문이 들 수 있습니다. 왜 Telegram이나 Web 인터페이스를 바로 사용하지 않을까요?

사실 플랫폼마다 장점이 있습니다. 제가 WhatsApp을 선택한 주된 이유는 다음과 같습니다.

• 익숙한 사용 방식: WhatsApp은 제가 일상에서 가장 자주 쓰는 채팅 도구이고 가족과 친구도 모두 사용합니다.
• 원활한 통합: 별도의 AI 앱을 열지 않아도 채팅 화면에서 바로 질문할 수 있습니다.
• Linked Devices: WhatsApp의 다중 기기 기능은 완성도가 높고 연결도 안정적입니다.
• 통제 가능한 개인정보: 데이터가 자체 서버에 보관되며 제3자를 거치지 않습니다.

물론 Telegram도 API가 더 개방적이고 봇 생태계가 풍부하다는 장점이 있습니다. 어느 쪽이 적합한지는 자신의 사용 환경에 따라 선택하면 됩니다.

사전 준비: 환경 확인

연동을 시작하기 전에 몇 가지 전제 조건을 먼저 확인하세요.

필수 조건

1. OpenClaw가 설치되어 실행 중이어야 합니다. 아직 설치하지 않았다면 이전 설치 가이드를 먼저 확인하세요.
2. 휴대전화에 WhatsApp 계정이 있어야 합니다. QR 코드 연결에 사용할 주 계정이 필요합니다.
3. Gateway가 실행 중이어야 합니다. openclaw gateway가 시작되었는지 확인하세요.
4. 네트워크가 안정적이어야 합니다. QR 코드로 연결할 때 원활한 네트워크가 필요합니다.

기술 관련 참고 사항

주의할 점이 하나 있습니다. Bun 런타임을 사용하면 WhatsApp이나 Telegram 연결 시 호환성 문제가 발생할 수 있습니다. 공식 권장 방식은 Node.js로 Gateway를 실행하는 것이며, 이쪽이 좀 더 안정적입니다.

실행 환경을 확인해 보겠습니다.

# Node.js 버전 확인
node --version

# Gateway 실행 여부 확인
ps aux | grep openclaw

세 가지 연동 방법

OpenClaw는 WhatsApp을 연결하는 세 가지 방법을 제공합니다. 추천 순서대로 소개하겠습니다.

방법 1: onboard 마법사(가장 간단함)

가장 간단한 방식으로, 처음 설정하는 사용자에게 적합합니다.

아직 초기 설정을 완료하지 않았다면 다음 명령을 바로 실행하세요.

openclaw onboard --install-daemon

마법사가 진행되는 동안 연결할 메시지 채널을 묻습니다. WhatsApp을 선택하고 다음과 같이 진행하세요.

1. 터미널에 QR 코드가 표시됩니다.
2. 휴대전화에서 WhatsApp을 열고 “설정” → “연결된 기기”로 이동합니다.
3. “기기 연결”을 누르고 QR 코드를 스캔합니다.
4. 스캔에 성공하면 터미널에 연결 완료 메시지가 표시됩니다.

전체 과정은 매우 빨라 1~2분이면 끝납니다. 저도 처음 스캔할 때는 연결되지 않을까 봐 꽤 긴장했지만, 막상 해 보니 한 번에 연결됐습니다.

방법 2: channels login 명령

이미 onboard를 완료했고 WhatsApp 채널만 따로 추가하려면 다음 명령을 사용할 수 있습니다.

openclaw channels login

실행하면 다음 과정이 진행됩니다.

1. 터미널 또는 Web 인터페이스에 QR 코드가 표시됩니다.
2. WhatsApp으로 QR 코드를 스캔합니다.
3. 연결이 수립되고 메시지 수신이 시작됩니다.

빠르고 간단하며 전체 설정 과정으로 다시 들어갈 필요가 없다는 것이 이 방법의 장점입니다.

방법 3: Web 인터페이스 설정(가장 유연함)

설정을 더 세밀하게 제어하려면 Web 인터페이스를 이용할 수 있습니다.

OpenClaw 제어판의 기본 주소인 http://localhost:18789에 접속한 후 다음 단계를 따르세요.

1단계: 설정 페이지 열기

Settings → Config로 이동하고 오른쪽 위의 RAW 버튼을 눌러 원본 설정 편집기를 엽니다.

2단계: WhatsApp 설정 추가

channels 섹션에 WhatsApp 설정을 추가합니다.

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+8613800138000"],
      "groupPolicy": "allowlist",
      "mediaMaxMb": 50,
      "debounceMs": 0
    }
  }
}

각 설정 항목의 의미는 다음과 같습니다.

• dmPolicy: 1:1 채팅 메시지 정책입니다. allowlist는 허용 목록에 있는 사용자만 메시지를 보낼 수 있다는 뜻입니다.
• allowFrom: 허용 목록입니다. 국가 코드를 포함한 국제 형식으로 자신의 전화번호를 입력합니다.
• groupPolicy: 그룹 메시지 정책입니다. 마찬가지로 allowlist로 설정하는 편이 더 안전합니다.
• mediaMaxMb: 수신할 수 있는 미디어 파일의 최대 크기(MB)입니다.
• debounceMs: 메시지 디바운스 지연 시간(밀리초)으로, 보통 0으로 설정합니다.

3단계: 저장하고 QR 코드 스캔

오른쪽 위의 Update 버튼을 눌러 설정을 저장한 뒤 Channels 페이지로 돌아가면 QR 코드가 표시됩니다. WhatsApp으로 스캔하면 됩니다.

세부 설정 설명

앞에서 언급한 설정 항목을 좀 더 자세히 살펴보겠습니다.

권한 관리: 누가 AI에 메시지를 보낼 수 있나요?

dmPolicy와 groupPolicy는 매우 중요한 보안 설정입니다.

**dmPolicy(1:1 채팅 정책)**에는 세 가지 선택지가 있습니다.

• allowlist: 허용 목록에 있는 번호만 메시지를 보낼 수 있습니다(권장).
• denylist: 차단 목록에 없는 모든 번호가 메시지를 보낼 수 있습니다.
• open: 누구나 메시지를 보낼 수 있습니다. 자신이 무엇을 하는지 확실히 알지 못한다면 권장하지 않습니다.

저는 allowlist를 사용해 저와 가족의 번호만 추가했습니다. AI에는 시스템에 접근할 권한이 있으므로 낯선 사람이 아무 메시지나 보내게 둘 수는 없습니다.

allowFrom 전화번호 형식

전화번호는 국가 코드를 포함한 국제 형식이어야 합니다.

"allowFrom": [
  "+8613800138000",    // 중국 전화번호
  "+14155552671",      // 미국 전화번호
  "+447700900000"      // 영국 전화번호
]

더하기 기호 +와 국가 코드를 빼먹으면 번호를 인식하지 못합니다.

groupPolicy(그룹 정책)

WhatsApp 그룹에서 AI를 사용하려면 그룹 정책을 설정해야 합니다. 다만 솔직히 말해 완전히 신뢰할 수 있는 비공개 소규모 그룹이 아니라면 그룹에 AI 권한을 바로 개방하는 것은 권하지 않습니다.

다음과 같이 설정할 수 있습니다.

"groupPolicy": "allowlist",
"allowFrom": ["그룹 ID"]

그룹 ID는 로그에서 찾을 수 있습니다. 또는 먼저 open으로 설정하고 메시지를 하나 보낸 다음 로그에서 ID를 확인할 수도 있습니다.

메시지 라우팅: AI가 메시지를 처리하는 방식

OpenClaw는 WhatsApp 메시지를 AI 모델로 자동 라우팅해 처리합니다. 전체 흐름은 다음과 같습니다.

1. WhatsApp에서 메시지를 보냅니다.
2. OpenClaw Gateway가 메시지를 수신합니다.
3. 발신자가 허용 목록에 있는지 확인합니다.
4. 검사를 통과하면 AI 모델로 전달합니다.
5. AI가 답변을 생성합니다.
6. 답변을 WhatsApp으로 전송합니다.

이 과정은 매우 빨라 보통 1~2초 안에 완료됩니다. 실제 속도는 AI 모델의 응답 속도에 따라 달라집니다.

미디어 파일 처리

mediaMaxMb 설정은 수신 가능한 파일 크기를 결정합니다. 기본값인 50MB면 일반적인 용도에는 충분합니다.

현재 OpenClaw가 지원하는 미디어 유형은 다음과 같습니다.

• 이미지(JPG, PNG 등)
• 오디오 파일
• 문서(PDF, TXT 등)

AI에 GPT-4V 같은 비전 기능이 설정되어 있다면 이미지를 보냈을 때 AI가 이미지 내용을 인식할 수 있습니다.

QR 코드 스캔 절차 상세 설명

어떤 방법을 사용하든 마지막에는 QR 코드를 스캔해야 합니다. 간단한 단계지만 몇 가지 세부 사항에 주의해야 합니다.

휴대전화에서 할 일

1. WhatsApp 앱을 엽니다.
2. 오른쪽 위의 “더보기”(점 세 개)를 누릅니다.
3. “연결된 기기” 또는 “Linked Devices”를 선택합니다.
4. “기기 연결” 또는 “Link a Device”를 누릅니다.
5. 지문 인식이나 비밀번호 입력이 필요할 수 있습니다.
6. 카메라가 열리면 컴퓨터에 표시된 QR 코드를 비춥니다.

컴퓨터에서 주의할 점

• QR 코드 유효 시간: QR 코드는 보통 1~2분 후 만료됩니다. 스캔되지 않으면 새로 고침해 다시 생성하세요.
• 선명도: QR 코드가 선명하게 표시되는지 확인하고 터미널 글꼴을 너무 작게 설정하지 마세요.
• 네트워크: 스캔 순간에 네트워크 연결이 필요하므로 휴대전화와 컴퓨터가 모두 온라인인지 확인하세요.

저도 처음에는 터미널 글꼴이 너무 작아 QR 코드가 뭉개지는 바람에 여러 번 스캔해야 했습니다. 터미널 창을 키우니 바로 해결됐습니다.

연결 성공을 확인하는 신호

QR 코드 스캔에 성공하면 다음과 같은 변화가 나타납니다.

• 휴대전화: “연결된 기기” 목록에 OpenClaw가 나타납니다.
• 컴퓨터: 터미널에 “WhatsApp connected” 또는 비슷한 메시지가 표시됩니다.
• Web 인터페이스: Channels 페이지에서 WhatsApp 상태가 연결됨을 뜻하는 초록색으로 표시됩니다.

테스트 및 확인

연결을 마친 뒤에는 모든 것이 정상인지 바로 테스트해 보세요.

첫 메시지 보내기

WhatsApp에서 자신에게 다음과 같은 메시지를 보내 보세요.

안녕하세요, 들리나요?

설정이 올바르다면 AI가 몇 초 안에 답합니다. 저도 처음 답장을 받았을 때 휴대전화 화면을 보며 한참 웃었습니다. 정말 신기했습니다.

여러 메시지 유형 확인

다음 작업도 시도해 보세요.

• 텍스트 메시지: AI에게 질문합니다.
• 이미지: 이미지를 보내고 AI에게 내용을 설명해 달라고 합니다. 비전 모델이 필요합니다.
• 문서: PDF나 TXT 파일을 보냅니다.
• 음성: 지원된다면 음성을 텍스트로 변환하는 기능을 시험합니다.

로그 확인

문제가 생겼다면 로그를 확인하면 원인 파악에 도움이 됩니다.

# OpenClaw 로그 확인
openclaw gateway --port 18789

로그에는 수신된 메시지, 처리 과정, 오류 정보 등이 표시됩니다.

자주 발생하는 문제 해결

소프트웨어를 설치하다 보면 문제를 피하기 어렵습니다. 제가 직접 겪은 문제와 해결 방법을 정리했습니다.

문제 1: QR 코드를 스캔해도 반응이 없음

가능한 원인:

• QR 코드가 만료됨
• 네트워크 연결 문제
• WhatsApp 버전이 너무 오래됨

해결 방법:

1. QR 코드를 새로 고침하고 다시 스캔합니다.
2. 휴대전화와 컴퓨터의 네트워크 연결을 확인합니다.
3. WhatsApp을 최신 버전으로 업데이트합니다.

문제 2: 연결 실패 및 status=515 오류

공식 문서에서도 따로 언급할 만큼 자주 발생하는 오류입니다.

전체 오류 메시지:

WhatsApp login failed: status=515 Unknown Stream Errored (restart required)

해결 방법:

1. Settings → Config로 돌아갑니다.
2. 설정을 변경하지 않았더라도 오른쪽 위의 Update 버튼을 누릅니다.
3. Channels 페이지로 돌아가 연결 상태를 확인합니다.
4. 그래도 해결되지 않으면 Gateway를 재시작합니다.

# Gateway 재시작
pkill -f openclaw
openclaw gateway --port 18789

문제 3: 메시지를 보냈지만 AI가 답하지 않음

가능한 원인:

• 발신자가 허용 목록에 없음
• AI 모델 설정에 문제가 있음
• API 키가 만료됨

확인 절차:

1. 전화번호 형식이 국제 형식으로 올바른지 확인합니다.
2. 로그를 살펴 메시지가 수신되었는지 확인합니다.
3. AI가 Web 인터페이스에서 정상적으로 응답하는지 테스트합니다.
4. API 키가 유효한지 확인합니다.

문제 4: 권한 거부

증상: 메시지를 보낸 뒤 “Permission denied”가 표시되거나 답변이 오지 않습니다.

해결 방법:

• 자신의 번호가 allowFrom 목록에 있는지 확인합니다.
• 국가 코드를 포함한 전화번호 형식을 확인합니다.
• 그룹 메시지라면 groupPolicy 설정을 확인합니다.

문제 5: 미디어 파일을 보낼 수 없음

가능한 원인:

• 파일이 mediaMaxMb 제한을 초과함
• 지원하지 않는 파일 형식임
• 네트워크 업로드에 실패함

해결 방법:

• mediaMaxMb 값을 늘립니다.
• 파일을 압축해 봅니다.
• 네트워크 연결을 확인합니다.

문제 6: Gateway 재시작 후 연결 끊김

증상: 컴퓨터나 Gateway를 재시작하면 WhatsApp 연결이 끊깁니다.

해결 방법:

1. 정상적인 경우 자동으로 다시 연결됩니다.
2. 자동 연결되지 않으면 openclaw channels login을 다시 실행합니다.
3. QR 코드를 다시 스캔해 연결합니다.
4. 또는 데몬이 정상적으로 시작됐는지 확인합니다.

고급 활용 팁

기본 기능을 설정했다면 몇 가지 고급 설정도 활용할 수 있습니다.

다중 기기 관리

WhatsApp에서는 여러 기기를 동시에 연결할 수 있습니다. OpenClaw가 설치된 컴퓨터가 여러 대라면 각각 연결할 수 있고, 메시지는 모든 기기에 동기화됩니다.

다만 같은 WhatsApp 계정으로는 OpenClaw를 한 번만 연결할 수 있다는 점에 유의하세요. 여러 컴퓨터에 연결하려면 서로 다른 WhatsApp 계정을 사용해야 합니다.

응답 정책 사용자 정의

설정에서 debounceMs를 지정해 메시지 디바운스를 제어할 수 있습니다.

"debounceMs": 1000

이렇게 하면 메시지를 연속해서 여러 개 보냈을 때 AI가 1초간 기다렸다가 한꺼번에 처리하므로 잦은 API 호출을 피할 수 있습니다.

메시지 필터링

특정 유형의 메시지를 무시하려면 스킬(Skills) 설정에서 필터 규칙을 지정할 수 있습니다. 예를 들어 “AI”로 시작하는 메시지에만 응답하도록 설정할 수 있습니다.

성능 최적화

메시지 양이 많다면 다음 방법을 고려하세요.

• mediaMaxMb 제한을 줄여 대역폭을 절약합니다.
• debounceMs를 조정해 요청이 지나치게 자주 발생하지 않도록 합니다.
• 더 빠른 AI 모델을 사용합니다.

보안 권장 사항

WhatsApp을 연동한 뒤에는 다음 보안 사항을 반드시 확인하세요.

1. 허용 목록을 엄격하게 관리

신뢰할 수 있는 번호만 allowFrom 목록에 추가하세요. 관련 스킬이 활성화되어 있다면 이 번호에서 AI를 통해 시스템 명령을 실행할 수도 있으므로 권한이 매우 큽니다.

2. 연결된 기기를 정기적으로 확인

WhatsApp의 “연결된 기기”에서 온라인 상태인 기기를 정기적으로 확인하세요. 모르는 기기가 있다면 즉시 제거해야 합니다.

3. 민감한 작업에는 확인 절차 추가

파일 삭제나 설정 변경 같은 작업에는 스킬에서 2차 확인 절차를 추가해 실수를 방지하는 것이 좋습니다.

4. 공용 기기에서 연결하지 않기

PC방이나 도서관 같은 공공장소에서는 QR 코드를 스캔해 WhatsApp을 연결하지 마세요. 기기가 감시되고 있다면 계정 정보가 유출될 수 있습니다.

5. OpenClaw 정기 업데이트

보안 패치를 제때 적용할 수 있도록 OpenClaw를 최신 버전으로 유지하세요.

npm update -g openclaw
# 또는
pnpm update -g openclaw

마무리

여기까지 따라왔다면 WhatsApp과 OpenClaw 연결에 성공했을 것입니다. 전체 과정을 다시 정리해 보겠습니다.

WhatsApp과 Telegram 중 무엇을 선택할까요?

아직 어떤 플랫폼을 사용할지 고민 중이라면 다음 기준을 참고하세요.

다음과 같은 경우 WhatsApp을 선택하세요.

• 평소 주로 WhatsApp으로 소통합니다.
• 가족이나 친구와 AI를 공유해야 합니다.
• Linked Devices의 안정성을 중요하게 생각합니다.

다음과 같은 경우 Telegram을 선택하세요.

• 더 개방적인 API 기능을 원합니다.
• 봇 생태계를 활용해야 합니다.
• 채널과 그룹 기능이 필요합니다.

솔직히 두 플랫폼을 모두 설정해도 좋습니다. OpenClaw는 여러 채널을 동시에 실행할 수 있으므로 WhatsApp과 Telegram을 함께 연동하고 상황에 맞는 플랫폼을 선택할 수 있습니다.

다음 단계

연결에 성공했다면 다음 작업을 해볼 수 있습니다.

• OpenClaw의 Skills 기능을 살펴보고 AI에 더 많은 기능을 추가합니다.
• 이미지와 문서를 보내 멀티모달 기능을 테스트합니다.
• 사용자 정의 응답 로직을 연구합니다.
• 관심이 있다면 자신만의 스킬 플러그인을 개발합니다.

마지막으로 한 가지 더 말씀드리겠습니다. WhatsApp 연동은 편리하지만 보안에도 주의해야 합니다. 허용 목록을 신중하게 관리하고 신뢰할 수 없는 사람에게 AI 권한을 개방하지 마세요.

즐겁게 활용하시고, 문제가 생기면 언제든 문서나 커뮤니티에서 답을 찾아보세요!

---