Zalo (Bot API)

상태: 실험적. DM이 지원되며, 명시적 그룹 정책 제어로 그룹 처리가 가능합니다.

플러그인 필요

Zalo는 플러그인으로 제공되며 기본 코어에 포함되지 않습니다.

  • CLI로 설치: openclaw plugins install @openclaw/zalo
  • 또는 온보딩 중 Zalo를 선택하고 설치 프롬프트를 확인
  • 자세한 내용: Plugins

빠른 설정 (초보자)

  1. Zalo 플러그인을 설치합니다:
    • 소스 체크아웃에서: openclaw plugins install ./extensions/zalo
    • npm에서 (발행된 경우): openclaw plugins install @openclaw/zalo
    • 또는 온보딩에서 Zalo를 선택하고 설치 프롬프트를 확인
  2. 토큰을 설정합니다:
    • 환경 변수: ZALO_BOT_TOKEN=...
    • 또는 설정: channels.zalo.botToken: "...".
  3. 게이트웨이를 재시작합니다 (또는 온보딩을 완료합니다).
  4. DM 접근은 기본적으로 페어링입니다. 첫 연락 시 페어링 코드를 승인하세요.

최소 설정:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

개요

Zalo는 베트남에서 많이 사용되는 메시징 앱입니다. Bot API를 통해 게이트웨이가 1:1 대화용 봇을 실행할 수 있습니다. Zalo로의 결정적 라우팅이 필요한 지원이나 알림에 적합합니다.

  • 게이트웨이가 소유하는 Zalo Bot API 채널.
  • 결정적 라우팅: 응답은 Zalo로 돌아갑니다. 모델은 채널을 선택하지 않습니다.
  • DM은 에이전트의 메인 세션을 공유합니다.
  • 그룹은 정책 제어 (groupPolicy + groupAllowFrom)로 지원되며 기본적으로 실패 폐쇄 허용 목록 동작을 사용합니다.

설정 (빠른 경로)

1) 봇 토큰 생성 (Zalo Bot Platform)

  1. https://bot.zaloplatforms.com에서 로그인합니다.
  2. 새 봇을 생성하고 설정을 구성합니다.
  3. 봇 토큰을 복사합니다 (형식: 12345689:abc-xyz).

2) 토큰 설정 (환경 변수 또는 설정)

예시:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

환경 변수 옵션: ZALO_BOT_TOKEN=... (기본 계정에만 적용).

다중 계정 지원: channels.zalo.accounts에 계정별 토큰과 선택적 name을 사용합니다.

  1. 게이트웨이를 재시작합니다. 토큰이 해석되면 (환경 변수 또는 설정) Zalo가 시작됩니다.
  2. DM 접근은 기본적으로 페어링입니다. 봇에 처음 연락하면 코드를 승인하세요.

동작 방식

  • 인바운드 메시지는 미디어 자리 표시자와 함께 공유 채널 엔벨로프로 정규화됩니다.
  • 응답은 항상 동일한 Zalo 채팅으로 라우팅됩니다.
  • 기본적으로 롱 폴링; channels.zalo.webhookUrl로 웹훅 모드를 사용할 수 있습니다.

제한

  • 아웃바운드 텍스트는 2000자로 분할됩니다 (Zalo API 제한).
  • 미디어 다운로드/업로드는 channels.zalo.mediaMaxMb(기본 5)로 제한됩니다.
  • 2000자 제한으로 스트리밍의 유용성이 떨어져 기본적으로 스트리밍이 차단됩니다.

접근 제어 (DM)

DM 접근

  • 기본값: channels.zalo.dmPolicy = "pairing". 알 수 없는 발신자에게 페어링 코드를 보내며, 승인될 때까지 메시지가 무시됩니다 (코드는 1시간 후 만료).
  • 승인:
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
  • 페어링은 기본 토큰 교환입니다. 자세한 내용: Pairing
  • channels.zalo.allowFrom은 숫자 사용자 ID를 허용합니다 (사용자 이름 조회 불가).

접근 제어 (그룹)

  • channels.zalo.groupPolicy는 그룹 인바운드 처리를 제어합니다: open | allowlist | disabled.
  • 기본 동작은 실패 폐쇄: allowlist.
  • channels.zalo.groupAllowFrom은 그룹에서 봇을 트리거할 수 있는 발신자 ID를 제한합니다.
  • groupAllowFrom이 미설정이면 Zalo는 발신자 확인을 위해 allowFrom으로 폴백합니다.
  • groupPolicy: "disabled"는 모든 그룹 메시지를 차단합니다.
  • groupPolicy: "open"은 모든 그룹 구성원을 허용합니다 (멘션 게이팅).
  • 런타임 참고: channels.zalo가 완전히 없으면 안전을 위해 groupPolicy="allowlist"로 폴백합니다.

롱 폴링 vs 웹훅

  • 기본값: 롱 폴링 (공개 URL 불필요).
  • 웹훅 모드: channels.zalo.webhookUrl과 channels.zalo.webhookSecret을 설정하세요.
    • 웹훅 시크릿은 8-256자여야 합니다.
    • 웹훅 URL은 HTTPS를 사용해야 합니다.
    • Zalo는 검증을 위해 X-Bot-Api-Secret-Token 헤더와 함께 이벤트를 보냅니다.
    • 게이트웨이 HTTP는 channels.zalo.webhookPath (기본값: 웹훅 URL 경로)에서 웹훅 요청을 처리합니다.
    • 요청은 Content-Type: application/json (또는 +json 미디어 타입)을 사용해야 합니다.
    • 중복 이벤트 (event_name + message_id)는 짧은 재생 기간 동안 무시됩니다.
    • 버스트 트래픽은 경로/소스별로 속도 제한되며 HTTP 429를 반환할 수 있습니다.

참고: getUpdates (폴링)와 웹훅은 Zalo API 문서에 따라 상호 배타적입니다.

지원되는 메시지 유형

  • 텍스트 메시지: 2000자 분할로 완전히 지원합니다.
  • 이미지 메시지: 인바운드 이미지를 다운로드하고 처리합니다. sendPhoto로 이미지를 보냅니다.
  • 스티커: 로그되지만 완전히 처리되지 않습니다 (에이전트 응답 없음).
  • 미지원 유형: 로그됩니다 (예: 보호된 사용자의 메시지).

기능

기능상태
다이렉트 메시지지원됨
그룹정책 제어로 지원됨 (기본 허용 목록)
미디어 (이미지)지원됨
리액션미지원
스레드미지원
투표미지원
네이티브 명령미지원
스트리밍차단됨 (2000자 제한)

전달 대상 (CLI/cron)

  • 채팅 ID를 대상으로 사용합니다.
  • 예시: openclaw message send --channel zalo --target 123456789 --message "hi".

문제 해결

봇이 응답하지 않는 경우:

  • 토큰이 유효한지 확인: openclaw channels status --probe
  • 발신자가 승인되었는지 확인 (페어링 또는 allowFrom)
  • 게이트웨이 로그 확인: openclaw logs --follow

웹훅이 이벤트를 수신하지 않는 경우:

  • 웹훅 URL이 HTTPS를 사용하는지 확인
  • 시크릿 토큰이 8-256자인지 확인
  • 게이트웨이 HTTP 엔드포인트가 설정된 경로에서 접근 가능한지 확인
  • getUpdates 폴링이 실행 중이 아닌지 확인 (상호 배타적)

설정 레퍼런스 (Zalo)

전체 설정: Configuration

제공자 옵션:

  • channels.zalo.enabled: 채널 시작 활성화/비활성화.
  • channels.zalo.botToken: Zalo Bot Platform의 봇 토큰.
  • channels.zalo.tokenFile: 일반 파일 경로에서 토큰 읽기. 심볼릭 링크 거부.
  • channels.zalo.dmPolicy: pairing | allowlist | open | disabled (기본값: pairing).
  • channels.zalo.allowFrom: DM 허용 목록 (사용자 ID). open은 "*" 필요. 마법사가 숫자 ID를 요청합니다.
  • channels.zalo.groupPolicy: open | allowlist | disabled (기본값: allowlist).
  • channels.zalo.groupAllowFrom: 그룹 발신자 허용 목록 (사용자 ID). 미설정 시 allowFrom으로 폴백.
  • channels.zalo.mediaMaxMb: 인바운드/아웃바운드 미디어 상한 (MB, 기본값 5).
  • channels.zalo.webhookUrl: 웹훅 모드 활성화 (HTTPS 필수).
  • channels.zalo.webhookSecret: 웹훅 시크릿 (8-256자).
  • channels.zalo.webhookPath: 게이트웨이 HTTP 서버의 웹훅 경로.
  • channels.zalo.proxy: API 요청용 프록시 URL.

다중 계정 옵션:

  • channels.zalo.accounts.<id>.botToken: 계정별 토큰.
  • channels.zalo.accounts.<id>.tokenFile: 계정별 일반 토큰 파일. 심볼릭 링크 거부.
  • channels.zalo.accounts.<id>.name: 표시 이름.
  • channels.zalo.accounts.<id>.enabled: 계정 활성화/비활성화.
  • channels.zalo.accounts.<id>.dmPolicy: 계정별 DM 정책.
  • channels.zalo.accounts.<id>.allowFrom: 계정별 허용 목록.
  • channels.zalo.accounts.<id>.groupPolicy: 계정별 그룹 정책.
  • channels.zalo.accounts.<id>.groupAllowFrom: 계정별 그룹 발신자 허용 목록.
  • channels.zalo.accounts.<id>.webhookUrl: 계정별 웹훅 URL.
  • channels.zalo.accounts.<id>.webhookSecret: 계정별 웹훅 시크릿.
  • channels.zalo.accounts.<id>.webhookPath: 계정별 웹훅 경로.
  • channels.zalo.accounts.<id>.proxy: 계정별 프록시 URL.
arrow_back
이전
Whatsapp
다음
Zalouser
arrow_forward