​

Zalo Personal (비공식)

경고: 이는 비공식 통합이며 계정 정지/차단으로 이어질 수 있습니다. 본인 책임하에 사용하세요.

​

번들 plugin

• CLI로 설치: openclaw plugins install @openclaw/zalouser
• 또는 소스 체크아웃에서 설치: openclaw plugins install ./path/to/local/zalouser-plugin
• 자세한 내용: Plugins

​

빠른 설정(초보자용)

1. Zalo Personal plugin을 사용할 수 있는지 확인합니다.
   • 현재 패키지된 OpenClaw 릴리스에는 이미 번들로 포함되어 있습니다.
   • 이전/사용자 지정 설치는 위 명령으로 수동 추가할 수 있습니다.
2. 로그인합니다(QR, 게이트웨이 머신에서):
   • openclaw channels login --channel zalouser
   • Zalo 모바일 앱으로 QR 코드를 스캔합니다.
3. 채널을 활성화합니다:

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

4. 게이트웨이를 재시작합니다(또는 설정을 완료합니다).
5. DM 액세스는 기본적으로 pairing이며, 첫 연락 시 페어링 코드를 승인합니다.

​

개요

• 전부 zca-js를 통해 인프로세스로 실행됩니다.
• native 이벤트 리스너를 사용해 수신 메시지를 받습니다.
• JS API를 통해 직접 응답을 전송합니다(텍스트/미디어/링크).
• Zalo Bot API를 사용할 수 없는 “개인 계정” 사용 사례를 위해 설계되었습니다.

​

이름 지정

​

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)

• 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/이름 -> 정규화된 그룹 slug -> * -> 기본값 (true).
• 이는 허용 목록 그룹과 open 그룹 모드 모두에 적용됩니다.
• 권한 있는 제어 명령(예: /new)은 멘션 게이팅을 우회할 수 있습니다.
• 그룹 메시지가 멘션 필요 때문에 건너뛰어지면 OpenClaw는 이를 보류 중인 그룹 기록으로 저장하고 다음에 처리되는 그룹 메시지에 포함합니다.
• 그룹 기록 제한은 기본적으로 messages.groupChat.historyLimit(대체값 50)입니다. 계정별로 channels.zalouser.historyLimit로 재정의할 수 있습니다.

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

​

다중 계정

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

​

입력 중, 반응 및 전달 확인

• OpenClaw는 응답을 전송하기 전에 입력 중 이벤트를 보냅니다(best-effort).
• 메시지 반응 액션 react는 채널 액션에서 zalouser에 대해 지원됩니다.
  • 메시지에서 특정 반응 이모지를 제거하려면 remove: true를 사용하세요.
  • 반응 의미 체계: Reactions
• 이벤트 메타데이터가 포함된 수신 메시지에 대해서는 OpenClaw가 전달됨 + 확인함 확인 응답을 보냅니다(best-effort).

​

문제 해결

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

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

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

​

관련 항목

• 채널 개요 — 지원되는 모든 채널
• 페어링 — DM 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 — 메시지용 세션 라우팅
• 보안 — 액세스 모델 및 강화