OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Regional platforms

Zalo

狀態：實驗性。已實作私訊與群組聊天；下方的功能表格反映在 Zalo Bot Creator／Marketplace 機器人上經驗證的行為。

內建外掛

目前的 OpenClaw 版本已內建 Zalo 外掛，因此封裝版本不需要另外安裝。

若使用較舊的版本，或使用排除 Zalo 的自訂安裝，請直接安裝 npm 套件：

  • 安裝：openclaw plugins install @openclaw/zalo
  • 鎖定版本：openclaw plugins install @openclaw/zalo@2026.6.11
  • 從本機簽出版本安裝：openclaw plugins install ./path/to/local/zalo-plugin
  • 詳細資訊：外掛

快速設定

  1. 在 https://bot.zaloplatforms.com 建立機器人權杖（登入、建立機器人並配置設定）。權杖為 numeric_id:secret；若是 Marketplace 機器人，可用的執行階段權杖可能會顯示在機器人的歡迎訊息中。
  2. 設定權杖，可以使用環境變數 ZALO_BOT_TOKEN=...（僅限預設帳號），也可以在設定檔中配置。
  3. 重新啟動閘道。
  4. 首次收到私訊時核准配對碼（預設私訊政策為配對）。

最小設定：

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

多帳號：在 channels.zalo.accounts.<id> 下新增更多項目，每個項目都有自己的 botToken/name。channels.zalo.botToken（扁平結構，不含 accounts）是舊版的單帳號簡寫；新設定請優先使用 accounts.<id>.*。

這是什麼

Zalo 是一款以越南市場為主的通訊應用程式。其 Bot API 可讓閘道為 1:1 對話和群組聊天執行機器人，並以確定性方式將訊息路由回 Zalo（模型絕不會選擇頻道）。

本頁說明 Zalo Bot Creator／Marketplace 機器人。Zalo Official Account (OA) 機器人屬於不同的產品介面，其行為可能不同；本頁不涵蓋該類機器人。

運作方式

  • 傳入訊息會連同媒體預留位置正規化為共用的頻道信封。
  • 回覆一律路由回相同的 Zalo 聊天；不使用引用回覆（replyToMode 固定為關閉）。
  • 預設使用長輪詢（getUpdates）；也可透過 channels.zalo.webhookUrl 使用網路鉤子模式。
  • 群組必須透過 @提及才能觸發機器人；無法針對個別頻道配置此行為。

限制

限制 值
傳出文字分段大小 2000 個字元（Zalo API 限制）
媒體大小（傳入／傳出） channels.zalo.mediaMaxMb，預設 5 MB
網路鉤子要求本文 1 MB，讀取逾時 30 秒
網路鉤子速率限制 每個路徑＋用戶端 IP 每 60 秒 120 個要求，之後回傳 HTTP 429
網路鉤子重播墓碑 30 天，每個帳號最多 20,000 個已完成事件（以訊息 ID 為鍵）

存取控制

私訊

  • channels.zalo.dmPolicy：pairing（預設）| allowlist | open | disabled。
  • 配對：未知傳送者會收到配對碼；核准前會忽略其訊息。配對碼會在 1 小時後到期。
    • openclaw pairing list zalo
    • openclaw pairing approve zalo &lt;CODE&gt;
    • 詳細資訊：配對
  • channels.zalo.allowFrom 接受數字形式的 Zalo 使用者 ID（不支援使用者名稱查詢）。open 需要 "*"。

群組

此外掛支援群組聊天（chatTypes: ["direct", "group"]），並由提及和群組政策共同管控：

  • channels.zalo.groupPolicy：open | allowlist | disabled。
  • channels.zalo.groupAllowFrom 限制哪些傳送者 ID 可在群組中觸發機器人；未設定時會改用 allowFrom。
  • 預設解析方式：配置 channels.zalo 時，未設定的 groupPolicy 會解析為 open。若完全缺少 channels.zalo，執行階段會採用失敗關閉原則，設為 allowlist。
  • 實際使用中回報的注意事項：在部分 Marketplace 機器人設定中，機器人完全無法加入群組。如果遇到此問題，請檢查機器人的 Zalo Bot Platform 設定；這是平台端的限制，而非 OpenClaw 政策。

長輪詢與網路鉤子比較

  • 預設：長輪詢（不需要公開 URL）。
  • 網路鉤子模式：設定 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
    • 網路鉤子 URL 必須使用 HTTPS。
    • 網路鉤子密鑰必須為 8-256 個字元。
    • Zalo 透過 X-Bot-Api-Secret-Token 標頭傳送事件，並使用固定時間比較進行檢查。
    • 閘道 HTTP 會在 channels.zalo.webhookPath 處理網路鉤子要求（預設為網路鉤子 URL 的路徑）。
    • 要求必須使用 Content-Type: application/json（或 +json 媒體類型）。
    • 只有在原始事件已持久儲存後才會回傳 HTTP 200；儲存失敗時會回傳 HTTP 500。
    • 依據 Zalo API 文件，每個機器人的 getUpdates 輪詢與網路鉤子互斥。

支援的訊息類型

  • 文字：完整支援，分段上限為 2000 個字元。
  • 媒體：支援傳入／傳出，上限由 mediaMaxMb 設定。
  • 回應、討論串、投票、原生命令：此外掛不支援。
  • 串流：此外掛宣告支援區塊串流，但 Zalo 沒有專用的傳出佇列／文字合併調整選項（不同於部分其他區域性頻道）；如果這對你的使用案例很重要，請在你的環境中驗證目前的行為。

功能

功能 狀態
私訊 支援
群組 支援（需提及才能觸發）
媒體（傳入／傳出） 支援，上限由 mediaMaxMb 設定
回應 不支援
討論串 不支援
投票 不支援
原生命令 不支援
回覆至／引用 不使用（固定為關閉）

傳送目標（命令列介面／排程）

使用聊天 ID 作為目標：

bash
openclaw message send --channel zalo --target 123456789 --message "hi"

疑難排解

機器人沒有回應：

  • 檢查權杖：openclaw channels status --probe
  • 確認傳送者已獲核准（配對或 allowFrom）
  • 檢查閘道記錄：openclaw logs --follow

網路鉤子未收到事件：

  • 確認網路鉤子 URL 使用 HTTPS
  • 確認密鑰為 8-256 個字元
  • 確認可透過已配置的路徑連線到閘道 HTTP 端點
  • 確認 getUpdates 輪詢未同時執行（兩者互斥）
  • 大量突發要求可能會收到 HTTP 429（每個路徑＋IP 每 60 秒 120 個要求）；請降低要求頻率後重試

設定參考

完整設定：設定

設定 說明 預設值
channels.zalo.enabled 啟用／停用頻道啟動 true
channels.zalo.accounts.<id>.botToken 來自 Zalo Bot Platform 的機器人權杖 -
channels.zalo.accounts.<id>.tokenFile 從檔案讀取權杖（拒絕符號連結） -
channels.zalo.accounts.<id>.name 顯示名稱 -
channels.zalo.accounts.<id>.enabled 啟用／停用此帳號 true
channels.zalo.accounts.<id>.dmPolicy 個別帳號的私訊政策 pairing
channels.zalo.accounts.<id>.allowFrom 私訊允許清單（使用者 ID） -
channels.zalo.accounts.<id>.groupPolicy 個別帳號的群組政策 請參閱群組
channels.zalo.accounts.<id>.groupAllowFrom 群組傳送者允許清單；未設定時改用 allowFrom -
channels.zalo.accounts.<id>.mediaMaxMb 傳入／傳出媒體上限（MB） 5
channels.zalo.accounts.<id>.webhookUrl 啟用網路鉤子模式（必須使用 HTTPS） -
channels.zalo.accounts.<id>.webhookSecret 網路鉤子密鑰（8-256 個字元） -
channels.zalo.accounts.<id>.webhookPath 閘道 HTTP 伺服器上的網路鉤子路徑 網路鉤子 URL 路徑
channels.zalo.accounts.<id>.proxy API 要求的 Proxy URL -
channels.zalo.accounts.<id>.responsePrefix 覆寫傳出回應前置字串 -
channels.zalo.defaultAccount 配置多個帳號時的預設帳號 default

channels.zalo.botToken、channels.zalo.dmPolicy 和其他扁平的頂層鍵，是上述欄位的舊版單帳號簡寫；兩種形式皆受支援。

環境變數選項：ZALO_BOT_TOKEN=... 僅會解析預設帳號的權杖。

相關內容

Was this useful?
On this page

On this page