English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Regional platforms

Zalo 개인용

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

번들 Plugin

Zalo Personal은 현재 OpenClaw 릴리스에서 번들 Plugin으로 제공되므로, 일반 패키지 빌드는 별도 설치가 필요하지 않습니다.

Zalo Personal을 제외한 이전 빌드 또는 사용자 지정 설치를 사용 중이라면, npm 패키지를 직접 설치하세요.

  • CLI로 설치: openclaw plugins install @openclaw/zalouser
  • 고정 버전: openclaw plugins install @openclaw/zalouser@2026.5.2
  • 또는 소스 체크아웃에서 설치: openclaw plugins install ./path/to/local/zalouser-plugin
  • 자세히: Plugin

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

빠른 설정(초보자)

  1. Zalo Personal Plugin을 사용할 수 있는지 확인합니다.
    • 현재 패키지된 OpenClaw 릴리스에는 이미 번들로 포함되어 있습니다.
    • 이전/사용자 지정 설치에서는 위 명령으로 수동 추가할 수 있습니다.
  2. 로그인(QR, Gateway 머신에서):
    • openclaw channels login --channel zalouser
    • Zalo 모바일 앱으로 QR 코드를 스캔합니다.
  3. 채널을 활성화합니다.
json5
{  channels: {    zalouser: {      enabled: true,      dmPolicy: "pairing",    },  },}
  1. Gateway를 다시 시작합니다(또는 설정을 완료합니다).
  2. DM 접근은 기본적으로 페어링을 사용합니다. 첫 연락 시 페어링 코드를 승인하세요.

개요

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

이름 지정

채널 ID는 zalouser입니다. 이는 개인 Zalo 사용자 계정(비공식)을 자동화한다는 점을 명확히 하기 위한 것입니다. 향후 공식 Zalo API 통합 가능성을 위해 zalo는 예약해 둡니다.

ID 찾기(디렉터리)

디렉터리 CLI를 사용해 피어/그룹과 해당 ID를 찾습니다.

bash
openclaw directory self --channel zalouseropenclaw 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에는 안정적인 Zalo 사용자 ID를 사용해야 합니다. 정적 발신자 접근 그룹(accessGroup:<name>)도 참조할 수 있습니다. 대화형 설정 중 입력한 이름은 Plugin의 프로세스 내부 연락처 조회를 사용해 ID로 확인할 수 있습니다.

원시 이름이 설정에 남아 있으면 시작 시 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화된 경우에만 확인됩니다. 이 명시적 선택이 없으면 런타임 발신자 검사는 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여야 합니다. 이름은 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화된 경우에만 시작 시 ID로 확인됩니다)
    • channels.zalouser.groupAllowFrom(허용된 그룹에서 어떤 발신자가 bot을 트리거할 수 있는지 제어합니다. 정적 발신자 접근 그룹은 accessGroup:<name>으로 참조할 수 있습니다)
  • 모든 그룹 차단: channels.zalouser.groupPolicy = "disabled".
  • 구성 마법사는 그룹 허용 목록을 입력하라는 프롬프트를 표시할 수 있습니다.
  • 시작 시 OpenClaw는 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화된 경우에만 허용 목록의 그룹/사용자 이름을 ID로 확인하고 매핑을 기록합니다.
  • 그룹 허용 목록 매칭은 기본적으로 ID 전용입니다. 확인되지 않은 이름은 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화되지 않는 한 인증에서 무시됩니다.
  • channels.zalouser.dangerouslyAllowNameMatching: true는 변경 가능한 시작 시 이름 확인과 런타임 그룹 이름 매칭을 다시 활성화하는 비상 호환성 모드입니다.
  • groupAllowFrom이 설정되지 않은 경우 런타임은 그룹 발신자 검사에 allowFrom을 대체로 사용합니다.
  • 발신자 검사는 일반 그룹 메시지와 제어 명령(예: /new, /reset) 모두에 적용됩니다.

예:

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

그룹 멘션 게이팅

  • channels.zalouser.groups.<group>.requireMention은 그룹 답장에 멘션이 필요한지 제어합니다.
  • 확인 순서: 정확한 그룹 ID/이름 -> 정규화된 그룹 슬러그 -> * -> 기본값(true).
  • 이는 허용 목록 그룹과 공개 그룹 모드 모두에 적용됩니다.
  • bot 메시지를 인용하면 그룹 활성화를 위한 암시적 멘션으로 간주됩니다.
  • 승인된 제어 명령(예: /new)은 멘션 게이팅을 우회할 수 있습니다.
  • 멘션이 필요해 그룹 메시지를 건너뛰면 OpenClaw는 이를 대기 중인 그룹 기록으로 저장하고 다음에 처리되는 그룹 메시지에 포함합니다.
  • 그룹 기록 제한은 기본적으로 messages.groupChat.historyLimit입니다(대체값 50). channels.zalouser.historyLimit으로 계정별 재정의할 수 있습니다.

예:

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

다중 계정

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

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

환경 변수

Zalo Personal Plugin은 환경 변수에서도 프로필 선택을 읽을 수 있습니다.

  • ZALOUSER_PROFILE: 채널 또는 계정 설정에 profile이 설정되지 않았을 때 사용할 프로필 이름입니다.
  • ZCA_PROFILE: 레거시 대체 프로필 이름이며, ZALOUSER_PROFILE이 설정되지 않은 경우에만 사용됩니다.

프로필 이름은 OpenClaw 상태에 저장된 Zalo 로그인 자격 증명을 선택합니다. 확인 순서는 다음과 같습니다.

  1. 설정의 명시적 profile.
  2. ZALOUSER_PROFILE.
  3. ZCA_PROFILE.
  4. 기본 계정이 아닌 경우 계정 ID, 기본 계정의 경우 default.

다중 계정 설정에서는 하나의 환경 변수가 여러 계정이 동일한 로그인 세션을 공유하게 만들지 않도록 설정에서 각 계정에 profile을 지정하는 것을 권장합니다.

입력 표시, 반응, 전달 확인

  • OpenClaw는 답장을 전송하기 전에 입력 중 이벤트를 보냅니다(최선 노력).
  • 메시지 반응 작업 react는 채널 작업에서 zalouser에 대해 지원됩니다.
    • 메시지에서 특정 반응 이모지를 제거하려면 remove: true를 사용하세요.
    • 반응 의미론: 반응
  • 이벤트 메타데이터가 포함된 수신 메시지의 경우 OpenClaw는 전달됨 + 읽음 확인을 보냅니다(최선 노력).

문제 해결

로그인이 유지되지 않음:

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

허용 목록/그룹 이름이 확인되지 않음:

  • allowFrom/groupAllowFrom에는 숫자 ID를 사용하고, groups에는 안정적인 그룹 ID를 사용하세요. 정확한 친구/그룹 이름이 의도적으로 필요한 경우 channels.zalouser.dangerouslyAllowNameMatching: true를 활성화하세요.

이전 CLI 기반 설정에서 업그레이드함:

  • 예전 외부 zca 프로세스에 대한 가정을 제거하세요.
  • 이제 채널은 외부 CLI 바이너리 없이 OpenClaw 내부에서 완전히 실행됩니다.

관련 항목

Was this useful?
On this page

On this page