OpenClaw Zalo 개인 계정 연동: 5분 만에 설정하기

개인용 메신저 계정을 자동화하려고 할 때, 공식 API가 없어서 답답했던 적 많으시죠? 특히 Zalo처럼 폐쇄적인 플랫폼은 개발자에게 큰 벽으로 느껴지곤 해요. 이제 OpenClaw를 통해 개인 Zalo 계정을 스마트하게 자동화하고 워크플로우에 연결해 보세요.

Zalo Personal (비공식)

상태: 실험적 기능. 이 통합은 OpenClaw 내부에서 네이티브 zca-js를 통해 개인 Zalo 계정을 자동화합니다.

경고: 이 기능은 비공식 통합이며 계정 정지 또는 차단될 위험이 있습니다. 본인의 책임 하에 사용하세요.

필요한 플러그인

Zalo Personal은 플러그인으로 제공되며 코어 설치에 포함되어 있지 않습니다.

CLI를 통해 설치: openclaw plugins install @openclaw/zalouser
또는 소스 체크아웃에서 설치: openclaw plugins install ./path/to/local/zalouser-plugin
상세 내용: Plugins

별도의 외부 zca/openzca CLI 바이너리는 필요하지 않습니다.

빠른 설정 (초보자용)

플러그인을 설치하세요 (위 내용 참고).
로그인 (Gateway가 실행 중인 머신에서 QR 코드 사용):
- openclaw channels login --channel zalouser
- Zalo 모바일 앱으로 QR 코드를 스캔하세요.
채널 활성화:

{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

Gateway를 재시작하세요 (또는 설정을 완료하세요).
DM 액세스 기본값은 페어링 모드입니다. 처음 연락이 올 때 페어링 코드를 승인하세요.

이 기능은 무엇인가요?

zca-js를 통해 프로세스 내부에서 완전히 실행됩니다.
네이티브 이벤트 리스너를 사용하여 수신 메시지를 받습니다.
JS API를 통해 직접 답장을 보냅니다 (텍스트/미디어/링크).
Zalo Bot API를 사용할 수 없는 “개인 계정” 유스케이스를 위해 설계되었습니다.

이름 지정

채널 ID는 zalouser입니다. 이는 비공식적으로 개인 Zalo 사용자 계정을 자동화한다는 점을 명확히 하기 위함입니다. zalo라는 이름은 향후 공식 Zalo API 통합을 위해 예약해 두었습니다.

ID 찾기 (디렉토리)

디렉토리 CLI를 사용하여 피어/그룹과 해당 ID를 찾을 수 있습니다:

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"

제한 사항

발신 텍스트는 약 2000자 단위로 잘려서 전송됩니다 (Zalo 클라이언트 제한).
스트리밍은 기본적으로 차단됩니다.

액세스 제어 (DM)

channels.zalouser.dmPolicy는 pairing | allowlist | open | disabled를 지원합니다 (기본값: pairing).

channels.zalouser.allowFrom은 사용자 ID나 이름을 허용합니다. 설정 과정에서 이름은 플러그인의 프로세스 내 연락처 조회를 통해 ID로 변환됩니다.

다음 명령어로 승인하세요:

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

그룹 액세스 (선택 사항)

기본값: channels.zalouser.groupPolicy = "open" (그룹 허용). 설정되지 않았을 때 기본값을 변경하려면 channels.defaults.groupPolicy를 사용하세요.
화이트리스트로 제한하려면:
- channels.zalouser.groupPolicy = "allowlist"
- channels.zalouser.groups (키는 고정된 그룹 ID여야 합니다. 이름은 가능한 경우 시작 시 ID로 변환됩니다)
- channels.zalouser.groupAllowFrom (허용된 그룹 내에서 어떤 발신자가 봇을 트리거할 수 있는지 제어합니다)
모든 그룹 차단: channels.zalouser.groupPolicy = "disabled".
설정 위저드에서 그룹 화이트리스트 입력을 요청할 수 있습니다.
시작 시 OpenClaw는 화이트리스트의 그룹/사용자 이름을 ID로 변환하고 매핑 정보를 로그에 남깁니다.
그룹 화이트리스트 매칭은 기본적으로 ID 전용입니다. channels.zalouser.dangerouslyAllowNameMatching: true가 활성화되지 않은 경우, 확인되지 않은 이름은 인증에서 무시됩니다.
channels.zalouser.dangerouslyAllowNameMatching: true는 변경 가능한 그룹 이름 매칭을 다시 활성화하는 비상 호환 모드입니다.
groupAllowFrom이 설정되지 않은 경우, 런타임은 그룹 발신자 확인을 위해 allowFrom을 대신 사용합니다.
발신자 확인은 일반 그룹 메시지와 제어 명령(예: /new, /reset) 모두에 적용됩니다.

예시:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

그룹 멘션 게이팅

channels.zalouser.groups.<group>.requireMention은 그룹 답장에 멘션이 필요한지 여부를 제어합니다.
확인 순서: 정확한 그룹 ID/이름 -> 정규화된 그룹 슬러그 -> * -> 기본값 (true).
이는 화이트리스트에 등록된 그룹과 공개 그룹 모드 모두에 적용됩니다.
인증된 제어 명령(예: /new)은 멘션 게이팅을 우회할 수 있습니다.
멘션이 필요해서 그룹 메시지를 건너뛸 때, OpenClaw는 이를 대기 중인 그룹 히스토리로 저장하고 다음 처리되는 그룹 메시지에 포함합니다.
그룹 히스토리 제한 기본값은 messages.groupChat.historyLimit (기본값 50)입니다. 계정별로 channels.zalouser.historyLimit을 사용하여 재정의할 수 있습니다.

예시:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { allow: true, requireMention: true },
        "Work Chat": { allow: true, requireMention: false },
      },
    },
  },
}

다중 계정

계정은 OpenClaw 상태의 zalouser 프로필에 매핑됩니다. 예시:

{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}

입력 중 표시, 리액션 및 전송 확인

OpenClaw는 답장을 보내기 전에 입력 중(typing) 이벤트를 보냅니다 (최선 노력 원칙).
채널 액션에서 zalouser에 대한 메시지 리액션 동작 react를 지원합니다.
- 메시지에서 특정 리액션 이모지를 제거하려면 remove: true를 사용하세요.
- 리액션 의미론: Reactions
이벤트 메타데이터가 포함된 수신 메시지에 대해 OpenClaw는 전송 완료(delivered) 및 읽음(seen) 확인을 보냅니다 (최선 노력 원칙).

문제 해결

로그인이 유지되지 않음:

openclaw channels status --probe
다시 로그인: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

화이트리스트/그룹 이름이 확인되지 않음:

allowFrom/groupAllowFrom/groups에 숫자 ID를 사용하거나, 정확한 친구/그룹 이름을 사용하세요.

이전 CLI 기반 설정에서 업그레이드한 경우:

이전의 외부 zca 프로세스 관련 설정을 모두 제거하세요.
이제 채널은 외부 CLI 바이너리 없이 OpenClaw 내부에서 완전히 실행됩니다.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.