English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

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/[email protected]
  • 또는 소스 체크아웃에서 설치: 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. 채널을 활성화합니다.
{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}
  1. Gateway를 다시 시작합니다(또는 설정을 완료합니다).
  2. 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에는 안정적인 Zalo 사용자 ID를 사용해야 합니다. 대화형 설정 중 입력한 이름은 Plugin의 프로세스 내부 연락처 조회를 사용해 ID로 확인할 수 있습니다.

원시 이름이 설정에 남아 있으면 시작 시 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화된 경우에만 이를 확인합니다. 이 옵트인이 없으면 런타임 발신자 검사는 ID만 사용하며 원시 이름은 권한 부여에서 무시됩니다.

다음으로 승인합니다.

  • openclaw pairing list zalouser
  • openclaw pairing approve zalouser <code>

그룹 액세스(선택 사항)

  • 기본값: channels.zalouser.groupPolicy = "open"(그룹 허용). 설정되지 않은 경우 기본값을 재정의하려면 channels.defaults.groupPolicy를 사용하세요.
  • allowlist로 제한:
    • channels.zalouser.groupPolicy = "allowlist"
    • channels.zalouser.groups(키는 안정적인 그룹 ID여야 합니다. 이름은 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화된 경우에만 시작 시 ID로 확인됩니다)
    • channels.zalouser.groupAllowFrom(허용된 그룹에서 어떤 발신자가 봇을 트리거할 수 있는지 제어)
  • 모든 그룹 차단: channels.zalouser.groupPolicy = "disabled".
  • 구성 마법사는 그룹 allowlist를 입력하도록 요청할 수 있습니다.
  • 시작 시 OpenClaw는 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화된 경우에만 allowlist의 그룹/사용자 이름을 ID로 확인하고 매핑을 로그에 기록합니다.
  • 그룹 allowlist 매칭은 기본적으로 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).
  • 이는 allowlist에 있는 그룹과 열린 그룹 모드 모두에 적용됩니다.
  • 봇 메시지를 인용하면 그룹 활성화를 위한 암시적 멘션으로 간주됩니다.
  • 권한이 있는 제어 명령(예: /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는 답장을 디스패치하기 전에 입력 중 이벤트를 보냅니다(최선 노력).
  • 메시지 반응 액션 react는 채널 액션에서 zalouser에 대해 지원됩니다.
    • 메시지에서 특정 반응 이모지를 제거하려면 remove: true를 사용하세요.
    • 반응 의미 체계: 반응
  • 이벤트 메타데이터가 포함된 인바운드 메시지의 경우 OpenClaw는 전달됨 + 읽음 확인을 보냅니다(최선 노력).

문제 해결

로그인이 유지되지 않는 경우:

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

Allowlist/그룹 이름이 확인되지 않은 경우:

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

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

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

관련 항목