跳轉到主要內容
狀態：實驗性。私訊和群組聊天都已實作；下方的 功能 表格反映 Zalo Bot Creator / Marketplace 機器人上已驗證的行為。

​
捆綁外掛

Zalo 以捆綁外掛形式隨目前的 OpenClaw 發行版本提供，因此打包建置不需要另外安裝。 在較舊的建置，或排除 Zalo 的自訂安裝中，請直接安裝 npm 套件：
  • 安裝：openclaw plugins install @openclaw/zalo
  • 釘選版本：openclaw plugins install @openclaw/zalo@2026.6.11
  • 從本機 checkout：openclaw plugins install ./path/to/local/zalo-plugin
  • 詳細資料：外掛

​
快速設定

  1. 在 https://bot.zaloplatforms.com 建立機器人權杖（登入、建立機器人、設定選項）。權杖格式為 numeric_id:secret；對 Marketplace 機器人而言，可用的執行階段權杖可能會出現在機器人的歡迎訊息中。
  2. 設定權杖，可設為環境變數 ZALO_BOT_TOKEN=...（僅限預設帳號）或寫入設定。
  3. 重新啟動閘道。
  4. 第一次私訊聯絡時核准配對碼（預設私訊政策為配對）。
最小設定： 
{
  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 秒讀取逾時
網路鉤子速率限制每個 path+client IP 於 60 秒內 120 個請求，之後回傳 HTTP 429
網路鉤子重複事件視窗5 分鐘（以 path + account + event name + chat + sender + message id 作為鍵）

​
存取控制

​
私訊

  • channels.zalo.dmPolicy：pairing（預設）| allowlist | open | disabled。
  • 配對：未知傳送者會收到配對碼；訊息會被忽略，直到核准為止。代碼會在 1 小時後過期。
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
    • 詳細資料：配對
  • 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 媒體類型）。
    • 依 Zalo API 文件，getUpdates 輪詢和網路鉤子在每個 Zalo API 中互斥。

​
支援的訊息類型

  • 文字：完整支援，分段為 2000 個字元。
  • 媒體：傳入/傳出，受 mediaMaxMb 限制。
  • 反應、討論串、投票、原生指令：外掛不支援。
  • 串流：外掛宣告區塊串流能力，但 Zalo 沒有專用的傳出佇列/合併文字調校旋鈕（不同於某些其他區域頻道）；如果這對你的使用案例很重要，請在你的環境中驗證目前行為。

​
功能

功能狀態
私訊支援
群組支援（由提及控管）
媒體（傳入/傳出）支援，受 mediaMaxMb 限制
反應不支援
討論串不支援
投票不支援
原生指令不支援
回覆至 / 引用未使用（固定關閉）

​
傳遞目標（命令列介面/排程）

使用聊天 ID 作為目標： 
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（每個 path+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>.proxyAPI 請求的 Proxy URL-
channels.zalo.accounts.<id>.responsePrefix傳出回應前綴覆寫-
channels.zalo.defaultAccount設定多個帳號時的預設帳號default
channels.zalo.botToken、channels.zalo.dmPolicy 和其他扁平頂層鍵是上述欄位的舊版單帳號簡寫；兩種形式都支援。 環境變數選項：ZALO_BOT_TOKEN=... 僅解析預設帳號的權杖。

​
相關