Zalo ClawBot

OpenClaw는 카탈로그에 등록된 외부 @zalo-platforms/openclaw-zaloclawbot Plugin을 통해 Zalo ClawBot에 연결합니다. 로그인은 Zalo Mini App QR 코드를 사용합니다.

호환성

필수 조건

• Node.js >= 22
• OpenClaw가 설치되어 있어야 합니다(openclaw CLI 사용 가능).
• 로그인 QR 코드를 스캔할 모바일 기기의 Zalo 계정.

onboard로 설치(권장)

OpenClaw 온보딩 마법사를 실행하고 채널 메뉴에서 Zalo ClawBot을 선택합니다.

openclaw onboard

마법사는 공식 카탈로그에서 Plugin을 설치하고(무결성 검증), 터미널에 로그인 QR을 바로 표시하며, Zalo 앱으로 스캔하면 채널 설정을 완료합니다. 추가 명령은 필요하지 않습니다.

수동 설치

이미 온보딩된 Gateway에 채널을 추가하려면 다음 단계를 따르세요.

1. Plugin 설치

openclaw plugins install "@zalo-platforms/openclaw-zaloclawbot@0.1.4"

위에 표시된 정확한 고정 버전을 사용하세요(공식 카탈로그 항목과 일치). 그러면 OpenClaw가 설치 중에 카탈로그 무결성 해시와 대조해 패키지를 검증합니다.

2. 구성에서 Plugin 활성화

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

3. QR 코드 생성 및 로그인

openclaw channels login --channel openclaw-zaloclawbot

Zalo 모바일 앱으로 터미널에 표시된 QR 코드를 스캔하고, Zalo Mini App 안에서 이용 약관에 동의한 다음 세션을 승인합니다.

4. Gateway 재시작

openclaw gateway restart

작동 방식

자체 Zalo Official Account(OA)를 등록하고 정적 개발자 자격 증명을 붙여 넣어야 하는 표준 개발자 Zalo 채널과 달리, Zalo ClawBot은 공유 공식 인프라를 사용하는 소유자 귀속 개인 비서로 작동합니다.

1. 보안 온보딩: QR 코드는 공유 공식 OA 아래 새로 프로비저닝된 비공개 봇을 사용자의 Zalo User ID에 직접 바인딩하는 안전한 Zalo Mini App으로 연결됩니다.
2. 소유자 귀속 개인정보 보호: 설계상 봇은 오직 소유자와만 통신하도록 제한됩니다. 다른 사용자의 메시지는 플랫폼 수준에서 삭제되므로 연결이 비공개로 안전하게 유지됩니다.
3. 공식 API 경로: Plugin은 브라우저나 웹 세션 자동화 대신 Zalo Bot Platform API를 사용합니다.

내부 구조

Zalo ClawBot Plugin은 지속적인 롱 폴링 메시지 루프를 통해 Zalo API와 통신합니다. 깔끔하고 가벼운 런타임을 유지하기 위해 다음과 같이 동작합니다.

• 롱 폴 연결은 getUpdates 엔드포인트를 사용합니다.
• 로컬 데스크톱/터미널 Gateway 실행에서는 Webhook이 기본적으로 비활성화됩니다.
• 메시지는 클라이언트 측에서 처리되며 로컬 에이전트 런타임에 직접 매핑됩니다.

외부 Plugin은 OpenClaw 상태 디렉터리 아래에서 봇 자격 증명을 관리합니다. 해당 디렉터리를 민감한 것으로 취급하고, 나머지 OpenClaw 상태와 동일한 접근 제어 및 백업 정책에 포함하세요.

문제 해결

• QR 로그인 시간 초과: 로그인 토큰(zbsk)은 보안상의 이유로 5분 후 만료됩니다. 스캔하기 전에 QR 코드가 만료되면 로그인 명령을 다시 실행해 새 코드를 생성하면 됩니다.
• Gateway 로드 실패: OpenClaw 호스트 버전이 2026.4.10 이상인지 확인하세요. 이전 버전은 외부 npm Plugin 설치 원장을 지원하지 않습니다.