Zalo（Bot API）

ステータス：実験的。DMに対応済み。明示的なグループポリシー制御によるグループ処理も利用可能です。

プラグインが必要

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

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

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

1. Zaloプラグインをインストール：
   • ソースチェックアウトから：openclaw plugins install ./extensions/zalo
   • npmから（公開済みの場合）：openclaw plugins install @openclaw/zalo
   • またはオンボーディングでZaloを選択してインストールプロンプトを確認
2. トークンを設定：
   • 環境変数：ZALO_BOT_TOKEN=...
   • または設定：channels.zalo.botToken: "..."
3. Gatewayを再起動（またはオンボーディングを完了）。
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はエージェントのメインセッションを共有します。
• グループはポリシー制御（groupPolicy + groupAllowFrom）に対応し、デフォルトはフェイルクローズの許可リスト動作です。

セットアップ（ファストパス）

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=...（デフォルトアカウントのみ）。

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

3. Gatewayを再起動。トークンが解決される（環境変数または設定）とZaloが起動します。
4. DMアクセスはデフォルトでペアリング。ボットに初めて連絡されたときにコードを承認してください。

動作の仕組み

• 受信メッセージはメディアプレースホルダー付きの共有チャンネルエンベロープに正規化されます。
• 返信は常に同じZaloチャットにルーティングされます。
• デフォルトはロングポーリング。channels.zalo.webhookUrlでウェブフックモードも利用可能。

制限事項

• アウトバウンドテキストは2000文字で分割されます（Zalo API制限）。
• メディアのダウンロード/アップロードはchannels.zalo.mediaMaxMbで制限されます（デフォルト5）。
• 2000文字制限によりストリーミングの有用性が低いため、ストリーミングはデフォルトでブロックされています。

アクセス制御（DM）

DMアクセス

• デフォルト：channels.zalo.dmPolicy = "pairing"。未知の送信者にはペアリングコードが発行されます。承認されるまでメッセージは無視されます（コードは1時間で期限切れ）。
• 承認方法：
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• ペアリングはデフォルトのトークン交換です。詳細：ペアリング
• channels.zalo.allowFromは数値ユーザーIDを受け付けます（ユーザー名検索は利用不可）。

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

• channels.zalo.groupPolicyはグループのインバウンド処理を制御：open | allowlist | disabled。
• デフォルトの動作はフェイルクローズ：allowlist。
• channels.zalo.groupAllowFromはグループ内でボットをトリガーできる送信者IDを制限します。
• groupAllowFromが未設定の場合、Zaloは送信者チェックでallowFromにフォールバックします。
• groupPolicy: "disabled"はすべてのグループメッセージをブロックします。
• groupPolicy: "open"は任意のグループメンバーを許可します（メンションゲーティング付き）。
• ランタイムの注意：channels.zaloが完全に欠落している場合、ランタイムは安全のためgroupPolicy="allowlist"にフォールバックします。

ロングポーリング vs ウェブフック

• デフォルト：ロングポーリング（パブリックURLは不要）。
• ウェブフックモード：channels.zalo.webhookUrlとchannels.zalo.webhookSecretを設定。
  • ウェブフックシークレットは8〜256文字である必要があります。
  • ウェブフックURLはHTTPSを使用する必要があります。
  • Zaloは検証用にX-Bot-Api-Secret-Tokenヘッダー付きでイベントを送信します。
  • Gateway HTTPはchannels.zalo.webhookPathでウェブフックリクエストを処理します（デフォルトはウェブフックURLパス）。
  • リクエストはContent-Type: application/json（または+jsonメディアタイプ）を使用する必要があります。
  • 重複イベント（event_name + message_id）は短いリプレイウィンドウで無視されます。
  • バーストトラフィックはパス/ソースごとにレート制限され、HTTP 429を返す場合があります。

注意： getUpdates（ポーリング）とウェブフックはZalo APIドキュメントごとに相互排他的です。

対応メッセージタイプ

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

機能

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

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

トラブルシューティング

ボットが応答しない：

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

ウェブフックがイベントを受信しない：

• ウェブフックURLがHTTPSを使用しているか確認
• シークレットトークンが8〜256文字か確認
• Gateway HTTPエンドポイントが設定されたパスで到達可能か確認
• getUpdatesポーリングが実行されていないか確認（相互排他的）

設定リファレンス（Zalo）

完全な設定：設定

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

• 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.groupPolicy：open | allowlist | disabled（デフォルト：allowlist）。
• channels.zalo.groupAllowFrom：グループ送信者許可リスト（ユーザーID）。未設定時はallowFromにフォールバック。
• channels.zalo.mediaMaxMb：受信/送信メディアの上限（MB、デフォルト5）。
• channels.zalo.webhookUrl：ウェブフックモードを有効化（HTTPS必須）。
• channels.zalo.webhookSecret：ウェブフックシークレット（8〜256文字）。
• channels.zalo.webhookPath：Gateway HTTPサーバー上のウェブフックパス。
• 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>.groupPolicy：アカウントごとのグループポリシー。
• channels.zalo.accounts.<id>.groupAllowFrom：アカウントごとのグループ送信者許可リスト。
• channels.zalo.accounts.<id>.webhookUrl：アカウントごとのウェブフックURL。
• channels.zalo.accounts.<id>.webhookSecret：アカウントごとのウェブフックシークレット。
• channels.zalo.accounts.<id>.webhookPath：アカウントごとのウェブフックパス。
• channels.zalo.accounts.<id>.proxy：アカウントごとのプロキシURL。