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 で Bot にメッセージを送信して接続を確認します。
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 を通じて応答が送信されます。各会話はユーザーごとに個別に追跡されるため、複数のユーザーが同じ Bot と独立してやり取りできます。
ロングポーリングはネットワーク設定なしですぐに使用できます。開発環境やパブリック 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 は 4 つのポリシーをサポートしています：
• pairing（デフォルト）— 新規ユーザーが初めてメッセージを送信するとペアリングコードを受け取ります。'openclaw pairing approve zalo <code>' で承認または拒否できます。コードは 1 時間後に有効期限が切れます。
• allowlist — allowFrom リストに記載された数値ユーザー ID のみが Bot とやり取りできます。それ以外はサイレントに無視されます。
• open — Bot にメッセージを送信した誰もが応答を受け取ります。注意して使用してください。
• disabled — DM 処理を完全に無効にします。
openclaw.json
{
"channels": {
"zalo": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "987654321"]
}
}
}'open' ポリシーは誰でも Bot とやり取りできるようにします。Bot が 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 インスタンスで異なる目的の Bot（例：カスタマーサポート Bot と社内チーム Bot）を運用したい場合に便利です。
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" | Bot に DM できるユーザーを制御。オプション：pairing、allowlist、open、disabled |
| allowFrom | string[] | [] | Bot とやり取りを許可する数値 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"
Bot に DM できるユーザーを制御。オプション：pairing、allowlist、open、disabled
allowFrom
Type: string[]Default: []
Bot とやり取りを許可する数値 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 がメッセージを受信しない
Bot Token が無効、期限切れ、または Gateway が実行されていない可能性があります。Webhook モードでは、HTTPS エンドポイントにアクセスできない可能性があります。
bot.zaloplatforms.com で Bot Token を確認してください。Gateway ログで接続エラーを確認します。Webhook を使用している場合は、エンドポイントが HTTPS でパブリックにアクセス可能であり、webhookSecret が一致していることを確認してください。
メッセージが遅延するか、まとめて到着する
ロングポーリングは Webhook モードと比較して固有のレイテンシがあります。ネットワークの不安定さもメッセージのバッチ処理を引き起こす可能性があります。
より低いレイテンシのために Webhook モードに切り替えてください。サーバーのインターネット接続が安定していることを確認します。Gateway ログでポーリング間隔情報を確認してください。
新規ユーザーにペアリングコードが送信されない
dmPolicy が 'pairing' に設定されていないか、Bot が 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 がサーバーのルーティング設定と一致していることを確認してください。