openclaw-weixin-cli · QR 바인딩 · 그레이스케일 플러그인 · Gateway 재시작 · 운영 Runbook
WeChat에서 ClawBot을 열고 OpenClaw Gateway를 통해 AI Agent와 대화하려다 npx @tencent-weixin/openclaw-weixin-cli 실행 후 QR 스캔 실패, 연락처 미표시, Gateway 재시작 뒤 응답 중단 같은 증상을 겪고 계신가요? 본문은 2026년 기준 공식 플러그인 경로를 전제로 사전 점검, 설치 Runbook, 바인딩 검수, 운영 주의사항을 한 번에 정리합니다. Gateway 설치 트러블슈팅 체크리스트와 멀티채널 강화 체크리스트를 함께 읽는 것을 권장합니다.
2026년 Tencent가 제공하는 WeChat ClawBot은 WeChat 클라이언트 내 공식 플러그인으로 AI 대화를 가능하게 하는 기능입니다. OpenClaw 측에서는 @tencent-weixin/openclaw-weixin 패키지가 Gateway의 채널 플러그인으로 동작하며, Telegram·Discord와 동급의 IM 진입점이 됩니다. 서드파티 Webhook 브리지나 개인 bot 프레임워크와 달리, 메시지는 WeChat 공식 클라이언트 ↔ Gateway ↔ 모델 백엔드라는 정규 경로를 따릅니다.
아키텍처상 ClawBot은 「WeChat 전용 대화 UI」, OpenClaw는 「스킬 실행·모델 라우팅·상시 Gateway」 역할을 분담합니다. OpenClaw 2026.3.22 이후 릴리스에서는 플러그인 API가 안정화되어 openclaw plugins install로 WeChat 채널을 추가할 수 있습니다. 모델이 클라우드 API인지 Ollama 로컬인지는 WeChat 채널과 무관합니다.
공식 vs 비공식: 운영 환경에서는 @tencent-weixin 스코프의 CLI/플러그인만 사용하고, 비공식 브리지는 키 유출·약관 위반 위험이 있습니다.
Gateway 필수: WeChat 이벤트는 Gateway가 수신해 Skill과 모델로 라우팅합니다. Gateway 미기동 시 QR 바인딩도 완료되지 않습니다.
24/7 전제: 노트북 절전은 WeChat 응답 SLA를 깨뜨립니다. 클라우드 Mac 상시 가동 가이드와 동일한 유형의 과제입니다.
그레이스케일: WeChat 클라이언트와 ClawBot 플러그인은 지역·버전별 단계 공개 중입니다. 최신 안정판 업데이트가 선행 조건입니다.
1:1 중심: 2026년 현재 그룹 대화·파일 전송에 제한이 있습니다. 유스케이스를 1:1 상담으로 한정해 설계하세요.
다음 절에서는 설치 전 반드시 확인할 버전·계정·노드 선정 체크리스트를 제시합니다.
ClawBot 도입 실패의 상당수는 「CLI는 성공했지만 WeChat 측 미지원」입니다. 아래 항목을 티켓에 붙인 뒤 Runbook으로 진행하세요.
| 항목 | 확인 내용 | 미달 시 전형적 증상 |
|---|---|---|
| WeChat 클라이언트 | 최신 안정판, ClawBot 플러그인 그레이스케일 활성 | 설정에 ClawBot 진입점 없음, QR 무효 |
| OpenClaw | 2026.3.22+, Node 22.14+, openclaw doctor 정상 | 플러그인 API 불일치, Gateway 기동 실패 |
| WeChat 계정 | 실명 인증 완료, 운영용 서브 계정 분리 권장 | 바인딩 거부, 이용 제한 |
| 실행 노드 | Gateway 24/7, 18789 계열 포트 도달 | 응답 지연, 재시작 후 무응답 |
| npm 레지스트리 | 공식 npm 또는 신뢰 가능한 미러 | npx 타임아웃, checksum 오류 |
WeChat은 클라이언트 측 그레이스케일이 마지막 관문입니다. 서버만 준비해도 단말이 대상 외이면 바인딩은 시작되지 않습니다.
개인 검증은 노트북에서도 가능하지만, 운영 IM 연동에서는 Docker/VPS 또는 Docker Compose 운영 베이스라인에 맞춘 격리 배포를 권장합니다. WeChat API 키와 Telegram 키는 별도 파일·별도 환경 변수로 관리하고, 멀티채널 강화 체크리스트의 최소 권한 원칙을 따르세요.
2026년 권장 경로는 두 가지입니다. 초회 검증은 npx @tencent-weixin/openclaw-weixin-cli, 운영·재현성 중시는 openclaw plugins install입니다. 어느 쪽이든 Gateway 기동 전후 순서를 지켜야 합니다.
Gateway 사전 확인: openclaw gateway status가 healthy입니다. openclaw doctor --fix로 Node와 포트를 맞춥니다.
경로 A — npx CLI: 아래 명령으로 플러그인 설치와 바인딩 마법사를 시작합니다. 대화형으로 QR이 표시됩니다.
경로 B — 수동 플러그인: openclaw plugins install @tencent-weixin/openclaw-weixin 후 설정 파일에서 채널을 활성화합니다.
Gateway 재시작: 플러그인 추가 후 반드시 openclaw gateway restart가 필요합니다. channels 캐시 갱신에 필수입니다.
openclaw doctor --fix openclaw gateway status npx @tencent-weixin/openclaw-weixin-cli install openclaw plugins install @tencent-weixin/openclaw-weixin openclaw gateway restart openclaw channels status
npx @tencent-weixin/openclaw-weixin-cli bind openclaw logs --follow openclaw channels status --channel weixin
팁: npm 미러 사용 시 @tencent-weixin 스코프 동기화 여부를 확인하세요. 오래된 캐시는 npm cache clean --force 후 재실행합니다.
바인딩 성공 판정은 「WeChat 연락처에 ClawBot 표시 + 테스트 문구가 Gateway 로그에 기록 + Agent 회신」 세 가지입니다. Telegram BotFather 토큰 방식과 절차가 다릅니다.
| 채널 | 인증 방식 | 콜백 | 운영 주의 |
|---|---|---|---|
| WeChat ClawBot | QR 스캔 + 플러그인 그레이스케일 | Gateway 상시 가동, WeChat 클라이언트 의존 | 1:1만, 파일 제한, 계정 분리 |
| Telegram | Bot Token + webhook/setWebhook | 공인 HTTPS 필수 | 그룹·채널 지원, Token 로테이션 |
| Discord | Bot Intents + Gateway WS | Intents 설정 오류 시 무음 | Guild 권한, Slash 명령 |
QR 표시: CLI QR은 보통 2~3분 내 만료됩니다. 만료 시 bind를 재실행하고 WeChat 「扫一扫」를 신속히 완료하세요.
연락처 확인: WeChat 연락처 목록에 ClawBot이 추가됐는지 눈으로 확인합니다.
첫 회环: 짧은 텍스트(예: ping)를 보내고 openclaw logs --follow로 inbound/outbound를 확인합니다.
channels status: openclaw channels status에서 weixin이 connected로 표시되는 것을 검수 기준으로 삼습니다.
회신이 없으면 모델 API가 아니라 채널 계층을 먼저 의심하세요. Gateway 트러블슈팅 체크리스트의 3단계 로그(Gateway → 채널 → 모델)를 따르면 이분 탐색이 빨라집니다.
| 증상 | 우선 확인 | 흔한 조치 |
|---|---|---|
| QR 스캔 실패 | WeChat 버전, 그레이스케일, QR 만료 | 클라이언트 업데이트, bind 재실행 |
| 메시지 미수신 | Gateway 중지, channels status | gateway restart, 3단계 로그 확인 |
| 재시작 후 무응답 | 플러그인 로드, WeChat 세션 | 재바인딩, 설정 파일 weixin 활성화 확인 |
| npx 타임아웃 | npm 미러, 네트워크 | 공식 registry, 프록시 재검토 |
| 파일·이미지 불가 | 2026 기능 제한 | 텍스트 전용 Skill 설계로 한정 |
@tencent-weixin/openclaw-weixin semver를 compose 또는 lockfile에 고정해 예기치 않은 메이저 업데이트를 막습니다.주의: 동일 변경 티켓에서 WeChat 재바인딩, Gateway 이미지 업데이트, 모델 API Key 로테이션을 동시에 수행하지 마세요. 삼각 변경은 원인 특정을 불가능하게 합니다.
WeChat ClawBot을 팀에서 쓰려면 Gateway가 상시 기동·모니터링 가능·키 분리되어야 합니다. 노트북 검증 후에는 Ollama나 클라우드 API와 마찬가지로 원격 노드로 이전하는 것이 정석입니다.
Docker Compose 운영 베이스라인에 따라 Gateway 컨테이너를 127.0.0.1에 바인딩하고 WeChat 플러그인을 볼륨에 영속화합니다. 로그는 Gateway → 채널 → 모델 순으로 분리하고, 주간 openclaw channels status 자동 점검을 넣으세요.
Apple Silicon 통합 메모리와 낮은 전력 소비는 WeChat 응답 체감 latency에도 영향을 줍니다. 전용 연산과 감사 가능한 변경이 필요한 팀에는 VpsMesh Mac Mini 클라우드 임대로 Gateway를 24/7 상시 가동시키는 구성이 적합합니다. 요금은 가격 페이지, 절차는 고객 센터, 주문은 주문 페이지를 참고하세요. 클라우드 Mac 상시 가동 가이드와 병행하면 WeChat·Telegram 멀티채널 운영까지 일원화할 수 있습니다.
네. 각 IM은 Gateway의 독립 채널입니다. WeChat 플러그인과 Telegram Bot을 병행 활성화할 수 있습니다. 필요한 것은 Gateway 24/7과 openclaw channels status 정기 확인입니다. 자세히는 멀티채널 강화 체크리스트를 참고하세요.
WeChat 클라이언트를 최신판으로 업데이트하고 ClawBot 플러그인 그레이스케일 활성 여부를 확인하세요. Gateway가 healthy일 때 npx @tencent-weixin/openclaw-weixin-cli bind를 재실행하고 QR 만료 전에 스캔을 완료합니다. 계속 실패하면 Gateway 트러블슈팅 체크리스트로 Node와 포트를 확인하세요.
openclaw gateway restart 후 openclaw channels status --channel weixin을 확인하고 connected가 아니면 재바인딩합니다. 운영 환경에서는 24/7 상시 가동 가이드에 맞춘 데몬과 원격 Mac 주문을 통한 노드 고정을 검토하세요.