OpenClaw

OpenClaw Zalo Personal 채널

메시징
보통

비공식 zca-cli 도구를 사용하여 OpenClaw를 개인 Zalo 계정에 연결합니다. Zalo Bot Platform 통합과 달리, 이 채널은 AI 어시스턴트가 실제 Zalo 개인 계정을 통해 작동합니다 — 그룹 채팅, 미디어, 친구 목록을 지원합니다. QR 코드를 스캔하여 인증하면 새 기기를 연결하는 것처럼 간단합니다.

기본 정보
난이도보통
카테고리메시징
지원 기능 수3 / 6

Zalo Personal 지원 기능

텍스트 메시지

지원

미디어 및 파일

지원

리액션

미지원

스레드

미지원

음성 메시지

미지원

그룹 채팅

지원

Zalo Personal 사전 요구사항

  • Zalo 개인 계정(표준 계정, Official Account 아님)
  • zca 바이너리가 설치되고 시스템 PATH에서 사용 가능
  • OpenClaw Gateway가 실행 중이고 설정 완료
  • 로그인 시 QR 코드 스캔용 Zalo 모바일 앱

Zalo Personal 빠른 설정

1

zalouser 플러그인과 zca-cli 설치

'openclaw plugins install @openclaw/zalouser'로 OpenClaw 플러그인을 설치합니다. 그런 다음 zca-cli 도구를 설치하고 PATH에 포함되었는지 확인합니다. 'zca --version'으로 검증하세요.

2

QR 코드로 로그인

'openclaw channels login --channel zalouser'를 실행하여 터미널에 QR 코드를 표시합니다. 스마트폰에서 Zalo 앱을 열고 QR 코드를 스캔하여 인증을 완료합니다.

3

설정 후 채팅 시작

zalouser 채널 설정을 ~/.openclaw/openclaw.json에 추가하고 dmPolicy와 groupPolicy를 설정합니다. 'openclaw start'로 Gateway를 시작하고 Zalo 계정에 메시지를 보내 테스트합니다.

Zalo Personal 구성 예시

config.json
{
  "channels": {
    "zalouser": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "open"
    }
  }
}

Zalo Personal 상세 문서

아키텍처 개요

OpenClaw는 zca-cli 도구를 통해 Zalo에 연결합니다 — Zalo 개인 계정용 비공식 명령줄 클라이언트입니다. Zalo Bot Platform 통합(HTTP API 사용)과 달리, 이 채널은 zca 바이너리를 사용하여 수신 메시지를 수신하고 발신 응답을 전송합니다. Gateway는 백그라운드에서 'zca listen' 프로세스를 실행하여 실시간으로 메시지를 수신하고, 'zca msg'를 사용하여 응답을 전송합니다. 이 방식은 완전히 로컬에서 작동합니다 — 공용 URL, Webhook, HTTPS 인증서가 필요 없습니다. 개인 계정을 사용하므로 봇은 그룹 채팅에 참여하고, 친구 목록에 접근하고, 미디어를 전송할 수 있습니다 — 공식 Bot Platform에서는 사용할 수 없는 기능입니다.
이것은 비공식 통합입니다. 사용 시 계정 정지 또는 차단 위험이 있습니다. 주요 개인 계정 대신 전용 계정을 사용하세요.
zca-cli 도구는 프로토콜 계층을 처리합니다. Zalo 서비스와의 호환성을 유지하기 위해 최신 상태로 유지하세요.
이것은 비공식 도구를 사용하는 실험적 통합입니다. Zalo는 서드파티 자동화를 사용하는 계정을 정지하거나 차단할 수 있습니다. 사용에 따른 위험은 본인이 부담합니다.

zca-cli 설치

zca-cli 바이너리는 이 채널의 전제 조건입니다. Gateway가 Zalo Personal 채널을 사용하려면 설치되어 시스템 PATH에서 접근 가능해야 합니다. 설치 후 터미널에서 'zca --version'을 실행하여 정상 작동을 확인합니다. 명령이 발견되지 않으면 PATH 설정을 확인하거나 재설치하세요.
terminal
zca --version
zca가 설치되어 있지만 PATH에 없는 경우, 쉘 프로파일(~/.bashrc, ~/.zshrc 등)에서 해당 디렉토리를 PATH에 추가할 수 있습니다.

QR 코드 인증

인증은 Zalo 모바일 앱으로 QR 코드를 스캔하여 수행합니다 — 새 기기를 연결하는 방법과 유사합니다. API 토큰이나 Bot 토큰이 필요 없습니다. 로그인 명령을 실행하여 터미널에 QR 코드를 표시합니다. 스마트폰에서 Zalo를 열고 QR 스캐너로 이동하여 코드를 스캔합니다. 세션이 설정되고 자격 증명이 로컬에 저장됩니다. 재시작 후 로그인이 유지되지 않으면 로그아웃 후 다시 로그인하여 세션을 새로고침하세요.
terminal
# 로그인
openclaw channels login --channel zalouser

# 로그인이 유지되지 않으면 재인증
openclaw channels logout --channel zalouser
openclaw channels login --channel zalouser
QR 코드 스캔 중 스마트폰을 인터넷에 연결된 상태로 유지하세요. 세션은 Zalo 서버를 통해 검증됩니다.

DM 정책

DM(다이렉트 메시지) 정책은 개인 메시지를 통해 AI 어시스턴트와 대화할 수 있는 사용자를 제어합니다. OpenClaw는 네 가지 정책을 지원합니다: • pairing(기본값) — 새 연락처가 처음 메시지를 보내면 페어링 코드를 받습니다. 'openclaw pairing approve zalouser <code>'로 승인합니다. 코드는 1시간 후 만료됩니다. • allowlist — allowFrom 목록에 있는 사용자 ID 또는 이름만 봇과 대화할 수 있습니다. 이름은 'zca friend find'로 ID로 변환됩니다. • open — 계정에 메시지를 보내는 모든 사람이 응답을 받습니다. • disabled — DM 처리를 완전히 비활성화합니다.
openclaw.json
{
  "channels": {
    "zalouser": {
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789", "친구 이름"]
    }
  }
}
'open' 정책은 누구나 개인 계정과 대화할 수 있게 합니다. 이것은 연락처에게 보이는 실제 Zalo 계정이므로 주의하여 사용하세요.

그룹 채팅 관리

Zalo Bot Platform 통합과 달리, Zalo Personal은 그룹 채팅을 완전히 지원합니다. 기본적으로 groupPolicy는 'open'으로 설정되어 봇이 모든 그룹 대화에서 응답합니다. 'allowlist' 정책과 groups 매핑을 사용하여 그룹 접근을 제한할 수 있습니다. 그룹은 숫자 ID 또는 이름으로 참조할 수 있습니다. groupPolicy를 'disabled'로 설정하면 모든 그룹 메시지를 완전히 무시합니다.
openclaw.json
{
  "channels": {
    "zalouser": {
      "groupPolicy": "allowlist",
      "groups": {
        "123456789": { "allow": true },
        "업무 채팅": { "allow": true }
      }
    }
  }
}
'openclaw directory groups list --channel zalouser --query "이름"'을 사용하여 그룹 ID와 이름을 검색할 수 있습니다.
그룹 이름은 대소문자를 구분합니다. Zalo 앱에 표시된 정확한 이름을 사용하세요.

메시지 처리

OpenClaw는 Zalo Personal을 통해 텍스트 메시지, 이미지, 파일, 링크 전송을 지원합니다. 텍스트 메시지는 Zalo 클라이언트 제한에 따라 약 2,000자 단위로 자동 분할됩니다. 연락처와 그룹의 수신 메시지는 'zca listen' 프로세스로 수신되어 AI로 전달됩니다. 발신 응답은 'zca msg'를 사용하여 전송됩니다. 문자 수 제한으로 인해 스트리밍 응답은 기본적으로 차단됩니다.
긴 AI 응답은 약 2,000자 경계에서 자동으로 여러 메시지로 분할됩니다.
미디어 전송 기능은 설치된 zca-cli 버전에 따라 다릅니다. 최상의 호환성을 위해 최신 상태로 유지하세요.

다중 계정 설정

OpenClaw는 다른 zca 프로파일에 매핑하여 여러 Zalo 개인 계정의 동시 실행을 지원합니다. 각 계정에는 고유한 프로파일 이름, DM 정책, 그룹 설정이 있습니다. 다른 용도(예: 업무 계정과 개인 계정)로 별도의 AI 어시스턴트를 운영하려는 경우 유용합니다.
openclaw.json
{
  "channels": {
    "zalouser": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "work": {
          "enabled": true,
          "profile": "work"
        },
        "personal": {
          "enabled": true,
          "profile": "personal"
        }
      }
    }
  }
}

디렉토리 및 검색

Zalo Personal 채널은 계정의 친구와 그룹을 검색하기 위한 디렉토리 명령을 제공합니다. 허용 목록용 사용자 ID나 그룹 정책용 그룹 ID를 찾는 데 유용합니다. 자신의 프로필 보기, 이름으로 친구 검색, 이름으로 그룹 검색이 모두 명령줄에서 가능합니다.
terminal
# 프로필 보기
openclaw directory self --channel zalouser

# 친구 검색
openclaw directory peers list --channel zalouser --query "이름"

# 그룹 검색
openclaw directory groups list --channel zalouser --query "업무"

Zalo Personal 구성 참조

enabled
Type: booleanDefault: false

Zalo Personal 채널 활성화 또는 비활성화

dmPolicy
Type: stringDefault: "pairing"

봇에게 DM할 수 있는 사용자를 제어. 옵션: pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

봇과 대화를 허용할 사용자 ID 또는 이름 목록(dmPolicy가 allowlist인 경우)

groupPolicy
Type: stringDefault: "open"

그룹 채팅 동작을 제어. 옵션: open, allowlist, disabled

groups
Type: objectDefault: {}

그룹 ID 또는 이름에서 권한 객체로의 매핑(groupPolicy가 allowlist인 경우)

defaultAccount
Type: stringDefault: "default"

사용할 기본 zca 프로파일 이름

accounts.<id>.enabled
Type: booleanDefault: true

다중 계정 모드에서 특정 계정 활성화 또는 비활성화

accounts.<id>.profile
Type: stringDefault: ""

특정 계정의 zca 프로파일 이름

Zalo Personal 자주 묻는 질문

Zalo Personal 문제 해결

zca 명령을 찾을 수 없음

zca-cli 바이너리가 설치되지 않았거나 시스템 PATH에 없습니다.

zca-cli를 설치하고 PATH에 포함되었는지 확인하세요. 'zca --version'으로 검증합니다. 설치되어 있지만 찾을 수 없는 경우, ~/.bashrc 또는 ~/.zshrc에서 설치 디렉토리를 PATH에 추가하세요.
QR 코드 로그인 실패 또는 세션이 유지되지 않음

Zalo 세션이 만료되었거나 초기 인증이 완료되지 않았을 수 있습니다.

로그아웃 후 다시 로그인해 보세요: 'openclaw channels logout --channel zalouser' 후 'openclaw channels login --channel zalouser'. QR 스캔 중 스마트폰의 인터넷 연결이 안정적인지 확인하세요.
봇이 그룹 메시지에 응답하지 않음

groupPolicy가 'disabled'로 설정되어 있거나 'allowlist'에 해당 그룹이 포함되지 않았을 수 있습니다.

groupPolicy 설정을 확인하세요. 'allowlist'를 사용하는 경우 그룹 ID 또는 이름이 groups 설정에 포함되었는지 확인합니다. 'openclaw directory groups list --channel zalouser'로 올바른 그룹 ID를 찾으세요.
메시지가 수신되지 않음

zca listen 프로세스가 실행되지 않거나 세션이 만료되었을 수 있습니다.

'openclaw channels status --probe'를 실행하여 연결을 진단합니다. 세션이 만료된 경우 QR 코드 로그인으로 재인증하세요. Gateway 로그에서 구체적인 오류 메시지를 확인하세요.
계정이 정지 또는 차단됨

Zalo가 계정에서 비공식 자동화를 감지했습니다.

이것은 비공식 통합 사용의 알려진 위험입니다. Zalo 지원팀에 연락하여 계정 복구를 시도하세요. 그룹 채팅은 지원되지 않지만 차단 위험이 없는 공식 Zalo Bot Platform 통합(zalo 채널)으로 전환을 고려하세요.
전체 문서 보기모든 채널로 돌아가기

관련 채널

WhatsApp

Medium

OpenClaw Baileys 프로토콜을 사용한 QR 코드 연결

설정 가이드

Telegram

Easy

OpenClaw grammY 프레임워크를 통한 Bot API 통합

설정 가이드

Discord

Easy

OpenClaw discord.js를 사용한 Bot Token 통합

설정 가이드