Zalo 개인용

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

번들 Plugin

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

​

빠른 설정(초보자)

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

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

4. Gateway를 다시 시작합니다(또는 설정을 완료합니다).
5. DM 액세스는 기본적으로 페어링을 사용합니다. 첫 연락 시 페어링 코드를 승인하세요.

​

개요

• zca-js를 통해 완전히 프로세스 내부에서 실행됩니다.
• 네이티브 이벤트 리스너를 사용해 수신 메시지를 받습니다.
• 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를 사용합니다.
• allowlist로 제한:
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups(키는 안정적인 그룹 ID여야 합니다. 이름은 channels.zalouser.dangerouslyAllowNameMatching: true가 활성화된 경우에만 시작 시 ID로 해석됩니다)
  • channels.zalouser.groupAllowFrom(허용된 그룹에서 어떤 발신자가 봇을 트리거할 수 있는지 제어합니다. 정적 발신자 액세스 그룹은 accessGroup:<name>으로 참조할 수 있습니다)
• 모든 그룹 차단: 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/name -> 정규화된 그룹 슬러그 -> * -> 기본값(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 },
      },
    },
  },
}

​

다중 계정

{
  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

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

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

​

관련 항목

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