Zalo

​

번들 Plugin

• 설치: openclaw plugins install @openclaw/zalo
• 버전 고정: openclaw plugins install @openclaw/zalo@2026.6.11
• 로컬 체크아웃에서 설치: openclaw plugins install ./path/to/local/zalo-plugin
• 자세한 내용: Plugin

​

빠른 설정

1. https://bot.zaloplatforms.com에서 봇 토큰을 생성합니다(로그인하고 봇을 만든 다음 설정을 구성합니다). 토큰 형식은 numeric_id:secret이며, Marketplace 봇의 경우 사용 가능한 런타임 토큰이 봇의 환영 메시지에 표시될 수 있습니다.
2. 환경 변수 ZALO_BOT_TOKEN=...(기본 계정에만 적용) 또는 구성에서 토큰을 설정합니다.
3. Gateway를 다시 시작합니다.
4. 첫 번째 DM 연락 시 페어링 코드를 승인합니다(기본 DM 정책은 페어링입니다).

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

​

개요

​

작동 방식

• 수신 메시지는 미디어 자리표시자와 함께 공유 채널 엔벌로프로 정규화됩니다.
• 응답은 항상 동일한 Zalo 채팅으로 다시 라우팅되며, 인용 답장은 사용되지 않습니다(replyToMode는 항상 꺼져 있습니다).
• 기본적으로 롱 폴링(getUpdates)을 사용하며, channels.zalo.webhookUrl을 통해 Webhook 모드를 사용할 수 있습니다.
• 그룹에서는 봇을 작동시키려면 @멘션이 필요하며, 채널별로 구성할 수 없습니다.

​

제한

​

접근 제어

​

다이렉트 메시지

• channels.zalo.dmPolicy: pairing(기본값) | allowlist | open | disabled.
• 페어링: 알 수 없는 발신자에게 페어링 코드가 제공되며, 승인될 때까지 메시지가 무시됩니다. 코드는 1시간 후 만료됩니다.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • 자세한 내용: 페어링
• channels.zalo.allowFrom에는 숫자로 된 Zalo 사용자 ID를 사용할 수 있습니다(사용자 이름 조회는 지원하지 않음). open에는 "*"가 필요합니다.

​

그룹

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom은 그룹에서 봇을 작동시킬 수 있는 발신자 ID를 제한하며, 설정하지 않으면 allowFrom으로 대체됩니다.
• 기본 해석: channels.zalo가 구성되어 있고 groupPolicy가 설정되지 않은 경우 open으로 해석됩니다. channels.zalo가 완전히 누락된 경우 런타임은 안전을 위해 allowlist로 제한됩니다.
• 실제 환경에서 보고된 주의 사항: 일부 Marketplace 봇 설정에서는 봇을 그룹에 전혀 추가할 수 없었습니다. 이 문제가 발생하면 봇의 Zalo Bot Platform 설정을 확인하세요. 이는 OpenClaw 정책이 아니라 플랫폼 측 제약입니다.

​

롱 폴링과 Webhook 비교

• 기본값: 롱 폴링(공개 URL 불필요).
• Webhook 모드: channels.zalo.webhookUrl 및 channels.zalo.webhookSecret을 설정합니다.
  • Webhook URL은 HTTPS를 사용해야 합니다.
  • Webhook 시크릿은 8~256자여야 합니다.
  • Zalo는 X-Bot-Api-Secret-Token 헤더와 함께 이벤트를 전송하며, 이 헤더는 상수 시간 비교를 통해 확인됩니다.
  • Gateway HTTP는 channels.zalo.webhookPath에서 Webhook 요청을 처리합니다(기본값은 Webhook URL의 경로).
  • 요청은 Content-Type: application/json 또는 +json 미디어 유형을 사용해야 합니다.
  • Zalo API 문서에 따르면 getUpdates 폴링과 Webhook은 함께 사용할 수 없습니다.

​

지원되는 메시지 유형

• 텍스트: 완전히 지원되며 2000자 단위로 분할됩니다.
• 미디어: 수신/발신을 지원하며 mediaMaxMb로 제한됩니다.
• 반응, 스레드, 설문 조사, 네이티브 명령: Plugin에서 지원되지 않습니다.
• 스트리밍: Plugin은 블록 스트리밍 기능을 선언하지만, Zalo에는 일부 다른 지역 채널과 달리 전용 발신 대기열/텍스트 병합 조정 옵션이 없습니다. 이 기능이 사용 사례에 중요하다면 현재 환경에서 동작을 확인하세요.

​

기능

​

전송 대상(CLI/Cron)

openclaw message send --channel zalo --target 123456789 --message "hi"

​

문제 해결

• 토큰을 확인합니다: openclaw channels status --probe
• 발신자가 승인되었는지 확인합니다(페어링 또는 allowFrom)
• Gateway 로그를 확인합니다: openclaw logs --follow

• Webhook URL이 HTTPS를 사용하는지 확인합니다
• 시크릿이 8~256자인지 확인합니다
• 구성된 경로에서 Gateway HTTP 엔드포인트에 접근할 수 있는지 확인합니다
• getUpdates 폴링이 함께 실행되고 있지 않은지 확인합니다(둘은 함께 사용할 수 없음)
• 요청이 급증하면 HTTP 429가 반환될 수 있습니다(경로+IP당 60초 동안 요청 120개). 잠시 기다린 후 다시 시도하세요

​

구성 참조

​

관련 항목

• 채널 개요 - 지원되는 모든 채널
• 페어링 - DM 인증 및 페어링 흐름
• 그룹 - 그룹 채팅 동작 및 멘션 제한
• 채널 라우팅 - 메시지의 세션 라우팅
• 보안 - 접근 모델 및 보안 강화