OpenClaw Zalo 채널
메시징
보통
Zalo Bot Platform을 사용하여 OpenClaw를 Zalo에 연결합니다. 이 통합을 통해 AI 어시스턴트가 베트남에서 가장 인기 있는 메시징 앱에서 메시지를 주고받을 수 있습니다. Bot Token을 설정하고 DM 정책을 구성하면 롱 폴링과 Webhook 두 가지 전달 모드로 대화를 시작할 수 있습니다.
기본 정보
난이도보통
카테고리메시징
지원 기능 수1 / 6
Zalo 지원 기능
텍스트 메시지
지원
미디어 및 파일
미지원
리액션
미지원
스레드
미지원
음성 메시지
미지원
그룹 채팅
미지원
Zalo 사전 요구사항
- Zalo Bot Platform(bot.zaloplatforms.com)에 접근할 수 있는 Zalo 계정
- Zalo Bot Platform 대시보드에서 발급받은 Bot Token
- OpenClaw Gateway가 실행 중이고 설정 완료
- Webhook 모드 사용 시: 공개적으로 접근 가능한 HTTPS 엔드포인트
Zalo 빠른 설정
1
Zalo Bot 생성 및 Token 발급
bot.zaloplatforms.com에 접속하여 Zalo 계정으로 로그인하고 새 Bot을 생성합니다. 대시보드에서 Bot Token(형식: 12345689:abc-xyz)을 복사합니다.
2
Zalo 채널 설정 추가
Zalo 채널 설정을 ~/.openclaw/openclaw.json에 추가합니다. botToken, dmPolicy(pairing, allowlist, open 또는 disabled)를 설정하고, 선택적으로 Webhook 설정을 구성합니다.
3
Gateway 시작 및 테스트
'openclaw start'로 Gateway를 시작합니다. 기본적으로 롱 폴링 모드로 연결됩니다. Zalo에서 봇에게 메시지를 보내 연결이 정상적인지 확인합니다.
Zalo 구성 예시
config.json
{
"channels": {
"zalo": {
"enabled": true,
"botToken": "12345689:abc-xyz",
"dmPolicy": "pairing"
}
}
}Zalo 상세 문서
아키텍처 개요
OpenClaw는 Zalo Bot Platform API를 통해 메시지를 주고받습니다. Gateway는 롱 폴링(기본값) 또는 Webhook 모드로 Zalo 서버와 통신합니다.
롱 폴링 모드에서는 Gateway가 주기적으로 새 메시지를 확인합니다. 공용 URL이나 HTTPS 인증서가 필요하지 않습니다. Webhook 모드에서는 Zalo가 이벤트를 서버로 직접 푸시하므로 공개적으로 접근 가능한 HTTPS 엔드포인트가 필요합니다.
Zalo 사용자의 메시지는 Gateway에서 수신되어 AI로 처리된 후 Zalo Bot API를 통해 응답이 전송됩니다. 각 대화는 사용자별로 독립적으로 추적되므로 여러 사용자가 같은 봇과 독립적으로 대화할 수 있습니다.
롱 폴링은 네트워크 설정 없이 바로 사용할 수 있습니다. 개발 환경이나 공용 URL이 없는 경우에 적합합니다.
Webhook 모드는 지연 시간이 더 짧으며 안정적인 HTTPS 엔드포인트가 있는 프로덕션 환경에 권장됩니다.
Zalo Bot 생성
OpenClaw를 Zalo에 연결하려면 Zalo Bot Platform에서 Bot Token을 발급받아야 합니다:
1. bot.zaloplatforms.com에 접속하여 Zalo 계정으로 로그인합니다.
2. 'Bot 생성'을 클릭하고 필수 정보(이름, 설명, 카테고리)를 입력합니다.
3. 생성 후 Bot 설정 페이지로 이동하여 Bot Token을 복사합니다.
Bot Token은 연결에 필요한 유일한 자격 증명입니다. 설정 파일, 환경 변수(ZALO_BOT_TOKEN) 또는 tokenFile 옵션을 사용하여 파일에서 읽을 수 있습니다.
openclaw.json
{
"channels": {
"zalo": {
"enabled": true,
"botToken": "12345689:abc-xyz"
}
}
}Bot Token은 환경 변수(ZALO_BOT_TOKEN) 또는 별도 파일(tokenFile)에 저장하여 버전 관리에 시크릿을 커밋하지 않도록 하세요.
DM 정책
DM(다이렉트 메시지) 정책은 AI 어시스턴트와 대화할 수 있는 사용자를 제어합니다. OpenClaw는 네 가지 정책을 지원합니다:
• pairing(기본값) — 새 사용자가 처음 메시지를 보내면 페어링 코드를 받습니다. 'openclaw pairing approve zalo <code>'로 승인 또는 거부할 수 있습니다. 코드는 1시간 후 만료됩니다.
• allowlist — allowFrom 목록에 있는 숫자 사용자 ID만 봇과 대화할 수 있습니다. 나머지는 조용히 무시됩니다.
• open — 봇에게 메시지를 보내는 모든 사람이 응답을 받습니다. 주의하여 사용하세요.
• disabled — DM 처리를 완전히 비활성화합니다.
openclaw.json
{
"channels": {
"zalo": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "987654321"]
}
}
}'open' 정책은 누구나 봇과 대화할 수 있게 합니다. 봇이 Zalo에서 공개적으로 검색 가능한 경우 상당한 AI 할당량을 소모할 수 있습니다.
Webhook 설정
기본적으로 OpenClaw는 롱 폴링으로 메시지를 수신합니다. Webhook 모드로 전환하려면 설정에서 webhookUrl을 설정합니다. 공개적으로 접근 가능한 HTTPS 엔드포인트가 필요합니다.
Webhook 모드가 활성화되면 롱 폴링은 자동으로 비활성화됩니다. Zalo가 메시지 이벤트를 Webhook URL로 직접 전송합니다. 검증은 시크릿 토큰으로 수행되며, Zalo는 각 요청의 X-Bot-Api-Secret-Token HTTP 헤더에 토큰을 포함합니다.
webhookPath 옵션을 사용하면 Gateway HTTP 서버에서 Zalo 이벤트를 수신하는 경로를 사용자 정의할 수 있습니다.
openclaw.json
{
"channels": {
"zalo": {
"botToken": "12345689:abc-xyz",
"webhookUrl": "https://your-server.com/zalo/webhook",
"webhookSecret": "your-secret-string-8-to-256-chars",
"webhookPath": "/zalo/webhook"
}
}
}webhookSecret은 8~256자 사이여야 합니다.
Webhook과 롱 폴링은 상호 배타적입니다. webhookUrl을 설정하면 폴링이 자동으로 비활성화됩니다.
메시지 처리
OpenClaw는 Zalo에서 텍스트 메시지와 이미지 메시지를 지원합니다. 텍스트 메시지는 Zalo의 제한에 따라 2,000자 단위로 자동 분할됩니다.
사용자가 보낸 이미지는 다운로드되어 처리됩니다. 발신 이미지는 Zalo sendPhoto API를 통해 전송됩니다. 사용자의 스티커 메시지는 기록되지만 AI에서 처리되지 않습니다.
mediaMaxMb 설정은 수신 미디어 파일의 최대 크기를 제어합니다(기본값: 5 MB).
긴 AI 응답은 2,000자 경계에서 자동으로 여러 메시지로 분할됩니다.
문자 수 제한으로 인해 Zalo에서는 스트리밍 응답이 지원되지 않습니다.
다중 계정 설정
OpenClaw는 여러 Zalo Bot 계정의 동시 실행을 지원합니다. 각 계정에는 고유한 Bot Token, DM 정책 및 선택적 Webhook 설정이 있습니다.
같은 Gateway 인스턴스에서 다른 용도의 봇(예: 고객 지원 봇과 내부 팀 봇)을 운영하려는 경우 유용합니다.
openclaw.json
{
"channels": {
"zalo": {
"accounts": {
"support-bot": {
"botToken": "token-for-support-bot",
"dmPolicy": "open"
},
"team-bot": {
"botToken": "token-for-team-bot",
"dmPolicy": "allowlist",
"allowFrom": ["111222333"]
}
}
}
}
}아웃바운드 메시징
CLI를 사용하여 특정 Zalo 사용자에게 메시지를 보낼 수 있습니다. 메시지는 원래 Zalo 채팅으로 결정적으로 라우팅되므로 응답은 항상 올바른 사용자에게 전송됩니다.
특정 사용자에게 수동 메시지를 보내려면 target 플래그에 숫자 Zalo 사용자 ID를 지정합니다.
terminal
openclaw message send --channel zalo --target 123456789프록시 설정
서버가 아웃바운드 연결에 프록시를 필요로 하는 경우 Zalo 채널용 프록시를 설정할 수 있습니다. 프록시 URL은 Zalo 서버로의 모든 API 요청에 사용됩니다.
기업 환경이나 Zalo API 엔드포인트에 대한 직접 접근이 제한된 지역에서 유용합니다.
openclaw.json
{
"channels": {
"zalo": {
"proxy": "http://proxy.example.com:8080"
}
}
}Zalo 구성 참조
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | Zalo 채널 활성화 또는 비활성화 |
| botToken | string | "" | Zalo Bot Platform(bot.zaloplatforms.com)에서 발급받은 Bot Token |
| tokenFile | string | "" | 인라인 설정 대신 파일 경로에서 Bot Token을 읽기 |
| dmPolicy | string | "pairing" | 봇에게 DM할 수 있는 사용자를 제어. 옵션: pairing, allowlist, open, disabled |
| allowFrom | string[] | [] | 봇과 대화를 허용할 숫자 Zalo 사용자 ID 목록(dmPolicy가 allowlist인 경우) |
| mediaMaxMb | number | 5 | 수신 미디어 파일의 최대 크기(MB) |
| webhookUrl | string | "" | Webhook 모드용 HTTPS URL. 설정 시 롱 폴링이 비활성화됨 |
| webhookSecret | string | "" | X-Bot-Api-Secret-Token 헤더를 통한 Webhook 검증용 시크릿 문자열(8~256자) |
| webhookPath | string | "" | Gateway HTTP 서버의 사용자 정의 Webhook 경로 |
| proxy | string | "" | Zalo로의 아웃바운드 API 요청용 프록시 URL |
| accounts.<id>.botToken | string | "" | 다중 계정 모드에서 특정 계정의 Bot Token |
| accounts.<id>.dmPolicy | string | "pairing" | 특정 계정의 DM 정책 재정의 |
| accounts.<id>.webhookUrl | string | "" | 특정 계정의 Webhook URL 재정의 |
enabled
Type: booleanDefault: false
Zalo 채널 활성화 또는 비활성화
botToken
Type: stringDefault: ""
Zalo Bot Platform(bot.zaloplatforms.com)에서 발급받은 Bot Token
tokenFile
Type: stringDefault: ""
인라인 설정 대신 파일 경로에서 Bot Token을 읽기
dmPolicy
Type: stringDefault: "pairing"
봇에게 DM할 수 있는 사용자를 제어. 옵션: pairing, allowlist, open, disabled
allowFrom
Type: string[]Default: []
봇과 대화를 허용할 숫자 Zalo 사용자 ID 목록(dmPolicy가 allowlist인 경우)
mediaMaxMb
Type: numberDefault: 5
수신 미디어 파일의 최대 크기(MB)
webhookUrl
Type: stringDefault: ""
Webhook 모드용 HTTPS URL. 설정 시 롱 폴링이 비활성화됨
webhookSecret
Type: stringDefault: ""
X-Bot-Api-Secret-Token 헤더를 통한 Webhook 검증용 시크릿 문자열(8~256자)
webhookPath
Type: stringDefault: ""
Gateway HTTP 서버의 사용자 정의 Webhook 경로
proxy
Type: stringDefault: ""
Zalo로의 아웃바운드 API 요청용 프록시 URL
accounts.<id>.botToken
Type: stringDefault: ""
다중 계정 모드에서 특정 계정의 Bot Token
accounts.<id>.dmPolicy
Type: stringDefault: "pairing"
특정 계정의 DM 정책 재정의
accounts.<id>.webhookUrl
Type: stringDefault: ""
특정 계정의 Webhook URL 재정의
Zalo 자주 묻는 질문
Zalo 문제 해결
봇이 메시지를 수신하지 않음
Bot Token이 유효하지 않거나 만료되었거나 Gateway가 실행되지 않고 있을 수 있습니다. Webhook 모드에서는 HTTPS 엔드포인트에 접근할 수 없을 수 있습니다.
bot.zaloplatforms.com에서 Bot Token을 확인하세요. Gateway 로그에서 연결 오류를 확인합니다. Webhook을 사용하는 경우 엔드포인트가 HTTPS로 공개적으로 접근 가능하고 webhookSecret이 일치하는지 확인하세요.
메시지가 지연되거나 한꺼번에 도착함
롱 폴링은 Webhook 모드에 비해 고유한 지연 시간이 있습니다. 네트워크 불안정으로 메시지가 일괄 처리될 수도 있습니다.
더 낮은 지연 시간을 위해 Webhook 모드로 전환하세요. 서버의 인터넷 연결이 안정적인지 확인합니다. Gateway 로그에서 폴링 간격 정보를 확인하세요.
새 사용자에게 페어링 코드가 전송되지 않음
dmPolicy가 'pairing'으로 설정되지 않았거나 봇이 Zalo에 제대로 연결되지 않았을 수 있습니다.
설정에서 dmPolicy가 'pairing'으로 설정되어 있는지 확인하세요. Gateway 로그에서 Zalo 채널이 온라인인지 확인합니다. 'openclaw pairing list zalo'를 실행하여 대기 중인 페어링 요청을 확인하세요.
이미지 메시지 전송 실패
이미지 파일이 mediaMaxMb 제한을 초과했거나 Zalo API가 일시적으로 사용할 수 없을 수 있습니다.
이미지 파일 크기가 mediaMaxMb 제한 내(기본값: 5 MB)인지 확인하세요. Gateway 로그에서 구체적인 API 오류 메시지를 확인합니다. 먼저 텍스트 메시지를 보내 연결이 정상인지 확인하세요.
Webhook 검증 실패
설정의 webhookSecret이 Zalo가 기대하는 것과 일치하지 않거나 엔드포인트가 올바른 응답을 반환하지 않고 있을 수 있습니다.
webhookSecret이 8~256자인지 확인하세요. HTTPS 인증서가 유효한지 확인합니다(자체 서명 인증서는 허용되지 않음). webhookPath가 서버의 라우팅 설정과 일치하는지 확인하세요.