OpenClaw WeChat 연결 튜토리얼

서문

WeChat은 중국에서 가장 주류인 인스턴트 메시징 도구입니다. OpenClaw를 WeChat에 연결하면 개인 AI 어시스턴트를 가질 수 있으며, 그룹 채팅에서 구성원들에게 지능형 질의응답 서비스를 제공할 수도 있습니다. 이 글에서는 WeChat 연동의 다양한 방식과 설정 방법을 상세히 설명합니다.

연동 방식 개요

WeChat에는 공식적인 Bot API가 없으므로 OpenClaw는 서드파티 브리지 솔루션을 통해 WeChat 연동을 구현합니다:

방식	원리	안정성	위험 등급
Web 프로토콜 (UOS)	웹 WeChat 로그인 시뮬레이션	보통	중
Wechaty Puppet	Wechaty 프레임워크를 통한 브리지	높음	낮음-중
iPad 프로토콜	iPad 클라이언트 시뮬레이션	높음	낮음
기업 WeChat API	기업 WeChat 공식 인터페이스 사용	최상	최저

중요 안내

주의: 개인 WeChat 연동은 비공식 방식이며 로그인이 제한될 위험이 있습니다.
테스트에는 부계정을 사용하시기 바라며, 절대 주 WeChat 계정을 사용하지 마십시오.
기업 WeChat API는 공식적으로 지원되는 방식으로, 기업급 배포에 적합합니다.

방식 1: Wechaty 브리지 (추천)

Wechaty는 성숙한 챗봇 SDK로, OpenClaw에는 Wechaty 지원이 내장되어 있습니다.

1.1 Wechaty 의존성 설치

시스템에 Node.js 22+ 이상이 설치되어 있는지 확인한 후 Wechaty를 설치합니다:

npm install -g wechaty

1.2 Puppet 선택

Wechaty는 Puppet을 통해 다양한 WeChat 프로토콜에 연결합니다:

Puppet	프로토콜	비용	설명
wechaty-puppet-wechat4u	Web 프로토콜	무료	기능 제한, 일부 계정 미지원
wechaty-puppet-padlocal	iPad 프로토콜	유료	완전한 기능, 추천
wechaty-puppet-xp	Windows Hook	무료	Windows 환경 필요
wechaty-puppet-service	원격 서비스	상황별	원격 Puppet 서비스에 연결

무료 방안은 wechat4u를 사용합니다:

npm install wechaty-puppet-wechat4u

1.3 OpenClaw 설정

~/.config/openclaw/openclaw.json5를 편집합니다:

{
  channels: {
    wechat: {
      enabled: true,
      // 브리지 방식
      bridge: "wechaty",

      // Wechaty Puppet 설정
      puppet: {
        // puppet 이름
        name: "wechaty-puppet-wechat4u",
        // 유료 puppet 사용 시 token 입력
        token: ""
      },

      // 트리거 방식
      trigger: {
        // 개인 채팅 자동 응답 여부 (키워드 불필요)
        privateAutoReply: true,
        // 그룹 채팅 트리거 키워드 (이 단어로 시작해야 응답)
        groupKeywords: ["@AI", "질문할게", "/ask"],
        // 그룹 채팅에서 @Bot 멘션이 필요한지 여부
        groupMentionRequired: true,
        // 자신이 보낸 메시지에 응답할지 여부
        selfMessage: false
      },

      // 응답 설정
      reply: {
        // 그룹 채팅 응답 시 원본 메시지 인용 여부
        quoteReply: true,
        // "입력 중" 상태 표시 여부
        showTyping: true,
        // 긴 텍스트 자동 분할 글자 수
        maxLength: 4000
      }
    }
  }
}

1.4 시작 및 QR 코드 스캔 로그인

설정 완료 후 OpenClaw를 재시작합니다:

openclaw restart

로그에서 로그인 QR 코드를 확인합니다:

openclaw logs -f --component channel:wechat

로그에 QR 코드가 표시됩니다 (터미널 문자 아트 형태). 로그인할 WeChat 계정으로 해당 QR 코드를 스캔하고 휴대폰에서 로그인을 확인합니다.

[INFO] [channel:wechat] QR 코드 스캔 대기 중...
[INFO] [channel:wechat] WeChat으로 아래 QR 코드를 스캔해 주십시오:
[INFO] [channel:wechat] ████████████████████████████████
[INFO] [channel:wechat] █                              █
[INFO] [channel:wechat] █  ▄▄▄▄▄ █ █ ▄ █▀▄▀ █ ▄▄▄▄▄  █
[INFO] [channel:wechat] █  ...(QR 코드 내용)...         █
[INFO] [channel:wechat] ████████████████████████████████

스캔 성공 후:

[INFO] [channel:wechat] 스캔 성공, 확인 대기 중...
[INFO] [channel:wechat] 로그인 성공! 현재 계정: AI 어시스턴트
[INFO] [channel:wechat] 연락처 수: 256, 그룹 채팅 수: 15

방식 2: 기업 WeChat API

기업 WeChat은 공식 API 인터페이스를 제공하며, 더 안정적이고 안전합니다.

2.1 기업 WeChat 앱 생성

기업 WeChat 관리 콘솔에 로그인합니다
앱 관리 → 자체 앱 → 앱 생성으로 이동합니다
앱 이름 입력, 아이콘 업로드, 표시 범위 선택
생성 후 AgentId와 Secret을 기록합니다

2.2 필요한 정보 수집

다음 정보가 필요합니다:

파라미터	출처	예시
CorpId	내 기업 → 기업 정보	`ww1234567890abcdef`
AgentId	앱 관리 → 앱 상세	`1000002`
Secret	앱 관리 → 앱 상세	`xxxxxxxxxxxxxxxxxxxx`
Token	메시지 수신 → API 수신	`your-token-string`
EncodingAESKey	메시지 수신 → API 수신	`your-encoding-aes-key`

2.3 콜백 주소 설정

앱의 메시지 수신 설정에서 콜백 URL을 설정합니다:

https://your-domain.com/webhook/wechat-work/callback

OpenClaw는 기업 WeChat의 URL 검증 요청을 자동으로 처리합니다.

2.4 OpenClaw 설정

{
  channels: {
    wechatWork: {
      enabled: true,
      corpId: "ww1234567890abcdef",
      agentId: 1000002,
      secret: "your-app-secret",
      token: "your-callback-token",
      encodingAESKey: "your-encoding-aes-key",

      // 허용된 사용자/부서 (빈 배열은 앱 표시 범위 내 모든 사용자 허용)
      allowedUsers: [],
      allowedDepartments: []
    }
  }
}

그룹 채팅 설정 상세

그룹 채팅 트리거 규칙

그룹 채팅에서는 Bot의 잦은 방해를 방지하기 위해 일반적으로 특정 트리거 방식이 필요합니다:

{
  channels: {
    wechat: {
      trigger: {
        groupMentionRequired: true,
        groupKeywords: ["@AI", "질문할게"],
        // 지정된 그룹 채팅에서만 활성화
        allowedGroups: ["기술 토론 그룹", "AI 어시스턴트 테스트 그룹"],
        // 또는 특정 그룹 제외
        ignoredGroups: ["가족 그룹", "업무 그룹"]
      }
    }
  }
}

그룹 채팅 컨텍스트 관리

{
  channels: {
    wechat: {
      context: {
        // 그룹 채팅에서 사용자별 독립 컨텍스트
        groupContextMode: "per-user",  // "per-user" | "shared"
        // 컨텍스트 유지 시간 (분)
        contextTimeout: 30,
        // 최대 컨텍스트 메시지 라운드 수
        maxContextTurns: 20
      }
    }
  }
}

메시지 유형 지원

OpenClaw의 WeChat 메시지 유형별 지원 현황:

메시지 유형	수신	전송	설명
텍스트 메시지	지원	지원	완전 지원
이미지 메시지	지원	지원	이미지 내용 인식 가능 (멀티모달 모델 필요)
음성 메시지	지원	미지원	자동으로 텍스트 변환 후 처리
파일 메시지	지원	지원	문서 분석 지원
링크 메시지	지원	미지원	링크 내용 추출 가능
이모티콘	미지원	미지원	무시 처리
미니프로그램	미지원	미지원	무시 처리
동영상 메시지	부분	미지원	Puppet 기능에 따라 다름

영구 로그인

매 재시작마다 QR 코드를 다시 스캔하는 것을 방지하기 위해 OpenClaw는 로그인 세션을 자동으로 저장합니다:

{
  channels: {
    wechat: {
      // 세션 데이터 저장 경로
      sessionDir: "~/.openclaw/wechat-session/",
      // 세션 갱신 간격 (시간)
      sessionRefresh: 12
    }
  }
}

세션 데이터가 저장된 후 OpenClaw 재시작 시 로그인 상태가 자동으로 복원되어 다시 스캔할 필요가 없습니다. 다만 오랜 기간 비활성 상태가 지속되면 (보통 1주 이상) 세션이 만료되어 다시 스캔해야 합니다.

문제 해결

스캔 후 로그인 실패

# 계정이 제한되었는지 확인
# 일부 신규 등록 또는 오래 사용하지 않은 계정은 Web 프로토콜을 사용할 수 없을 수 있습니다
# 해결 방안: iPad 프로토콜 또는 기업 WeChat 방식으로 변경

# 네트워크 연결 확인
openclaw doctor

메시지 송수신 지연

# 메시지 처리 로그 확인
openclaw logs --component channel:wechat --level debug

# 일반적인 원인:
# 1. AI 모델 응답이 느림 - 모델 API 지연 확인
# 2. 프록시 네트워크가 느림 - 프록시 설정 최적화
# 3. 메시지 큐 적체 - 동시성 설정 확인

그룹 채팅에서 응답 없음

다음 사항을 확인합니다:

Bot 계정이 해당 그룹 채팅에 있는지
그룹 채팅 이름이 allowedGroups 목록에 있는지 (설정한 경우)
메시지가 트리거 조건을 충족하는지 (키워드 또는 @)
로그에 해당 그룹 채팅의 메시지 기록이 있는지

요약

WeChat 연동은 중국 환경에서 OpenClaw의 가장 실용적인 기능 중 하나입니다. 몇 가지 제안사항:

개인 사용: Wechaty + wechat4u (무료) 방식으로 빠르게 체험하는 것을 추천합니다
안정성 요구: 유료 iPad 프로토콜 Puppet을 고려하시면 안정성이 더 좋습니다
기업 시나리오: 기업 WeChat API를 강력히 추천합니다. 공식 지원이며 계정 차단 위험이 없습니다
보안 인식: 비공식 프로토콜 사용 시 부계정으로 테스트하고 위험 평가를 수행하십시오