Zalo

​

バンドル済み Plugin

• インストール: openclaw plugins install @openclaw/zalo
• 固定バージョン: openclaw plugins install @openclaw/zalo@2026.6.11
• ローカルチェックアウトから: openclaw plugins install ./path/to/local/zalo-plugin
• 詳細: Plugins

​

クイックセットアップ

1. https://bot.zaloplatforms.com でボットトークンを作成します（サインインし、ボットを作成して設定を構成します）。トークンは numeric_id:secret です。Marketplace ボットでは、利用可能なランタイムトークンがボットのウェルカムメッセージに表示される場合があります。
2. トークンを、env ZALO_BOT_TOKEN=...（デフォルトアカウントのみ）または設定で指定します。
3. Gateway を再起動します。
4. 初回 DM 接触時にペアリングコードを承認します（デフォルトの DM ポリシーはペアリングです）。

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

​

概要

​

仕組み

• 受信メッセージは、メディアプレースホルダー付きの共有チャンネルエンベロープに正規化されます。
• 返信は常に同じ Zalo チャットへルーティングされます。引用返信は使用されません（replyToMode は固定でオフです）。
• デフォルトはロングポーリング（getUpdates）です。Webhook モードは channels.zalo.webhookUrl で利用できます。
• グループではボットを起動するために @mention が必要です。これはチャンネルごとには設定できません。

​

制限

​

アクセス制御

​

ダイレクトメッセージ

• channels.zalo.dmPolicy: pairing（デフォルト） | allowlist | open | disabled。
• ペアリング: 不明な送信者にはペアリングコードが送られます。承認されるまでメッセージは無視されます。コードは 1 時間後に期限切れになります。
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • 詳細: ペアリング
• channels.zalo.allowFrom は数値の Zalo ユーザー ID を受け付けます（ユーザー名検索はありません）。open には "*" が必要です。

​

グループ

• channels.zalo.groupPolicy: open | allowlist | disabled。
• channels.zalo.groupAllowFrom は、グループ内でボットを起動できる送信者 ID を制限します。未設定の場合は allowFrom にフォールバックします。
• デフォルト解決: channels.zalo が設定されている場合、未設定の groupPolicy は open に解決されます。channels.zalo がまったくない場合、ランタイムはフェイルクローズして allowlist になります。
• 報告されている実環境の注意点: 一部の Marketplace ボット設定では、ボットをグループにまったく追加できない場合があります。この問題に遭遇した場合は、ボットの Zalo Bot Platform 設定で確認してください。これはプラットフォーム側の制約であり、OpenClaw のポリシーではありません。

​

ロングポーリングと Webhook

• デフォルト: ロングポーリング（公開 URL は不要）。
• Webhook モード: channels.zalo.webhookUrl と channels.zalo.webhookSecret を設定します。
  • Webhook URL は HTTPS を使用する必要があります。
  • Webhook シークレットは 8-256 文字である必要があります。
  • Zalo は X-Bot-Api-Secret-Token ヘッダー付きでイベントを送信し、定数時間比較でチェックされます。
  • Gateway HTTP は channels.zalo.webhookPath で Webhook リクエストを処理します（デフォルトは Webhook URL のパス）。
  • リクエストは Content-Type: application/json（または +json メディアタイプ）を使用する必要があります。
  • getUpdates ポーリングと Webhook は、Zalo API ドキュメント上、Zalo API ごとに相互排他的です。

​

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

• テキスト: 完全サポート、2000 文字ごとに分割。
• メディア: 受信/送信、mediaMaxMb で上限設定。
• リアクション、スレッド、投票、ネイティブコマンド: Plugin ではサポートされません。
• ストリーミング: Plugin はブロックストリーミング機能を宣言しますが、Zalo には専用の送信キュー/テキスト結合の調整ノブはありません（一部の他の地域向けチャンネルとは異なります）。これがユースケースに重要な場合は、現在の動作を自分の環境で確認してください。

​

機能

​

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

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 ポーリングも同時に実行されていないことを確認します（これらは相互排他的です）
• リクエストのバーストは HTTP 429 を返す場合があります（パス+IP ごとに 60 秒あたり 120 リクエスト）。バックオフして再試行してください

​

設定リファレンス

​

関連

• チャンネル概要 - サポートされるすべてのチャンネル
• ペアリング - DM 認証とペアリングフロー
• グループ - グループチャットの動作とメンション制御
• チャンネルルーティング - メッセージのセッションルーティング
• セキュリティ - アクセスモデルと堅牢化