무료 OpenClaw 위챗 사용법

요약: @tencent-weixin/openclaw-weixin 플러그인을 설치하고, QR 코드를 스캔하여 계정을 승인한 다음 게이트웨이를 다시 시작하여 OpenClaw를 WeChat에 연결하세요. 전체 설정은 5분 이내에 완료됩니다. 이 플러그인은 무료 오픈 소스이며 여러 WeChat 계정을 동시에 지원합니다.

소개

WeChat에서 AI 비서를 실행하는 것은 복잡하게 들릴 수 있습니다. 대부분의 솔루션은 비싼 API 구독료, 복잡한 서버 설정 또는 기업 계정을 요구합니다. OpenClaw는 이러한 점을 바꿉니다.

@tencent-weixin/openclaw-weixin 플러그인은 개인 WeChat 계정을 OpenClaw의 AI 게이트웨이에 몇 분 만에 연결해줍니다. 기업 계정은 필요 없습니다. 월 사용료도 없습니다. QR 코드를 스캔하기만 하면 바로 사용할 수 있습니다.

이 가이드는 플러그인 설치부터 여러 계정 처리 및 대화 컨텍스트 격리까지 전체 설정을 안내합니다. 이 가이드를 마치면 WeChat에 OpenClaw에서 실행되는 완벽한 AI 비서를 갖게 될 것입니다.

💡

WeChat 봇이 외부 API(날씨, 결제, CRM)를 호출해야 하는 경우 API 테스트 도구가 필요할 것입니다. 봇에 연결하기 전에 Apidog Free를 사용하여 API를 설계, 테스트 및 문서화해 보세요.

button

필수 조건

시작하기 전에 다음이 필요합니다:

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 승인

플러그인이 설치되면 WeChat 계정으로 로그인하세요:

openclaw channels login --channel openclaw-weixin

터미널에 QR 코드가 나타날 것입니다. 휴대폰에서 WeChat을 열고 스캔 아이콘을 탭한 다음 코드를 스캔하세요. 휴대폰에서 승인을 확인하세요.

로그인 자격 증명은 자동으로 로컬에 저장됩니다. 로그아웃하지 않는 한 다시 스캔할 필요가 없습니다.

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

승인 후, 플러그인을 활성화하기 위해 OpenClaw 게이트웨이를 다시 시작하세요:

openclaw gateway restart

이것으로 끝입니다. 이제 WeChat 계정이 OpenClaw에 연결되었습니다. WeChat으로 전송된 메시지는 AI 에이전트에 의해 처리됩니다.

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

OpenClaw는 여러 WeChat 계정을 동시에 지원합니다. 다른 계정을 추가하려면 로그인 명령을 다시 실행하세요:

openclaw channels login --channel openclaw-weixin

각 QR 코드 스캔은 새로운 계정 항목을 생성합니다. 모든 계정은 서로 방해받지 않고 병렬로 실행됩니다.

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

기본적으로 모든 채널은 동일한 AI 대화 컨텍스트를 공유합니다. 이는 WeChat 대화와 다른 채널(Telegram, Discord 등)이 동일한 AI 메모리를 공유한다는 의미입니다.

각 WeChat 계정이 자체적으로 격리된 컨텍스트를 가지도록 하려면:

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 엔드포인트

플러그인은 5개의 HTTP JSON 엔드포인트를 사용합니다:

엔드포인트	경로	목적
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

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

미디어 파일은 업로드 전에 AES-128-ECB로 암호화됩니다. 흐름은 다음과 같습니다:

파일 메타데이터(크기, MD5)와 함께 getUploadUrl 호출
미리 서명된 CDN 업로드 매개변수 수신
AES-128-ECB로 파일 암호화
미리 서명된 URL을 사용하여 CDN에 업로드
sendMessage에서 CDN 파일 참조

일반적인 문제 및 해결 방법

플러그인 로드 거부

오류: 시작 시 플러그인 로드 거부

해결 방법: OpenClaw 버전을 확인하세요. 플러그인 v2.0.x는 >=2026.3.22 버전을 필요로 합니다.

openclaw --version
# 구버전이라면 먼저 OpenClaw를 업데이트하세요

QR 코드 만료

오류: 스캔하기 전에 QR 코드 시간이 초과됨

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

openclaw channels login --channel openclaw-weixin

메시지 수신 안 됨

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

해결 방법: 로그인 후 게이트웨이를 다시 시작하세요.

openclaw gateway restart

여러 계정 컨텍스트 혼합

오류: 한 계정의 AI 응답이 다른 계정에 나타남

해결 방법: 채널별 컨텍스트 격리를 활성화하세요.

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

실제 사용 사례

개인 AI 비서

개인 WeChat을 OpenClaw에 연결하고 바쁠 때 AI 비서가 메시지에 응답하도록 설정하세요. 각 연락처가 대화 기록을 기반으로 개인화된 응답을 받도록 컨텍스트 격리를 설정하세요.

소규모 사업 고객 지원

다양한 사업 부문에 대해 여러 WeChat 계정을 운영하세요. 각 계정은 격리된 AI 메모리로 자체 고객 문의를 처리합니다. 계정 간 교차 오염이 없습니다.

개발자 테스트

HTTP JSON API를 사용하여 사용자 지정 통합을 구축하세요. 플러그인의 백엔드 프로토콜은 완전히 문서화되어 있어 기본 동작을 쉽게 확장하거나 교체할 수 있습니다.

결론

WeChat과 OpenClaw를 설정하는 데 5분도 채 걸리지 않습니다. 플러그인을 설치하고, QR 코드를 스캔하고, 게이트웨이를 다시 시작하면 끝입니다. 이 무료 설정은 여러 계정, 컨텍스트 격리, 그리고 모든 미디어 지원(이미지, 음성, 파일, 비디오)을 제공합니다.

개발자의 경우, 문서화된 HTTP JSON API를 통해 사용자 지정 통합을 쉽게 할 수 있습니다.

원클릭 설치 관리자로 시작하세요:

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

다음 단계: WeChat 봇이 실행되면 결제 게이트웨이, CRM, 날씨 서비스 등 외부 API에 연결해야 할 것입니다. Apidog로 API를 테스트하여 봇이 매번 올바른 데이터를 전송하는지 확인하세요. 무료 등급을 사용할 수 있으며 신용 카드 정보는 필요하지 않습니다.

button

자주 묻는 질문

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

A: 네. 대부분의 WeChat 자동화 도구와 달리 이 플러그인은 개인 계정으로 작동합니다. 기업 또는 공식 계정은 필요하지 않습니다.

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 통합을 테스트하고 검증하세요.