Zalo（Bot API）

狀態：實驗性。支援私訊；群組處理可透過明確的群組政策控制使用。

需要外掛

Zalo 以外掛形式提供，不包含在核心安裝中。

• 透過 CLI 安裝：openclaw plugins install @openclaw/zalo
• 或在引導設定時選擇 Zalo 並確認安裝提示
• 詳情：外掛

快速設定（入門）

1. 安裝 Zalo 外掛：
   • 從原始碼 checkout：openclaw plugins install ./extensions/zalo
   • 從 npm（如已發佈）：openclaw plugins install @openclaw/zalo
   • 或在引導設定時選擇 Zalo 並確認安裝提示
2. 設定 token：
   • 環境變數：ZALO_BOT_TOKEN=...
   • 或設定：channels.zalo.botToken: "..."
3. 重啟 Gateway（或完成引導設定）。
4. 私訊存取預設為配對模式；首次聯繫時核准配對代碼。

最小設定：

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

這是什麼

Zalo 是一個以越南為主的通訊應用程式；其 Bot API 讓 Gateway 可以為一對一對話運行機器人。 適合需要確定性路由回 Zalo 的客服或通知場景。

• 由 Gateway 擁有的 Zalo Bot API 頻道。
• 確定性路由：回覆永遠回到 Zalo；模型不會選擇頻道。
• 私訊共享代理的主要工作階段。
• 群組支援政策控制（groupPolicy + groupAllowFrom），預設為失敗關閉的許可清單行為。

設定（快速路徑）

1) 建立機器人 token（Zalo Bot Platform）

1. 前往 https://bot.zaloplatforms.com 並登入。
2. 建立新機器人並設定相關選項。
3. 複製機器人 token（格式：12345689:abc-xyz）。

2) 設定 token（環境變數或設定檔）

範例：

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

環境變數選項：ZALO_BOT_TOKEN=...（僅限預設帳號）。

多帳號支援：使用 channels.zalo.accounts 搭配按帳號的 token 和選用的 name。

3. 重啟 Gateway。當 token 被解析（環境變數或設定檔）後，Zalo 即會啟動。
4. 私訊存取預設為配對模式。首次聯繫機器人時核准配對代碼。

運作方式（行為）

• 接收的訊息被正規化為共用頻道封包，含媒體佔位符。
• 回覆永遠路由回同一個 Zalo 對話。
• 預設使用長輪詢；可透過 channels.zalo.webhookUrl 啟用 webhook 模式。

限制

• 外送文字以 2000 字元為單位分段（Zalo API 限制）。
• 媒體下載/上傳受 channels.zalo.mediaMaxMb（預設 5）限制。
• 串流預設為封鎖，因為 2000 字元限制使串流效果不佳。

存取控制（私訊）

私訊存取

• 預設：channels.zalo.dmPolicy = "pairing"。未知發送者會收到配對代碼；訊息在核准前會被忽略（代碼 1 小時後過期）。
• 核准方式：
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• 配對是預設的 token 交換。詳情：配對
• 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 webhook

• 預設：長輪詢（不需要公開 URL）。
• Webhook 模式：設定 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
  • webhook secret 必須為 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。

注意： 根據 Zalo API 文件，getUpdates（輪詢）和 webhook 是互斥的。

支援的訊息類型

• 文字訊息：完全支援，2000 字元分段。
• 圖片訊息：下載並處理接收的圖片；透過 sendPhoto 發送圖片。
• 貼圖：記錄但未完全處理（無代理回覆）。
• 不支援的類型：記錄（例如來自受保護使用者的訊息）。

功能

傳送目標（CLI/cron）

• 使用聊天 ID 作為目標。
• 範例：openclaw message send --channel zalo --target 123456789 --message "hi"。

疑難排解

機器人不回覆：

• 檢查 token 是否有效：openclaw channels status --probe
• 驗證發送者已核准（配對或 allowFrom）
• 檢查 Gateway 日誌：openclaw logs --follow

Webhook 沒有接收事件：

• 確保 webhook URL 使用 HTTPS
• 驗證 secret token 為 8-256 個字元
• 確認 Gateway HTTP 端點在設定的路徑上可達
• 檢查 getUpdates 輪詢是否正在運行（兩者互斥）

設定參考（Zalo）

完整設定：設定

供應商選項：

• channels.zalo.enabled：啟用/停用頻道啟動。
• channels.zalo.botToken：來自 Zalo Bot Platform 的機器人 token。
• channels.zalo.tokenFile：從一般檔案路徑讀取 token。符號連結會被拒絕。
• channels.zalo.dmPolicy：pairing | allowlist | open | disabled（預設：pairing）。
• channels.zalo.allowFrom：私訊許可清單（使用者 ID）。open 需要 "*"。精靈會要求輸入數字 ID。
• channels.zalo.groupPolicy：open | allowlist | disabled（預設：allowlist）。
• channels.zalo.groupAllowFrom：群組發送者許可清單（使用者 ID）。未設定時備援使用 allowFrom。
• channels.zalo.mediaMaxMb：接收/外送媒體上限（MB，預設 5）。
• channels.zalo.webhookUrl：啟用 webhook 模式（需要 HTTPS）。
• channels.zalo.webhookSecret：webhook secret（8-256 字元）。
• channels.zalo.webhookPath：Gateway HTTP 伺服器上的 webhook 路徑。
• channels.zalo.proxy：API 請求的代理 URL。

多帳號選項：

• channels.zalo.accounts.<id>.botToken：按帳號的 token。
• channels.zalo.accounts.<id>.tokenFile：按帳號的一般 token 檔案。符號連結會被拒絕。
• channels.zalo.accounts.<id>.name：顯示名稱。
• channels.zalo.accounts.<id>.enabled：啟用/停用帳號。
• channels.zalo.accounts.<id>.dmPolicy：按帳號的私訊政策。
• channels.zalo.accounts.<id>.allowFrom：按帳號的許可清單。
• channels.zalo.accounts.<id>.groupPolicy：按帳號的群組政策。
• channels.zalo.accounts.<id>.groupAllowFrom：按帳號的群組發送者許可清單。
• channels.zalo.accounts.<id>.webhookUrl：按帳號的 webhook URL。
• channels.zalo.accounts.<id>.webhookSecret：按帳號的 webhook secret。
• channels.zalo.accounts.<id>.webhookPath：按帳號的 webhook 路徑。
• channels.zalo.accounts.<id>.proxy：按帳號的代理 URL。