Rihpig

Posted on Mar 25 • Originally published at apidog.com

무료 OpenClaw 위챗 사용법

요약: @tencent-weixin/openclaw-weixin 플러그인을 설치하고, QR 코드를 스캔하여 계정을 승인한 뒤, 게이트웨이를 재시작하면 OpenClaw를 WeChat에 바로 연결할 수 있습니다. 전체 설정은 5분 이내에 끝나며, 무료 오픈 소스 플러그인으로 여러 WeChat 계정을 동시에 지원합니다.

지금 Apidog을 사용해보세요

소개

WeChat에서 AI 비서를 실행하는 일은 복잡해 보이지만, OpenClaw로 간단히 해결할 수 있습니다. 기존 솔루션과 달리, 복잡한 서버 설정이나 기업 계정, 비싼 구독료가 필요 없습니다.

이 글에서는 @tencent-weixin/openclaw-weixin 플러그인을 활용해 개인 WeChat 계정을 OpenClaw AI 게이트웨이에 연결하는 방법, 다계정 처리, 대화 컨텍스트 격리까지 실전 중심으로 안내합니다. 이 과정을 따라하면 WeChat에 OpenClaw 기반 AI 비서를 곧바로 사용할 수 있습니다.

💡WeChat 봇이 외부 API(날씨, 결제, CRM 등)와 연동된다면, 먼저 API 테스트 도구로 검증하세요. Apidog Free를 활용해 API를 설계·테스트·문서화할 수 있습니다.

필수 조건

OpenClaw 설치 (플러그인 v2.0.x는 >=2026.3.22 필요)
openclaw CLI 사용 가능
WeChat 계정 (개인 계정만 있으면 됨)
Node.js 설치 (원클릭 설치용)

OpenClaw 버전 확인:

openclaw --version

버전이 낮다면 먼저 업데이트하세요. 플러그인 v2.0.x는 OpenClaw >=2026.3.22가 요구됩니다.

플러그인 호환성

플러그인 버전	OpenClaw 버전	상태
2.0.x	`>=2026.3.22`	활성
1.0.x	`>=2026.1.0 <2026.3.22`	유지보수

플러그인은 OpenClaw 버전을 자동 확인하며, 호환 범위가 아니면 로드를 거부합니다.

1단계: 플러그인 설치

옵션 A: 원클릭 설치 (권장)

npx -y @tencent-weixin/openclaw-weixin-cli install

위 명령은 플러그인 설치, 구성, 초기 설정까지 자동 처리합니다.

옵션 B: 수동 설치

원클릭이 안 된다면 다음 명령을 순차 실행하세요:

1. 플러그인 설치:

openclaw plugins install "@tencent-weixin/openclaw-weixin"

2. 플러그인 활성화:

openclaw config set plugins.entries.openclaw-weixin.enabled true

2단계: QR 코드 스캔하여 WeChat 승인

openclaw channels login --channel openclaw-weixin

QR 코드가 터미널에 출력됩니다. WeChat 앱에서 스캔 아이콘을 사용해 QR을 스캔하고, 휴대폰에서 로그인 승인을 터치하세요.

로그인 상태는 로컬에 저장되므로, 로그아웃 전까지는 QR 재스캔이 불필요합니다.

3단계: 게이트웨이 다시 시작

openclaw gateway restart

게이트웨이 재시작 후, WeChat 계정이 OpenClaw에 연동됩니다. 이후 WeChat 메시지는 AI 에이전트가 자동 처리합니다.

4단계: 여러 WeChat 계정 추가 (선택 사항)

openclaw channels login --channel openclaw-weixin

위 명령을 계정별로 반복 실행하면, 각 QR 스캔마다 새 계정이 등록됩니다. 모든 계정이 독립적으로 병렬 운영됩니다.

5단계: 대화 컨텍스트 격리 (선택 사항)

기본값으론 모든 채널이 동일한 AI 대화 컨텍스트를 공유합니다. WeChat과 다른 채널의 AI 메모리가 섞이지 않게 하려면 아래처럼 설정하세요:

openclaw config set agents.mode per-channel-per-peer

이렇게 하면 각 "WeChat 계정 + 연락처" 조합마다 고유한 AI 메모리가 유지됩니다.

플러그인이 내부적으로 작동하는 방식

OpenClaw 게이트웨이와 플러그인 사이의 API 구조는 다음과 같습니다.

인증 헤더

헤더	값
`Content-Type`	`application/json`
`AuthorizationType`	`ilink_bot_token`
`Authorization`	`Bearer <token>`
`X-WECHAT-UIN`	base64로 인코딩된 임의의 uint32

핵심 API 엔드포인트

엔드포인트	경로	목적
getUpdates	`getupdates`	새 메시지 롱폴링
sendMessage	`sendmessage`	텍스트/이미지/비디오/파일 전송
getUploadUrl	`getuploadurl`	미디어 업로드용 CDN URL 발급
getConfig	`getconfig`	계정 설정 조회 (입력 알림 등)
sendTyping	`sendtyping`	입력 중 알림 표시/숨기기

메시지 수신 (롱폴링)

// 요청
{
  "get_updates_buf": ""
}

// 응답
{
  "ret": 0,
  "msgs": [...],
  "get_updates_buf": "<new_cursor>",
  "longpolling_timeout_ms": 35000
}

최신 메시지만 받으려면, 응답의 get_updates_buf 값을 다음 요청에 그대로 넘기면 됩니다.

메시지 전송

{
  "msg": {
    "to_user_id": "<target_user_id>",
    "context_token": "<session_context_token>",
    "item_list": [
      {
        "type": 1,
        "text_item": { "text": "Hello!" }
      }
    ]
  }
}

메시지 유형

유형	값
TEXT	1
IMAGE	2
VOICE	3
FILE	4
VIDEO	5

미디어 업로드 (이미지, 파일, 비디오)

파일 메타데이터(크기, MD5)와 함께 getUploadUrl 호출
서명된 CDN 업로드 정보 수신
AES-128-ECB로 파일 암호화
CDN에 업로드
sendMessage에서 해당 파일 참조

일반적인 문제 및 해결 방법

플러그인 로드 거부

오류: 플러그인 로드 거부

해결: OpenClaw 버전을 반드시 >=2026.3.22로 맞추세요.

openclaw --version
# 구버전이면 업데이트 필요

QR 코드 만료

오류: QR 코드가 빠르게 만료됨

해결: 로그인 명령을 다시 실행하세요. QR 코드는 약 30초 후 만료됩니다.

openclaw channels login --channel openclaw-weixin

메시지 수신 안 됨

오류: 메시지가 OpenClaw에 도달하지 않음

해결: 로그인 후 반드시 게이트웨이를 재시작하세요.

openclaw gateway restart

여러 계정 컨텍스트 혼합

오류: AI 응답이 타 계정에 섞여 전달됨

해결: 채널별 컨텍스트 격리 활성화

openclaw config set agents.mode per-channel-per-peer

실제 사용 사례

개인 AI 비서

개인 WeChat을 OpenClaw에 연결해, AI 비서가 메시지를 자동 응답하도록 설정하세요. 컨텍스트 격리로 각 연락처별 맞춤 대화가 가능합니다.

소규모 사업 고객 지원

여러 WeChat 계정으로 각각 독립적인 AI 메모리를 갖추고, 부서/사업별로 문의 대응을 자동화할 수 있습니다.

개발자 테스트

HTTP JSON API를 활용해 맞춤형 통합도 가능합니다. 문서화된 백엔드 프로토콜로, 동작 확장·교체도 손쉽게 지원합니다.

결론

5분만 투자하면 WeChat과 OpenClaw를 완전히 연동할 수 있습니다. 플러그인 설치 > QR 코드 승인 > 게이트웨이 재시작, 단 세 단계면 끝. 무료로 다계정, 컨텍스트 격리, 모든 미디어 지원(이미지/음성/파일/비디오)까지 사용할 수 있습니다.

개발자를 위한 HTTP JSON API도 완비되어 있어, 외부 서비스와의 연동 및 확장이 쉽습니다.

즉시 시작하려면 원클릭 설치 명령을 사용하세요:

npx -y @tencent-weixin/openclaw-weixin-cli install

다음 단계: WeChat 봇이 준비됐다면, 결제 게이트웨이, CRM, 날씨 등 외부 API를 반드시 연결해야 할 것입니다. Apidog로 API 테스트를 진행해, 봇이 올바른 데이터를 주고받는지 검증하세요. 무료 등급, 신용카드 불필요.

자주 묻는 질문

Q: 개인 WeChat 계정으로도 작동하나요?

A: 네. 이 플러그인은 개인 계정으로도 동작하며, 기업/공식 계정이 필요 없습니다.

Q: 이 플러그인은 무료인가요?

A: 네. @tencent-weixin/openclaw-weixin 플러그인은 무료 오픈 소스입니다. OpenClaw가 있으면 바로 사용 가능합니다.

Q: 여러 WeChat 계정을 동시에 실행할 수 있나요?

A: 네. 각 계정별로 openclaw channels login --channel openclaw-weixin 명령을 반복 실행하면 됩니다.

Q: 컴퓨터를 다시 시작하면 어떻게 되나요?

A: 로그인 정보는 로컬에 저장되어, 재부팅 후 QR 재스캔 없이 openclaw gateway restart만 하면 됩니다.

Q: 이 위에 사용자 지정 통합을 구축할 수 있나요?

A: 네. getUpdates, sendMessage, getUploadUrl, getConfig, sendTyping 등 5가지 HTTP JSON API가 모두 문서화되어 있습니다. 외부 서비스 연동 전, Apidog으로 API 통합을 검증하세요.

DEV Community