Zalo（Bot API）

ステータス：実験的。ダイレクトメッセージのみ；グループは Zalo ドキュメントに従って近日公開予定。

プラグインが必要

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

  • CLI 経由でインストール：openclaw plugins install @openclaw/zalo
  • またはオンボーディング中に Zalo を選択し、インストールプロンプトを確認します
  • 詳細：Plugins

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

  1. Zalo プラグインをインストール：
    • ソースチェックアウトから：openclaw plugins install ./extensions/zalo
    • npm から（公開されている場合）：openclaw plugins install @openclaw/zalo
    • またはオンボーディングで Zalo を選択し、インストールプロンプトを確認します
  2. トークンを設定：
    • 環境変数：ZALO_BOT_TOKEN=...
    • または設定：channels.zalo.botToken: "..."。
  3. ゲートウェイを再起動します（またはオンボーディングを完了）。
  4. DM アクセスはデフォルトでペアリングです；最初の連絡時にペアリングコードを承認します。

最小構成：

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

これは何か

Zalo はベトナム向けメッセージングアプリです；その Bot API により、Gateway は 1:1 会話用のボットを実行できます。 サポートや通知で、Zalo への確定的なルーティングを必要とする場合に適しています。

  • Gateway が所有する Zalo Bot API チャンネル。
  • 確定的なルーティング：返信は Zalo に戻ります；モデルはチャンネルを選択しません。
  • DM はエージェントのメインセッションを共有します。
  • グループはまだサポートされていません（Zalo ドキュメントには「近日公開予定」と記載）。

セットアップ（高速パス）

1) ボットトークンを作成（Zalo Bot Platform）

  1. https://bot.zaloplatforms.com にアクセスしてサインインします。
  2. 新しいボットを作成し、その設定を構成します。
  3. ボットトークンをコピーします（形式：12345689:abc-xyz）。

2) トークンを構成（環境変数または設定）

例：

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

環境変数オプション：ZALO_BOT_TOKEN=...（デフォルトアカウントのみで機能）。

マルチアカウントサポート：アカウントごとのトークンとオプションの name で channels.zalo.accounts を使用します。

  1. ゲートウェイを再起動します。Zalo はトークンが解決されると起動します（環境変数または設定）。
  2. DM アクセスはデフォルトでペアリングです。ボットが最初に連絡されたときにコードを承認します。

どのように機能するか（動作）

  • インバウンドメッセージは、メディアプレースホルダーを含む共有チャンネルエンベロープに正規化されます。
  • 返信は常に同じ Zalo チャットにルーティングされます。
  • デフォルトでロングポーリング；channels.zalo.webhookUrl で webhook モードが利用可能。

制限

  • アウトバウンドテキストは 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 を受け入れます（ユーザー名ルックアップは利用不可）。

ロングポーリング vs webhook

  • デフォルト：ロングポーリング（パブリック URL 不要）。
  • Webhook モード：channels.zalo.webhookUrl と channels.zalo.webhookSecret を設定します。
    • Webhook シークレットは 8〜256 文字である必要があります。
    • Webhook URL は HTTPS を使用する必要があります。
    • Zalo は検証用に X-Bot-Api-Secret-Token ヘッダーを含むイベントを送信します。
    • Gateway HTTP は channels.zalo.webhookPath（webhook URL パスにデフォルト）で webhook リクエストを処理します。

注意： getUpdates（ポーリング）と webhook は Zalo API ドキュメントに従って相互に排他的です。

サポートされているメッセージタイプ

  • テキストメッセージ：2000 文字のチャンク分割で完全サポート。
  • 画像メッセージ：インバウンド画像をダウンロードして処理；sendPhoto 経由で画像を送信。
  • スタンプ：ログに記録されますが、完全には処理されません（エージェント応答なし）。
  • サポートされていないタイプ：ログに記録されます（例：保護されたユーザーからのメッセージ）。

機能

機能ステータス
ダイレクトメッセージ✅ サポート
グループ❌ 近日公開予定（Zalo ドキュメントに従って）
メディア（画像）✅ サポート
リアクション❌ サポートされていません
スレッド❌ サポートされていません
投票❌ サポートされていません
ネイティブコマンド❌ サポートされていません
ストリーミング⚠️ ブロック済み（2000 文字制限）

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

  • チャット ID をターゲットとして使用します。
  • 例：openclaw message send --channel zalo --target 123456789 --message "hi"。

トラブルシューティング

ボットが応答しない：

  • トークンが有効か確認：openclaw channels status --probe
  • 送信者が承認されているか確認（ペアリングまたは allowFrom）
  • ゲートウェイログを確認：openclaw logs --follow

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

  • Webhook URL が HTTPS を使用していることを確認
  • シークレットトークンが 8〜256 文字であることを確認
  • 構成されたパスでゲートウェイ HTTP エンドポイントが到達可能であることを確認
  • getUpdates ポーリングが実行されていないことを確認（相互に排他的）

設定リファレンス（Zalo）

完全な設定：Configuration

プロバイダーオプション：

  • 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.mediaMaxMb：インバウンド/アウトバウンドメディアキャップ（MB、デフォルト 5）。
  • channels.zalo.webhookUrl：webhook モードを有効化（HTTPS 必須）。
  • channels.zalo.webhookSecret：webhook シークレット（8〜256 文字）。
  • channels.zalo.webhookPath：ゲートウェイ 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>.webhookUrl：アカウントごとの webhook URL。
  • channels.zalo.accounts.<id>.webhookSecret：アカウントごとの webhook シークレット。
  • channels.zalo.accounts.<id>.webhookPath：アカウントごとの webhook パス。
  • channels.zalo.accounts.<id>.proxy：アカウントごとのプロキシ URL。
← ドキュメントに戻る