Zalo

​

번들 Plugin

• CLI로 설치: openclaw plugins install @openclaw/zalo
• 고정 버전: openclaw plugins install @openclaw/zalo@2026.5.2
• 또는 소스 체크아웃에서 설치: openclaw plugins install ./path/to/local/zalo-plugin
• 세부 정보: Plugins

​

빠른 설정(초보자)

1. Zalo Plugin을 사용할 수 있는지 확인합니다.
   • 현재 패키지된 OpenClaw 릴리스에는 이미 번들로 포함되어 있습니다.
   • 이전/사용자 지정 설치에서는 위 명령으로 수동 추가할 수 있습니다.
2. 토큰을 설정합니다.
   • Env: ZALO_BOT_TOKEN=...
   • 또는 config: channels.zalo.accounts.default.botToken: "...".
3. Gateway를 다시 시작합니다(또는 설정을 완료합니다).
4. DM 액세스는 기본적으로 페어링 방식입니다. 첫 연락 시 페어링 코드를 승인하세요.

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

​

개요

• Gateway가 소유하는 Zalo Bot API 채널입니다.
• 결정적 라우팅: 응답은 Zalo로 다시 전달되며, 모델은 채널을 선택하지 않습니다.
• DM은 에이전트의 기본 세션을 공유합니다.
• 아래 기능 섹션은 현재 Marketplace 봇 지원 상태를 보여 줍니다.

​

설정(빠른 경로)

​

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

1. https://bot.zaloplatforms.com으로 이동해 로그인합니다.
2. 새 봇을 만들고 설정을 구성합니다.
3. 전체 봇 토큰(일반적으로 numeric_id:secret)을 복사합니다. Marketplace 봇의 경우, 생성 후 봇의 환영 메시지에 사용 가능한 런타임 토큰이 표시될 수 있습니다.

​

2) 토큰 구성(env 또는 config)

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

3. Gateway를 다시 시작합니다. 토큰이 확인되면(env 또는 config) Zalo가 시작됩니다.
4. DM 액세스는 기본적으로 페어링입니다. 봇이 처음 연락을 받을 때 코드를 승인하세요.

​

작동 방식(동작)

• 인바운드 메시지는 미디어 자리 표시자와 함께 공유 채널 엔벨로프로 정규화됩니다.
• 응답은 항상 동일한 Zalo 채팅으로 다시 라우팅됩니다.
• 기본값은 long-polling이며, Webhook 모드는 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.
• channels.zalo.groupAllowFrom은 그룹에서 봇을 트리거할 수 있는 발신자 ID를 제한합니다.
• groupAllowFrom이 설정되지 않은 경우, Zalo는 발신자 검사에 allowFrom을 대체 사용합니다.
• 런타임 참고: channels.zalo가 완전히 없으면 런타임은 안전을 위해 여전히 groupPolicy="allowlist"로 대체됩니다.

• groupPolicy: "disabled" — 모든 그룹 메시지를 차단합니다.
• groupPolicy: "open" — 모든 그룹 멤버를 허용합니다(멘션 게이트 적용).
• groupPolicy: "allowlist" — 실패 시 닫힘 기본값이며, 허용된 발신자만 수락됩니다.

​

Long-polling 대 Webhook

• 기본값: long-polling(공개 URL 필요 없음).
• Webhook 모드: channels.zalo.webhookUrl 및 channels.zalo.webhookSecret을 설정합니다.
  • Webhook secret은 8~256자여야 합니다.
  • Webhook URL은 HTTPS를 사용해야 합니다.
  • Zalo는 검증을 위해 X-Bot-Api-Secret-Token 헤더와 함께 이벤트를 전송합니다.
  • Gateway HTTP는 channels.zalo.webhookPath에서 Webhook 요청을 처리합니다(기본값은 Webhook URL 경로).
  • 요청은 Content-Type: application/json(또는 +json 미디어 유형)을 사용해야 합니다.
  • 중복 이벤트(event_name + message_id)는 짧은 재생 방지 기간 동안 무시됩니다.
  • 버스트 트래픽은 경로/소스별로 속도 제한되며 HTTP 429를 반환할 수 있습니다.

​

지원되는 메시지 유형

• 텍스트 메시지: 2000자 분할과 함께 완전 지원됩니다.
• 텍스트의 일반 URL: 일반 텍스트 입력처럼 동작합니다.
• 링크 미리보기 / 리치 링크 카드: 기능의 Marketplace 봇 상태를 참조하세요. 안정적으로 응답을 트리거하지 않았습니다.
• 이미지 메시지: 기능의 Marketplace 봇 상태를 참조하세요. 인바운드 이미지 처리는 신뢰할 수 없었습니다(최종 응답 없이 입력 표시기만 표시).
• 스티커: 기능의 Marketplace 봇 상태를 참조하세요.
• 음성 메모 / 오디오 파일 / 비디오 / 일반 파일 첨부: 기능의 Marketplace 봇 상태를 참조하세요.
• 지원되지 않는 유형: 로그에 기록됩니다(예: 보호된 사용자의 메시지).

​

기능

​

전달 대상(CLI/cron)

• 채팅 ID를 대상으로 사용하세요.
• 예: openclaw message send --channel zalo --target 123456789 --message "hi".

​

문제 해결

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

• Webhook URL이 HTTPS를 사용하는지 확인
• secret 토큰이 8~256자인지 확인
• Gateway HTTP 엔드포인트가 구성된 경로에서 접근 가능한지 확인
• getUpdates 폴링이 실행 중이 아닌지 확인(둘은 서로 배타적)

​

구성 참조(Zalo)

• 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). config에 존재합니다. 현재 Marketplace 봇 동작은 기능 및 액세스 제어(그룹)를 참조하세요.
• channels.zalo.groupAllowFrom: 그룹 발신자 허용 목록(사용자 ID). 설정되지 않은 경우 allowFrom으로 대체됩니다.
• channels.zalo.mediaMaxMb: 인바운드/아웃바운드 미디어 제한(MB, 기본값 5).
• channels.zalo.webhookUrl: Webhook 모드를 활성화합니다(HTTPS 필요).
• channels.zalo.webhookSecret: Webhook secret(8~256자).
• channels.zalo.webhookPath: Gateway HTTP 서버의 Webhook 경로입니다.
• 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: 계정별 그룹 정책입니다. config에 존재합니다. 현재 Marketplace 봇 동작은 기능 및 액세스 제어(그룹)를 참조하세요.
• channels.zalo.accounts.<id>.groupAllowFrom: 계정별 그룹 발신자 허용 목록입니다.
• channels.zalo.accounts.<id>.webhookUrl: 계정별 Webhook URL입니다.
• channels.zalo.accounts.<id>.webhookSecret: 계정별 Webhook secret입니다.
• channels.zalo.accounts.<id>.webhookPath: 계정별 Webhook 경로입니다.
• channels.zalo.accounts.<id>.proxy: 계정별 프록시 URL입니다.

​

관련 항목

• Channels Overview — 지원되는 모든 채널
• Pairing — DM 인증 및 페어링 흐름
• Groups — 그룹 채팅 동작 및 멘션 게이팅
• Channel Routing — 메시지의 세션 라우팅
• Security — 액세스 모델 및 강화