設定 OpenClaw Zalo Personal：5 分鐘內完成個人帳號整合

想要自動化 Zalo 卻發現官方 API 門檻太高，或者根本不支援個人帳號？這通常是開發者最頭痛的事。如果你正想把 Zalo 個人帳號整合進你的工作流，這篇指南會告訴你如何透過 OpenClaw 輕鬆達成。

當你需要讓機器人直接在個人帳號上運作，而不是透過受限的官方 Bot 帳號時，這套整合方案就是你的最佳選擇。

Zalo Personal (非官方)

狀態：實驗性。此整合透過 OpenClaw 內建的 zca-js 實現 Zalo 個人帳號的自動化。

警告： 這是一個非官方的整合方案，可能會導致帳號被停權或封鎖。請自行承擔使用風險。

需要外掛程式

Zalo Personal 以外掛程式形式提供，並未包含在核心安裝包中。

透過 CLI 安裝：openclaw plugins install @openclaw/zalouser
或從原始碼安裝：openclaw plugins install ./path/to/local/zalouser-plugin
詳細資訊：Plugins

不需要額外的 zca/openzca CLI 二進位檔案。

快速設定（初學者）

安裝外掛程式（見上方）。
登入（在 Gateway 機器上顯示 QR Code）：
- openclaw channels login --channel zalouser
- 使用 Zalo 手機 App 掃描 QR Code。
啟用 Channel：

{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

重啟 Gateway（或完成設定）。
私訊存取預設為配對模式；在第一次聯絡時核准配對碼即可。

這是什麼

完全透過 zca-js 在進程內執行。
使用原生事件監聽器接收傳入訊息。
直接透過 JS API 發送回覆（文字/媒體/連結）。
專為無法使用 Zalo Bot API 的「個人帳號」場景設計。

命名規範

Channel ID 為 zalouser，這是為了明確表示它是在自動化 Zalo 個人使用者帳號（非官方）。我們將 zalo 保留給未來可能的官方 Zalo API 整合。

尋找 ID（目錄）

使用目錄 CLI 來發現聯絡人/群組及其 ID：

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"

限制

傳出文字會被切分為約 2000 字的區塊（受限於 Zalo 用戶端限制）。
預設禁用串流 (Streaming)。

存取控制（私訊）

channels.zalouser.dmPolicy 支援：pairing | allowlist | open | disabled（預設值：pairing）。

channels.zalouser.allowFrom 接受使用者 ID 或名稱。在設定期間，名稱會透過外掛程式的進程內聯絡人查詢功能解析為 ID。

核准方式：

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

群組存取（選填）

預設值：channels.zalouser.groupPolicy = "open"（允許群組）。未設定時，可使用 channels.defaults.groupPolicy 來覆蓋預設行為。
使用白名單限制：
- channels.zalouser.groupPolicy = "allowlist"
- channels.zalouser.groups（Key 應為穩定的群組 ID；啟動時會盡可能將名稱解析為 ID）
- channels.zalouser.groupAllowFrom（控制允許群組中的哪些發送者可以觸發機器人）
封鎖所有群組：channels.zalouser.groupPolicy = "disabled"。
設定精靈會提示輸入群組白名單。
啟動時，OpenClaw 會將白名單中的群組/使用者名稱解析為 ID 並記錄對應關係。
群組白名單比對預設僅限 ID。除非啟用了 channels.zalouser.dangerouslyAllowNameMatching: true，否則無法解析的名稱將被忽略。
channels.zalouser.dangerouslyAllowNameMatching: true 是一種緊急相容模式，可重新啟用易變的群組名稱比對。
如果未設定 groupAllowFrom，執行時會退而使用 allowFrom 進行群組發送者檢查。
發送者檢查同時適用於一般群組訊息與控制指令（例如 /new, /reset）。

範例：

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

群組提及過濾

channels.zalouser.groups.<group>.requireMention 控制群組回覆是否需要被提及 (@)。
解析順序：精確群組 ID/名稱 -> 標準化群組 slug -> * -> 預設值 (true)。
此設定同時適用於白名單模式與開放群組模式。
授權的控制指令（例如 /new）可以繞過提及過濾。
當群組訊息因未被提及而被跳過時，OpenClaw 會將其儲存為待處理的群組歷史紀錄，並在下一次處理群組訊息時一併包含。
群組歷史紀錄限制預設為 messages.groupChat.historyLimit（備用值為 50）。你可以針對個別帳號使用 channels.zalouser.historyLimit 進行覆蓋。

範例：

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { allow: true, requireMention: true },
        "Work Chat": { allow: true, requireMention: false },
      },
    },
  },
}

多帳號

帳號會對應到 OpenClaw 狀態中的 zalouser 設定檔。範例：

{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}

輸入中狀態、表情回應與送達確認

OpenClaw 在發送回覆前會先發送「正在輸入」事件（盡力而為）。
zalouser 支援 Channel Actions 中的訊息表情回應動作 react。
- 使用 remove: true 來移除訊息中特定的表情符號。
- 表情回應語義：Reactions
對於包含事件元數據的傳入訊息，OpenClaw 會發送「已送達」與「已讀」確認（盡力而為）。

故障排除

登入狀態無法保持：

檢查狀態：openclaw channels status --probe
重新登入：openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

白名單或群組名稱無法解析：

在 allowFrom/groupAllowFrom/groups 中使用數字 ID，或使用精確的聯絡人/群組名稱。
如果是從舊版基於 CLI 的設定升級，請移除任何關於外部 zca 程序運作的假設。此 Channel 現在完全在 OpenClaw 內部執行，不需要外部 CLI 二進位檔案。

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。