【最新版】ZaloでOpenClawを使う方法（Bot APIでDM連携）

2026年3月18日

Zalo

Zalo（Bot API）

ステータス：experimental。DM（1:1）がサポートされています。下の「Capabilities」セクションは、現在の Marketplace bot の挙動を反映しています。

プラグインが必要

Zalo はプラグインとして提供されており、コアインストールには同梱されていません。

CLI でインストール：

openclaw plugins install @openclaw/zalo

もしくはセットアップ中に Zalo を選択し、インストールプロンプトを承認します。

詳細： Plugins

クイックセットアップ（初心者向け）

1) Zalo プラグインをインストール

source checkout から：

openclaw plugins install ./extensions/zalo

npm（公開されている場合）：

openclaw plugins install @openclaw/zalo

またはセットアップで Zalo を選び、インストールプロンプトを承認します。

2) トークンを設定

Env：

ZALO_BOT_TOKEN=...

または config：

channels.zalo.accounts.default.botToken: "..."

3) Gateway を再起動（またはセットアップ完了）

DM アクセスはデフォルトで pairing です。最初の接触時にペアリングコードを承認してください。

最小 config

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

これは何？（What it is）

Zalo はベトナム向けのメッセージングアプリです。Bot API により、Gateway が 1:1 会話のボットを動かせます。

サポートや通知など、返信を確実に Zalo に返したい（deterministic routing）用途に向いています。

このページは現在の Zalo Bot Creator / Marketplace bots に対する OpenClaw の挙動を反映しています。Zalo Official Account（OA）bots は別プロダクトで、挙動が異なる可能性があります。

Gateway が所有する Zalo Bot API チャネル
決定的ルーティング：返信は常に Zalo に戻り、モデルがチャネルを選びません
DM はエージェントの main セッションを共有します
下の Capabilities セクションは現在の Marketplace bot の対応状況を示します

セットアップ（fast path）

1) bot token を作成（Zalo Bot Platform）

https://bot.zaloplatforms.comにアクセスしてサインインします。

新しい bot を作成し、設定を行います。

完全な bot token（通常は numeric_id:secret）をコピーします。 Marketplace bot の場合、作成後に bot の welcome message に runtime で使える token が表示されることがあります。

2) token を設定（env または config）

例：

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

将来的に、グループが使える Zalo の別ボット面（product surface）へ移行した場合は、明示的に groupPolicy や groupAllowFrom などのグループ用設定を追加できます。現在の Marketplace bot の挙動は Capabilities を参照してください。

Env オプション：ZALO_BOT_TOKEN=...（デフォルトアカウントのみ）

マルチアカウント：channels.zalo.accounts を使って、アカウントごとの token と任意の name を設定します。

Gateway を再起動します。Zalo は token（env または config）が解決できた時点で起動します。

DM アクセスはデフォルトで pairing です。ボットへ最初に連絡したときに表示されるコードを承認してください。

How it works（挙動）

受信メッセージは、メディアのプレースホルダーを含む共通のチャネルエンベロープに正規化されます。
返信は常に同じ Zalo チャットへルーティングされます。
デフォルトは long-polling。channels.zalo.webhookUrl による webhook モードも利用できます。

制限（Limits）

送信テキストは 2000 文字で分割されます（Zalo API 制限）。
メディアのダウンロード/アップロードは channels.zalo.mediaMaxMb（デフォルト 5）で上限があります。
ストリーミングはデフォルトでブロックされます（2000文字上限のためストリーミングの旨味が薄い）。

アクセス制御（DM）

DM access

デフォルト：channels.zalo.dmPolicy = "pairing"。未知の送信者はペアリングコードを受け取り、承認されるまでメッセージは無視されます（コードは 1 時間で期限切れ）。

承認：

openclaw pairing list zalo
openclaw pairing approve zalo <CODE>

pairing はデフォルトのトークン交換フローです。詳細： Pairing

channels.zalo.allowFrom は数値の user ID を受け付けます（ユーザー名のルックアップは利用できません）。

アクセス制御（グループ）

Zalo Bot Creator / Marketplace bots では、実運用上グループサポートが利用できませんでした（ボット自体をグループに追加できない）。

そのため、以下のグループ関連 config キーは schema には存在しますが、Marketplace bot では使えませんでした：

channels.zalo.groupPolicy：グループ受信を制御（open | allowlist | disabled）
channels.zalo.groupAllowFrom：グループ内でボットをトリガーできる送信者 ID を制限
groupAllowFrom が未設定の場合、送信者チェックは allowFrom にフォールバックします
Runtime note：channels.zalo が完全に欠けている場合でも、安全のため runtime は groupPolicy="allowlist" にフォールバックします

（もしあなたが別の Zalo ボット面を使っていて、グループが動作することを確認している場合）Marketplace bot のフローに一致すると仮定せず、別途ドキュメント化してください。

groupPolicy の値（グループアクセスが利用できる場合）

groupPolicy: "disabled" — すべてのグループメッセージをブロック
groupPolicy: "open" — 任意のグループメンバーを許可（メンションゲートあり）
groupPolicy: "allowlist" — fail-closed デフォルト。許可された送信者のみ受理

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 URL の path）で webhook リクエストを受けます
リクエストは Content-Type: application/json（または +json のメディアタイプ）である必要があります
重複イベント（event_name + message_id）は短いリプレイウィンドウ内で無視されます
バーストトラフィックは path/source 単位で rate-limit され、HTTP 429 を返すことがあります

注： Zalo API ドキュメント上、getUpdates（polling）と webhook は排他的（mutually exclusive）です。

対応メッセージタイプ（Supported message types）

ざっくりの対応状況は Capabilities を参照してください。以下は挙動に補足が必要な箇所のメモです。

テキストメッセージ： 2000文字の chunking 付きでフルサポート
テキスト内の素の URL： 通常のテキスト入力として扱われます
リンクプレビュー / リッチリンクカード： Capabilities の Marketplace bot 状態を参照（返信が不安定でした）
画像メッセージ： Capabilities の Marketplace bot 状態を参照（受信画像の扱いが不安定で、typing indicator のみで最終返信が来ない挙動がありました）
ステッカー： Capabilities の Marketplace bot 状態を参照
ボイスノート / 音声ファイル / 動画 / 一般ファイル添付： Capabilities の Marketplace bot 状態を参照
未対応タイプ： ログに記録されます（例：保護ユーザーからのメッセージ）

Capabilities

これは、現在の Zalo Bot Creator / Marketplace bot の OpenClaw における挙動サマリーです。

| Feature | Status |
| --------------------------- | --------------------------------------- |
| Direct messages | ✅ Supported |
| Groups | ❌ Not available for Marketplace bots |
| Media (inbound images) | ⚠️ Limited / verify in your environment |
| Media (outbound images) | ⚠️ Not re-tested for Marketplace bots |
| Plain URLs in text | ✅ Supported |
| Link previews | ⚠️ Unreliable for Marketplace bots |
| Reactions | ❌ Not supported |
| Stickers | ⚠️ No agent reply for Marketplace bots |
| Voice notes / audio / video | ⚠️ No agent reply for Marketplace bots |
| File attachments | ⚠️ No agent reply for Marketplace bots |
| Threads | ❌ Not supported |
| Polls | ❌ Not supported |
| Native commands | ❌ Not supported |
| Streaming | ⚠️ Blocked (2000 char limit) |

配信ターゲット（CLI/cron）

target には chat id を使います。

例：

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

トラブルシューティング

Bot が反応しない

token が有効か確認：openclaw channels status --probe
送信者が承認されているか確認（pairing または allowFrom）
Gateway ログ確認：openclaw logs --follow

Webhook がイベントを受信しない

Webhook URL が HTTPS であること
secret token が 8〜256 文字であること
設定した path で Gateway の HTTP endpoint に到達できること
getUpdates polling が動作していないこと（排他）

設定リファレンス（Zalo）

フル設定： Configuration

フラットなトップレベルキー（channels.zalo.botToken、channels.zalo.dmPolicy など）は、レガシーの single-account shorthand です。新規設定では channels.zalo.accounts.<id>.* を推奨します。ただし schema に存在するため、ここでは両形式を記載します。

Provider options

channels.zalo.enabled：チャネル起動の有効/無効
channels.zalo.botToken：Zalo Bot Platform の bot token
channels.zalo.tokenFile：通常ファイルから token を読み込み（symlink は拒否）
channels.zalo.dmPolicy：pairing | allowlist | open | disabled（デフォルト：pairing）
channels.zalo.allowFrom：DM allowlist（user IDs）。open には "*" が必要。ウィザードは数値 ID を促します
channels.zalo.groupPolicy：open | allowlist | disabled（デフォルト：allowlist）。Marketplace bot の現状は Capabilities と「アクセス制御（グループ）」を参照
channels.zalo.groupAllowFrom：グループ送信者 allowlist（user IDs）。未設定時は allowFrom にフォールバック
channels.zalo.mediaMaxMb：送受信メディア上限（MB、デフォルト 5）
channels.zalo.webhookUrl：webhook mode を有効化（HTTPS 必須）
channels.zalo.webhookSecret：webhook secret（8〜256文字）
channels.zalo.webhookPath：Gateway HTTP サーバー上の webhook path
channels.zalo.proxy：API リクエスト用 proxy URL

Multi-account options

channels.zalo.accounts.<id>.botToken：アカウントごとの token
channels.zalo.accounts.<id>.tokenFile：アカウントごとの token file（symlink は拒否）
channels.zalo.accounts.<id>.name：表示名
channels.zalo.accounts.<id>.enabled：アカウントの有効/無効
channels.zalo.accounts.<id>.dmPolicy：アカウント単位の DM policy
channels.zalo.accounts.<id>.allowFrom：アカウント単位の allowlist
channels.zalo.accounts.<id>.groupPolicy：アカウント単位の group policy（Marketplace bot の現状は Capabilities を参照）
channels.zalo.accounts.<id>.groupAllowFrom：アカウント単位の group sender allowlist
channels.zalo.accounts.<id>.webhookUrl：アカウント単位の webhook URL
channels.zalo.accounts.<id>.webhookSecret：アカウント単位の webhook secret
channels.zalo.accounts.<id>.webhookPath：アカウント単位の webhook path
channels.zalo.accounts.<id>.proxy：アカウント単位の proxy URL

参考

https://docs.openclaw.ai/channels/zalo.md

#ガイド

BizClaw 導入支援

OpenClaw の構築を
まるごと代行します

Mac mini のセットアップから Slack・iMessage 連携まで、届いた日から使える状態でお届けします。

サービスを見る

AIエージェントのメモリスタックとは？2026年に重要度が上がる理由をやさしく解説

2026年4月8日

OpenClaw vs Hermes vs Claude、創業者はどれを選ぶべき？2026年版の実務比較

2026年4月8日

X公式MCPサーバーとは？AIエージェント運用で何が変わるのかを実務目線で解説

2026年4月8日

【最新版】ZaloでOpenClawを使う方法（Bot APIでDM連携）

Zalo

Zalo（Bot API）

プラグインが必要

クイックセットアップ（初心者向け）

1) Zalo プラグインをインストール

2) トークンを設定

3) Gateway を再起動（またはセットアップ完了）

最小 config

これは何？（What it is）

セットアップ（fast path）

1) bot token を作成（Zalo Bot Platform）

2) token を設定（env または config）

How it works（挙動）

制限（Limits）

アクセス制御（DM）

DM access

アクセス制御（グループ）

groupPolicy の値（グループアクセスが利用できる場合）

long-polling と webhook

対応メッセージタイプ（Supported message types）

Capabilities

配信ターゲット（CLI/cron）

トラブルシューティング

Bot が反応しない

Webhook がイベントを受信しない

設定リファレンス（Zalo）

Provider options

Multi-account options

参考

OpenClaw の構築をまるごと代行します

関連記事

AIエージェントのメモリスタックとは？2026年に重要度が上がる理由をやさしく解説

OpenClaw vs Hermes vs Claude、創業者はどれを選ぶべき？2026年版の実務比較

X公式MCPサーバーとは？AIエージェント運用で何が変わるのかを実務目線で解説

OpenClaw の構築を
まるごと代行します