OpenClaw Zalo 頻道
即時通訊
中等
透過 Zalo Bot Platform 將 OpenClaw 連接到 Zalo。此整合讓你的 AI 助手可以在越南最受歡迎的即時通訊應用程式上收發訊息。只需設定 Bot Token，配置私訊策略，即可開始聊天——支援長輪詢和 Webhook 兩種訊息接收模式。
快速資訊
難度中等
分類即時通訊
支援功能數1 / 6
Zalo 支援功能
文字訊息
支援
媒體與檔案
不支援
表情回應
不支援
討論串
不支援
語音訊息
不支援
群組聊天
不支援
Zalo 前置條件
- 擁有 Zalo 帳號並可存取 Zalo Bot Platform（bot.zaloplatforms.com）
- 從 Zalo Bot Platform 控制台取得的 Bot Token
- OpenClaw Gateway 已執行並設定完成
- 若使用 Webhook 模式：需要一個可公開存取的 HTTPS 端點
Zalo 快速設定
1
建立 Zalo Bot 並取得 Token
前往 bot.zaloplatforms.com，使用 Zalo 帳號登入，建立一個新的 Bot。從控制台複製 Bot Token（格式如：12345689:abc-xyz）。
2
新增 Zalo 頻道設定
將 Zalo 頻道設定新增到 ~/.openclaw/openclaw.json。設定 botToken、dmPolicy（pairing、allowlist、open 或 disabled），並可選擇設定 Webhook。
3
啟動 Gateway 並測試
使用 'openclaw start' 啟動 Gateway。預設透過長輪詢模式連線。在 Zalo 上向你的 Bot 傳送一條訊息以驗證連線是否正常。
Zalo 設定範例
config.json
{
"channels": {
"zalo": {
"enabled": true,
"botToken": "12345689:abc-xyz",
"dmPolicy": "pairing"
}
}
}Zalo 深入了解
架構概覽
OpenClaw 透過 Zalo Bot Platform API 傳送和接收訊息。Gateway 使用長輪詢（預設）或 Webhook 模式與 Zalo 伺服器通訊。
在長輪詢模式下，Gateway 定期檢查新訊息——無需公網 URL 或 HTTPS 憑證。在 Webhook 模式下，Zalo 會直接將事件推送到你的伺服器，這需要一個可公開存取的 HTTPS 端點。
Zalo 使用者的訊息由 Gateway 接收，交由 AI 處理，然後透過 Zalo Bot API 傳送回覆。每個對話按使用者獨立追蹤，因此多個使用者可以同時與同一個 Bot 互動。
長輪詢無需任何網路設定即可使用。適合開發環境或沒有公網 URL 的場景。
Webhook 模式延遲更低，建議在擁有穩定 HTTPS 端點的生產環境中使用。
建立 Zalo Bot
要將 OpenClaw 連接到 Zalo，你需要從 Zalo Bot Platform 取得 Bot Token：
1. 前往 bot.zaloplatforms.com，使用 Zalo 帳號登入。
2. 點擊「建立 Bot」並填寫必要資訊（名稱、描述、分類）。
3. 建立完成後，進入 Bot 設定頁面並複製 Bot Token。
Bot Token 是連線所需的唯一憑證。你可以透過設定檔、環境變數（ZALO_BOT_TOKEN）或使用 tokenFile 選項從檔案讀取。
openclaw.json
{
"channels": {
"zalo": {
"enabled": true,
"botToken": "12345689:abc-xyz"
}
}
}將 Bot Token 儲存在環境變數（ZALO_BOT_TOKEN）或單獨檔案（tokenFile）中，避免將密鑰提交到版本控制系統。
私訊策略
私訊策略控制誰可以與你的 AI 助手互動。OpenClaw 支援四種策略：
• pairing（預設）— 新使用者首次傳送訊息時會收到配對碼。你可以透過 'openclaw pairing approve zalo <code>' 核准或拒絕。配對碼在 1 小時後過期。
• allowlist — 只有 allowFrom 清單中的數字使用者 ID 可以與 Bot 互動。其他人將被靜默忽略。
• open — 任何向 Bot 傳送訊息的人都會收到回覆。請謹慎使用。
• disabled — 完全關閉私訊處理。
openclaw.json
{
"channels": {
"zalo": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "987654321"]
}
}
}'open' 策略允許任何人與你的 Bot 互動。如果你的 Bot 在 Zalo 上是公開可發現的，這可能會消耗大量 AI 配額。
Webhook 設定
預設情況下，OpenClaw 使用長輪詢接收訊息。要切換到 Webhook 模式，請在設定中設定 webhookUrl。這需要一個可公開存取的 HTTPS 端點。
啟用 Webhook 模式後，長輪詢會自動停用。Zalo 會直接將訊息事件傳送到你的 Webhook URL。驗證透過 Secret Token 完成——Zalo 會在每個請求的 X-Bot-Api-Secret-Token HTTP 標頭中包含該 Token。
webhookPath 選項允許你自訂 Gateway HTTP 伺服器上接收 Zalo 事件的路徑。
openclaw.json
{
"channels": {
"zalo": {
"botToken": "12345689:abc-xyz",
"webhookUrl": "https://your-server.com/zalo/webhook",
"webhookSecret": "your-secret-string-8-to-256-chars",
"webhookPath": "/zalo/webhook"
}
}
}webhookSecret 的長度必須在 8 到 256 個字元之間。
Webhook 和長輪詢是互斥的——設定 webhookUrl 會自動停用輪詢。
訊息處理
OpenClaw 在 Zalo 上支援文字訊息和圖片訊息。文字訊息會按照 Zalo 的限制自動在 2,000 個字元處分段。
使用者傳送的圖片會被下載並處理。向外傳送的圖片透過 Zalo sendPhoto API 傳送。使用者傳送的貼圖訊息會被記錄但不會交由 AI 處理。
mediaMaxMb 設定控制接收媒體檔案的最大大小（預設：5 MB）。
較長的 AI 回覆會自動在 2,000 字元邊界處拆分為多條訊息。
由於字元限制，Zalo 不支援串流回應。
多帳號設定
OpenClaw 支援同時執行多個 Zalo Bot 帳號。每個帳號有獨立的 Bot Token、私訊策略和可選的 Webhook 設定。
如果你想在同一個 Gateway 實例下執行不同用途的 Bot（例如客服 Bot 和內部團隊 Bot），這非常實用。
openclaw.json
{
"channels": {
"zalo": {
"accounts": {
"support-bot": {
"botToken": "token-for-support-bot",
"dmPolicy": "open"
},
"team-bot": {
"botToken": "token-for-team-bot",
"dmPolicy": "allowlist",
"allowFrom": ["111222333"]
}
}
}
}
}主動傳送訊息
你可以透過 CLI 向特定 Zalo 使用者傳送訊息。訊息會確定性地路由回原始 Zalo 聊天，因此回覆始終傳送給正確的使用者。
要向特定使用者傳送手動訊息，使用 target 參數並指定其數字 Zalo 使用者 ID。
terminal
openclaw message send --channel zalo --target 123456789代理設定
如果你的伺服器需要透過代理進行出站連線，可以為 Zalo 頻道設定代理。代理 URL 將用於所有發往 Zalo 伺服器的 API 請求。
這在企業環境或直接存取 Zalo API 端點受限的地區非常實用。
openclaw.json
{
"channels": {
"zalo": {
"proxy": "http://proxy.example.com:8080"
}
}
}Zalo 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | 啟用或停用 Zalo 頻道 |
| botToken | string | "" | 來自 Zalo Bot Platform（bot.zaloplatforms.com）的 Bot Token |
| tokenFile | string | "" | 從檔案路徑讀取 Bot Token，替代內聯設定 |
| dmPolicy | string | "pairing" | 控制誰可以與 Bot 私訊。選項：pairing、allowlist、open、disabled |
| allowFrom | string[] | [] | 允許與 Bot 互動的數字 Zalo 使用者 ID 清單（當 dmPolicy 為 allowlist 時使用） |
| mediaMaxMb | number | 5 | 接收媒體檔案的最大大小（MB） |
| webhookUrl | string | "" | Webhook 模式的 HTTPS URL。設定後將停用長輪詢 |
| webhookSecret | string | "" | 用於 Webhook 驗證的密鑰字串（8-256 個字元），透過 X-Bot-Api-Secret-Token 標頭傳遞 |
| webhookPath | string | "" | Gateway HTTP 伺服器上的自訂 Webhook 路徑 |
| proxy | string | "" | 發往 Zalo 的出站 API 請求使用的代理 URL |
| accounts.<id>.botToken | string | "" | 多帳號模式下特定帳號的 Bot Token |
| accounts.<id>.dmPolicy | string | "pairing" | 特定帳號的私訊策略覆寫 |
| accounts.<id>.webhookUrl | string | "" | 特定帳號的 Webhook URL 覆寫 |
enabled
Type: booleanDefault: false
啟用或停用 Zalo 頻道
botToken
Type: stringDefault: ""
來自 Zalo Bot Platform（bot.zaloplatforms.com）的 Bot Token
tokenFile
Type: stringDefault: ""
從檔案路徑讀取 Bot Token，替代內聯設定
dmPolicy
Type: stringDefault: "pairing"
控制誰可以與 Bot 私訊。選項：pairing、allowlist、open、disabled
allowFrom
Type: string[]Default: []
允許與 Bot 互動的數字 Zalo 使用者 ID 清單（當 dmPolicy 為 allowlist 時使用）
mediaMaxMb
Type: numberDefault: 5
接收媒體檔案的最大大小（MB）
webhookUrl
Type: stringDefault: ""
Webhook 模式的 HTTPS URL。設定後將停用長輪詢
webhookSecret
Type: stringDefault: ""
用於 Webhook 驗證的密鑰字串（8-256 個字元），透過 X-Bot-Api-Secret-Token 標頭傳遞
webhookPath
Type: stringDefault: ""
Gateway HTTP 伺服器上的自訂 Webhook 路徑
proxy
Type: stringDefault: ""
發往 Zalo 的出站 API 請求使用的代理 URL
accounts.<id>.botToken
Type: stringDefault: ""
多帳號模式下特定帳號的 Bot Token
accounts.<id>.dmPolicy
Type: stringDefault: "pairing"
特定帳號的私訊策略覆寫
accounts.<id>.webhookUrl
Type: stringDefault: ""
特定帳號的 Webhook URL 覆寫
Zalo 常見問題
Zalo 故障排除
Bot 收不到任何訊息
Bot Token 可能無效、已過期，或 Gateway 未執行。在 Webhook 模式下，HTTPS 端點可能無法存取。
在 bot.zaloplatforms.com 驗證你的 Bot Token。檢查 Gateway 日誌中的連線錯誤。如果使用 Webhook，確認端點可透過 HTTPS 公開存取，且 webhookSecret 相符。
訊息延遲或批次到達
長輪詢相比 Webhook 模式存在固有延遲。網路不穩定也可能導致訊息批次到達。
切換到 Webhook 模式以取得更低延遲。確保伺服器網路連線穩定。檢查 Gateway 日誌中的輪詢間隔資訊。
新使用者未收到配對碼
dmPolicy 可能未設定為 'pairing'，或 Bot 未正確連接到 Zalo。
確認設定中 dmPolicy 已設定為 'pairing'。檢查 Gateway 日誌確認 Zalo 頻道已上線。執行 'openclaw pairing list zalo' 查看待處理的配對請求。
圖片訊息傳送失敗
圖片檔案可能超過 mediaMaxMb 限制，或 Zalo API 暫時無法使用。
檢查圖片檔案大小是否在 mediaMaxMb 限制內（預設：5 MB）。查看 Gateway 日誌中的具體 API 錯誤訊息。先嘗試傳送文字訊息以確認連線正常。
Webhook 驗證失敗
設定中的 webhookSecret 與 Zalo 預期的不相符，或端點未回傳正確回應。
確保 webhookSecret 長度在 8 到 256 個字元之間。驗證 HTTPS 憑證是否有效（不接受自簽憑證）。檢查 webhookPath 是否與伺服器的路由設定相符。