如何在 Gateway 中串接 Zalo Bot API

如果你曾經試過串接不同國家的通訊軟體 API，應該知道那種被各種認證機制和訊息格式搞瘋的感覺。每次想開拓一個新市場，都要重新研究一套底層邏輯，光是處理基礎的連線和 Webhook 驗證就要花掉不少開發時間，沒辦法專注在真正的功能開發上。

這篇文章會教你如何快速將 Zalo 整合進你的 Gateway，讓你用最簡單的方式開始處理來自越南用戶的訊息。

需要準備的東西

• Zalo Bot Platform 帳號與 Bot Token
• @openclaw/zalo 插件
• 運作中的 Gateway 環境

快速開始

Zalo 目前是以插件形式提供，並未內建在核心安裝包中。你可以按照以下步驟在 5 分鐘內完成設定：

1. 安裝插件

你可以透過 CLI 直接安裝：

openclaw plugins install @openclaw/zalo

或者在 onboarding 過程中選擇 Zalo 並確認安裝提示。

2. 取得 Token

1. 前往 Zalo Bot Platform 並登入。
2. 建立一個新的 bot 並完成設定。
3. 複製產生的 bot token（格式通常為 12345689:abc-xyz）。

3. 配置設定

你可以選擇使用環境變數或修改設定檔。最簡單的 config.json5 設定如下：

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

如果你偏好環境變數，可以設定 ZALO_BOT_TOKEN=...（這僅適用於預設帳號）。

4. 啟動與配對

重啟你的 Gateway。當你第一次從 Zalo 傳送訊息給機器人時，系統預設會啟用 pairing 模式。你會收到一個配對碼，請在 CLI 輸入以下指令來核准：

openclaw pairing approve zalo <你的配對碼>

疑難排解

機器人沒有回應：

• 檢查你的 token 是否有效：執行 openclaw channels status --probe。
• 確認發送者是否已通過審核（檢查 pairing 狀態或 allowFrom 名單）。
• 查看 Gateway 即時日誌：openclaw logs --follow。

Webhook 收不到事件：

• 確保你的 Webhook URL 使用的是 HTTPS 協定。
• 檢查 webhookSecret 長度是否介於 8-256 字元之間。
• 確認 Gateway 的 HTTP endpoint 路徑可以被外部正常存取。
• 檢查是否同時開啟了長輪詢（Long-polling），根據 Zalo API 規範，輪詢與 Webhook 是互斥的。

如果你在設定過程中卡住了，可以隨時詢問 AI Setup Assistant 獲取協助。

下一步

• Plugins 插件詳解
• Pairing 配對機制說明
• Gateway 配置參考