2026 WECHAT
CLAWBOT_
OFFICIAL_
BIND_RUNBOOK.

개인 WeChat 안에서 OpenClaw를 쓰려면 Tencent 공식 ClawBot 플러그인과 레거시 서드파티 브리지를 구분해야 합니다. 2026년 3월부터 npm에 @tencent-weixin/openclaw-weixin-cli가 공개되었고, WeChat 「설정 → 플러그인」에서 ClawBot을 켠 뒤 QR로 Gateway를 바인딩합니다. 본문은 사전 게이트, 원클릭·수동 설치, 6단계 Runbook, 리스크 매트릭스, 현장 사례, 수치 SLO를 다룹니다. WeChat 쪽은 휴대폰 온라인 + 그레이 롤아웃, 서버 쪽은 24/7 Gateway가 전제입니다—노트북이 잠들면 채널이 끊기므로, 원격 Mac 수용 호스트가 실무적인 프로덕션 패턴입니다. 시나리오 구분은 멀티 플랫폼 Channel, WeCom(기업 WeChat) 자동화, 설치 후 Gateway 미준비와 교차 링크합니다.

1. ClawBot vs 서드파티 브리지

ClawBot은 OpenClaw용 WeChat 공식 플러그인 경로이며, @tencent-weixin/openclaw-weixin으로 인증합니다. 스크래핑 Web 프로토콜이 아닙니다. DM(1:1) 워크플로를 겨냥하며, WeCom(기업) 봇 문서와는 채널·자격 증명이 다릅니다. 비공식 브리지는 단기 동작해도 계정·약관 리스크가 큽니다. 프로덕션은 Tencent 채널을 표준화하고 Gateway를 상시 온라인 하드웨어에 두세요—로컬 상시 Mac 또는 launchd로 관리하는 원격 Mac.

검색·온보딩 문서에서 흔한 혼동은 「개인 WeChat ClawBot」과 「기업 WeChat OpenClaw」를 같은 티켓으로 묶는 경우입니다. CorpID·AgentId·콜백 URL이 있는 기업 시나리오는 본 Runbook 범위 밖이며, DM 스캔·단일 연락처 대화가 목표일 때만 이 채널을 선택하십시오. 레거시 「Web 로그인 에뮬레이션」류 도구는 버전 업데이트마다 깨지기 쉬우므로, 장애 시 롤백 경로가 없는 팀은 특히 공식 CLI 경로로 고정하는 편이 안전합니다.

2. 사전 수용 검증(다섯 게이트)

게이트 A: openclaw --version ideally ≥ 2026.3.22 및 openclaw doctor. 게이트 B: Node.js 22+와 올바른 global npm PATH. 게이트 C: WeChat 클라이언트 ≥ 8.0.70, 실명·장기 계정 권장. 게이트 D: 플러그인 목록에 ClawBot 표시—없으면 그레이 미포함, 비공식 도구로 대체하지 마세요. 게이트 E: openclaw gateway status healthy, QR 스캔 전 /health 2초 이내.

게이트 E가 실패하면 QR을 찍어도 「연락처는 생겼는데 메시지가 안 온다」는 반쪽 성공만 남습니다. 원격 Mac에서는 SSH로 동일 명령을 실행하고, launchd plist의 EnvironmentVariables가 대화형 셸과 일치하는지 Gateway·PATH Runbook과 대조하십시오. 바인딩 호스트와 일상 SSH 작업 호스트가 다르면, 나중에 「집에서 스캔·회사에서 확인」 같은 엔드포인트 드리프트가 재현됩니다.

3. 의사결정 매트릭스

시나리오	경로	비고
최초 랩 바인딩	npx @tencent-weixin/openclaw-weixin-cli install	가장 빠른 QR 플로우
감사 대상 프로덕션	수동 plugins install + config	변경 티켓 친화
npm 타임아웃	미러 레지스트리 후 재시도	플러그인 활성화 전 스캔 금지
업그레이드 후 무응답	plugins.entries.openclaw-weixin.enabled 확인	2026.3.22+ 플러그인 키 변경
노트북 슬립으로 DM 끊김	원격 Mac Gateway에서 재바인딩	바인딩은 엔드포인트별

4. 6단계 Runbook

Step 1 WeChat에서 ClawBot 활성화

WeChat 업데이트 → 설정 → 플러그인 → ClawBot 켜기. 항목이 없으면 버전을 기록(그레이 대기).

Step 2 Gateway 가동 증명

바인딩 호스트에서 openclaw gateway status, curl -m 3 http://127.0.0.1:18789/health(원격 Mac은 SSH).

Step 3 채널 설치

Step 4 QR 즉시 스캔

QR은 빨리 만료됩니다. 오래된 스크린샷 재사용 금지, 만료 시 Step 3 재실행. 터미널 폰트가 작으면 확대 후 스캔하십시오.

Step 5 송수신 검증

DM 테스트 연락처에 짧은 문장을 보내고, 동시에 openclaw channels status --probe와 openclaw logs --follow로 openclaw-weixin 이벤트를 봅니다. 수신만 되고 발신이 실패하면 WeChat 레이어보다 모델 API 키·쿼터·Gateway RPC 지연(HTTP/RPC 타임아웃)을 먼저 분리하십시오. 한 턴에 파일 쓰기·exec Skill을 켜기 전, 단순 텍스트 3라운드로 컨텍스트가 유지되는지 확인하면 이후 장애 범위를 줄일 수 있습니다.

Step 6 원격 30분 소크

MACGPU 또는 자체 원격 Mac 대조 노드에서 Step 2–5를 반복합니다. 노트북 뚜껑을 닫아도 WeChat이 도달 가능한지 확인한 뒤, probe가 연속 30분 녹색일 때만 프로덕션 계정으로 트래픽을 옮기십시오. 대조 노드에는 스냅샷·설정 diff를 남겨, 재스캔 시 「어제와 오늘 Gateway 설정 차이」를 티켓에 첨부할 수 있게 합니다.

5. 함정 매트릭스

영역	리스크	완화
범위	DM 우선, 그룹 기능 제한	지원 그룹을 여기에 매핑하지 말 것
계정	주 WeChat + 강력 Agent 도구	보조 계정 전용, exec 제한
컴플라이언스	트래픽이 WeChat 인프라 경유	고위험 자동응답 템플릿 회피
업그레이드	플러그인 로드 순서 변경	전후 doctor + probe
가동률	오프라인 Gateway = WeChat 침묵	슬립 노트북 대신 원격 Mac launchd

6. 계층형 트러블슈팅

플러그인 목록에 ClawBot 없음: 그레이 미포함—대기하거나 이미 그레이된 테스트 계정으로 검증.스캔 후 연락처 없음: Gateway 미재시작 또는 plugins.entries.openclaw-weixin.enabled false.수신만 됨: enabled·18789 방화벽·Tailscale/SSH 터널이 로컬 루프백만 가리키는지 확인.npx 실패: npm config set registry https://registry.npmmirror.com 후 재시도, 플러그인 미설치 상태에서 QR 반복 금지.업그레이드 후 장애: openclaw doctor --fix → gateway restart --force --wait; ~/.openclaw 무단 삭제 금지(백업·diff 선행).

로그에 websocket disconnect가 반복되면 「API 장애」가 아니라 프로세스·호스트 슬립을 의심하십시오. pmset·에너지 세이버·Docker Desktop 일시 중지가 Gateway PID를 함께 내리는 경우가 많습니다. 원격 Mac에서는 openclaw gateway install --force와 launchd 재적재 후 동일 QR로 재바인딩하고, 호스트명·바인딩 시각을 운영 위키에 고정 기록하십시오.

7. 사례: QR 성공, 출퇴근 중 침묵

팀은 초기에 Tencent API를 의심했으나 로그는 로컬 슬립과 websocket 채널 종료를 보여줬습니다. 24/7 원격 Mac에서 재바인딩하니 SLA가 회복됐습니다. 교훈: ClawBot은 스캔 당시 온라인이던 Gateway 엔드포인트에 묶인다—호스트 변경 시 재페어링과 운영 Runbook 항목이 필요합니다.

8. 업계 인사이트

IM 벤더가 네이티브 Agent 채널을 출시하면서 운영 부담은 자체 호스팅 Gateway로 이동합니다. WeChat 도달 범위는 크지만 SLO는 서버 측 관측·롤백에 달립니다. Windows/Linux VPS에서도 OpenClaw는 가능하나, 많은 팀이 ClawHub Skills·미디어 도구 때문에 macOS 골든 호스트를 유지합니다. Apple Silicon 원격 Mac은 프로덕션 WeChat 트래픽 전 30분 probe 창을 돌리는 일반적 장소입니다. MACGPU 원격 Mac 렌탈은 디스크 격리, 스냅샷 롤백, 로그 재생을 제공하되 WeChat 계정 컴플라이언스 책임은 사용자에게 있습니다.

9. 참조 임계값

WeChat < 8.0.70: 먼저 업그레이드. OpenClaw < 2026.3.22: 업그레이드 + doctor. 스캔 후 5분간 probe 적색: 라이브 금지. 파일 쓰기 Skills 전 DM 3턴 컨텍스트 유지. Gateway 변경 후 원격 호스트 30분 녹색 probe.

운영 티켓에는 「WeChat 버전 / OpenClaw 빌드 / 바인딩 호스트명 / QR 시각 / probe 스크린샷」 다섯 항목을 기본 첨부로 두면, Tencent 측 그레이 이슈와 자체 Gateway 슬립을 빠르게 가릴 수 있습니다.

10. FAQ

ClawBot과 WeCom OpenClaw는 같은가요? 아닙니다. WeCom은 기업 앱·CorpID 경로이고, ClawBot은 개인 WeChat 공식 플러그인 채널입니다.Mac이 필수인가요? OpenClaw는 크로스 플랫폼이나, 본문의 7×24 수용·ClawHub·미디어 Skill 디버깅에는 Apple Silicon 원격 Mac이 자주 쓰입니다.QR이 만료되면? npx … install 또는 channels login을 다시 실행하십시오.그룹 채팅은? 현재 제품 설명 기준 DM을 기본으로 계획하고, 그룹 요구는 별도 채널(예: Telegram·钉钉·飛書)을 검토하십시오.MACGPU 역할은? 대조 노드·로그 재생·스냅샷을 제공하며, WeChat 계정·콘텐츠 컴플라이언스 책임은 고객에게 있습니다.