​

Zalo (Bot API)

​

バンドル済みプラグイン

• CLIでインストール: openclaw plugins install @openclaw/zalo
• またはソースチェックアウトから: openclaw plugins install ./path/to/local/zalo-plugin
• 詳細: Plugins

​

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

1. Zaloプラグインが利用可能であることを確認します。
   • 現在のパッケージ版OpenClawリリースには、すでにバンドルされています。
   • 古い/カスタムインストールでは、上記のコマンドで手動追加できます。
2. トークンを設定します。
   • 環境変数: ZALO_BOT_TOKEN=...
   • または設定: channels.zalo.accounts.default.botToken: "..."。
3. Gatewayを再起動します（またはセットアップを完了します）。
4. DMアクセスはデフォルトでペアリングです。初回接触時にペアリングコードを承認してください。

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

​

これは何か

• Gatewayが所有するZalo Bot APIチャンネル。
• 決定論的ルーティング: 返信はZaloに戻り、モデルがチャンネルを選ぶことはありません。
• DMはエージェントのメインセッションを共有します。
• 以下の機能セクションに、現在のMarketplaceボットのサポート状況を示しています。

​

セットアップ（短縮手順）

​

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

1. https://bot.zaloplatforms.comにアクセスしてサインインします。
2. 新しいボットを作成し、その設定を行います。
3. 完全なボットトークン（通常はnumeric_id:secret）をコピーします。Marketplaceボットでは、利用可能なランタイムトークンが作成後のボット歓迎メッセージ内に表示されることがあります。

​

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

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

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

​

仕組み（動作）

• 受信メッセージは、メディアプレースホルダー付きの共有チャンネルエンベロープに正規化されます。
• 返信は常に同じZaloチャットにルーティングされます。
• デフォルトはlong-pollingで、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を受け付けます（ユーザー名参照は利用不可）。

​

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

• channels.zalo.groupPolicyは、グループ受信処理を制御します: open | allowlist | disabled。
• channels.zalo.groupAllowFromは、グループ内でどの送信者IDがボットをトリガーできるかを制限します。
• groupAllowFromが未設定の場合、Zaloは送信者チェックにallowFromへフォールバックします。
• ランタイム注記: channels.zalo自体が完全に欠落している場合でも、安全のためランタイムは引き続きgroupPolicy="allowlist"へフォールバックします。

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

​

Long-polling と webhook

• デフォルト: long-polling（公開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リクエストを処理します（デフォルトはwebhook URLのパス）。
  • リクエストはContent-Type: application/json（または+jsonメディアタイプ）を使用する必要があります。
  • 重複イベント（event_name + message_id）は短いリプレイウィンドウの間、無視されます。
  • バーストトラフィックはパス/送信元ごとにレート制限され、HTTP 429が返る場合があります。

​

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

• テキストメッセージ: 2000文字分割付きで完全サポート。
• テキスト内のプレーンURL: 通常のテキスト入力と同様に動作します。
• リンクプレビュー / リッチリンクカード: 機能のMarketplaceボット状況を参照してください。安定して返信をトリガーしませんでした。
• 画像メッセージ: 機能のMarketplaceボット状況を参照してください。受信画像処理は不安定でした（入力中表示は出るが最終返信なし）。
• ステッカー: 機能のMarketplaceボット状況を参照してください。
• ボイスノート / 音声ファイル / 動画 / 汎用ファイル添付: 機能のMarketplaceボット状況を参照してください。
• 未対応タイプ: ログ出力されます（例: 保護されたユーザーからのメッセージ）。

​

機能

​

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

• ターゲットにはchat idを使用します。
• 例: openclaw message send --channel zalo --target 123456789 --message "hi"。

​

トラブルシューティング

• トークンが有効か確認する: openclaw channels status --probe
• 送信者が承認済みであることを確認する（ペアリングまたはallowFrom）
• Gatewayログを確認する: openclaw logs --follow

• webhook URLがHTTPSを使用していることを確認する
• シークレットトークンが8～256文字であることを確認する
• 設定されたパスでGateway HTTPエンドポイントに到達できることを確認する
• getUpdates pollingが実行中でないことを確認する（相互排他的です）

​

設定リファレンス（Zalo）

• channels.zalo.enabled: チャンネル起動を有効化/無効化します。
• channels.zalo.botToken: Zalo Bot Platformのボットトークン。
• channels.zalo.tokenFile: 通常のファイルパスからトークンを読み取ります。symlinkは拒否されます。
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled（デフォルト: pairing）。
• channels.zalo.allowFrom: DM許可リスト（ユーザーID）。openには"*"が必要です。ウィザードでは数値IDを尋ねます。
• channels.zalo.groupPolicy: open | allowlist | disabled（デフォルト: allowlist）。設定には存在します。現在のMarketplaceボットの挙動については、機能およびアクセス制御（グループ）を参照してください。
• channels.zalo.groupAllowFrom: グループ送信者許可リスト（ユーザーID）。未設定時はallowFromへフォールバックします。
• channels.zalo.mediaMaxMb: 受信/送信メディア上限（MB、デフォルト5）。
• channels.zalo.webhookUrl: webhookモードを有効化します（HTTPS必須）。
• channels.zalo.webhookSecret: webhookシークレット（8～256文字）。
• channels.zalo.webhookPath: Gateway HTTPサーバー上のwebhookパス。
• channels.zalo.proxy: APIリクエスト用プロキシURL。

• channels.zalo.accounts.<id>.botToken: アカウントごとのトークン。
• channels.zalo.accounts.<id>.tokenFile: アカウントごとの通常のトークンファイル。symlinkは拒否されます。
• 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: アカウントごとのグループポリシー。設定には存在します。現在のMarketplaceボットの挙動については、機能およびアクセス制御（グループ）を参照してください。
• channels.zalo.accounts.<id>.groupAllowFrom: アカウントごとのグループ送信者許可リスト。
• 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。

​

関連

• Channels Overview — サポートされるすべてのチャンネル
• Pairing — DM認証とペアリングフロー
• Groups — グループチャットの挙動とメンション制御
• Channel Routing — メッセージのセッションルーティング
• Security — アクセスモデルとハードニング