Zalo 個人帳號（非官方）

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

警告： 這是非官方整合，可能導致帳號被暫停或封禁。使用風險自負。

需要外掛

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

透過 CLI 安裝：openclaw plugins install @openclaw/zalouser
或從原始碼 checkout：openclaw plugins install ./extensions/zalouser
詳情：外掛

不需要外部 zca/openzca CLI 二進位檔。

快速設定（入門）

安裝外掛（見上方）。
登入（QR，在 Gateway 機器上）：
- openclaw channels login --channel zalouser
- 用 Zalo 手機應用程式掃描 QR 碼。
啟用頻道：

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

重啟 Gateway（或完成引導設定）。
私訊存取預設為配對模式；首次聯繫時核准配對代碼。

這是什麼

完全在程序內透過 zca-js 運行。
使用原生事件監聽器接收接收訊息。
透過 JS API 直接發送回覆（文字/媒體/連結）。
專為 Zalo Bot API 不可用時的「個人帳號」使用情境設計。

命名

頻道 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 客戶端限制）。
串流預設為封鎖。

存取控制（私訊）

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（鍵應為穩定的群組 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）。
這同時適用於許可清單群組和開放群組模式。
來自授權發送者的控制指令可以繞過提及管控。
當群組訊息因需要提及而被跳過時，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 的訊息表情回應操作 react。
- 使用 remove: true 從訊息中移除特定的表情符號回應。
- 表情回應語意：表情回應
對於包含事件中繼資料的接收訊息，OpenClaw 會發送已送達和已讀確認（盡力而為）。

疑難排解

登入無法保持：

openclaw channels status --probe
重新登入：openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

許可清單/群組名稱未解析：

在 allowFrom/groupAllowFrom/groups 中使用數字 ID，或精確的好友/群組名稱。

從舊版 CLI 為基礎的設定升級：

移除任何舊版外部 zca 程序假設。
頻道現在完全在 OpenClaw 內運行，不需要外部 CLI 二進位檔。