Zalo Bot API を Gateway で動かす

新しいメッセージングプラットフォームに対応するのは、いつも大変な作業です。特に特定の地域で普及しているアプリを導入しようとすると、API の仕様を一つずつ確認して、一から実装を積み上げるのは時間がかかります。

もっとシンプルに、既存の Gateway に統合して Bot を動かしたいですよね。Zalo プラグインを使えば、数分でセットアップが完了し、すぐにメッセージのやり取りを開始できます。

必要なもの

セットアップを始める前に、以下の準備ができているか確認してください。

• Zalo Bot Platform のアカウント
• Zalo Bot Token（12345689:abc-xyz の形式）
• openclaw CLI がインストールされた環境

クイックスタート

最短で Zalo Bot を動かすためのステップです。

1. プラグインのインストール

Zalo はプラグインとして提供されているため、まずは以下のコマンドでインストールします。

openclaw plugins install @openclaw/zalo

2. トークンの設定

環境変数、または設定ファイルで Bot Token を設定します。

設定ファイル (config.json5) の例:

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

または、環境変数 ZALO_BOT_TOKEN=... を使用することも可能です。

3. Gateway の起動とペアリング

Gateway を起動（または再起動）してください。

Zalo チャンネルはデフォルトで pairing ポリシーが適用されます。初めて Bot にメッセージを送信すると、ペアリングコードが表示されます。以下の CLI コマンドで承認してください。

# ペアリングコードの確認
openclaw pairing list zalo

# 承認
openclaw pairing approve zalo <CODE>

これで、Bot との 1:1 チャットが可能になります。

知っておくべきポイント

• メッセージ制限: Zalo API の制限により、送信テキストは 2000 文字ごとに分割されます。この制限があるため、Streaming はデフォルトで無効化されています。
• グループチャット: 現在は Direct Message のみをサポートしています。Zalo 公式ドキュメントによると、グループ機能は「近日公開予定」です。
• Webhook と Long-polling: デフォルトでは Long-polling で動作するため、公開 URL は不要です。Webhook を使用したい場合は、channels.zalo.webhookUrl と channels.zalo.webhookSecret を設定してください。

トラブルシューティング

Bot が反応しない場合:

• トークンが有効か確認してください: openclaw channels status --probe
• 送信者が承認されているか（ペアリング済みか）確認してください。
• Gateway のログを確認してください: openclaw logs --follow

Webhook がイベントを受信できない場合:

• Webhook URL に HTTPS を使用しているか確認してください。
• Secret Token が 8〜256 文字であることを確認してください。
• Long-polling（getUpdates）が同時に動いていないか確認してください（これらは排他的です）。

セットアップで困ったことがあれば、こちらのツールも活用してください。 AI Setup Assistant

次のステップ

• Plugins: プラグインの管理方法について
• Pairing: ペアリングの仕組みの詳細
• Configuration: 詳細な設定リファレンス