OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Regional platforms

Zalo Personal

狀態：實驗性。此整合透過原生 zca-js 在程序內自動操作個人 Zalo 帳號，不需要外部命令列介面執行檔。

安裝

Zalo Personal 是官方外部外掛，並未隨核心一同提供。使用前請先安裝：

bash
openclaw plugins install @openclaw/zalouser
  • 鎖定版本：openclaw plugins install @openclaw/zalouser@<version>
  • 從原始碼簽出版本安裝：openclaw plugins install ./path/to/local/zalouser-plugin
  • 詳細資訊：外掛

快速設定

  1. 安裝外掛（如上所述）。
  2. 登入（在閘道機器上使用 QR Code）：
    • openclaw channels login --channel zalouser
    • 使用 Zalo 行動應用程式掃描 QR Code。
  3. 啟用頻道：
json5
{  channels: {    zalouser: {      enabled: true,      dmPolicy: "pairing",    },  },}
  1. 重新啟動閘道（或完成設定）。
  2. 私訊存取預設使用配對；第一次聯絡時請核准配對碼。

功能說明

  • 完全透過 zca-js 程式庫在程序內執行（不需要外部 zca/openzca 執行檔）。
  • 使用原生事件監聽器（message、error）接收傳入訊息。
  • 透過 JS API 直接傳送回覆（文字／媒體／連結）。
  • 專為無法使用 Zalo Bot API 的「個人帳號」使用情境所設計。

命名

頻道 ID 為 zalouser，以明確表示其自動操作的是個人 Zalo 使用者帳號（非官方）。zalo 保留供未來可能推出的官方 Zalo API 整合使用。

尋找 ID（目錄）

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

限制

  • 傳出文字會依 2000 個字元分段（Zalo 用戶端限制）。
  • 不支援串流。
  • 已完成處理的傳入訊息 ID 會保留 30 天，每個帳號最多保留最近的 1000 筆項目。

傳入訊息持久性

OpenClaw 會在處理每個原始 zca-js 訊息回呼之前，先將其儲存。閘道重新啟動後，待處理訊息會從帳號佇列繼續處理，且每個直接聊天或群組的處理會維持循序執行。

zca-js 通訊端監聽器不會提供送達確認，也不會在重新連線後自動重播舊訊息。因此，持久性佇列只能防範回呼送達 OpenClaw 後的本機當機空窗；無法復原通訊端從未送達的訊息。重播刪除標記主要用於防範同一個 Zalo 訊息 ID 的回呼重複出現。

存取控制（私訊）

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

channels.zalouser.allowFrom 應使用穩定的 Zalo 使用者 ID。它也可以參照靜態傳送者存取群組（accessGroup:<name>）。在互動式設定期間，可使用外掛的程序內聯絡人查詢，將輸入的名稱解析為 ID。

如果設定中仍有原始名稱，只有啟用 channels.zalouser.dangerouslyAllowNameMatching: true 時，啟動程序才會解析該名稱。若未明確啟用此選項，執行階段的傳送者檢查只會使用 ID，且會忽略原始名稱，不將其用於授權。

核准方式：

  • openclaw pairing list zalouser
  • openclaw pairing approve zalouser <code>

群組存取（選用）

  • 預設：channels.zalouser.groupPolicy = "allowlist"（群組必須有明確的允許清單項目）。
  • 開放所有群組：channels.zalouser.groupPolicy = "open"。
  • 封鎖所有群組：channels.zalouser.groupPolicy = "disabled"。
  • 搭配 groupPolicy = "allowlist" 時：
    • channels.zalouser.groups 的鍵應為穩定的群組 ID；只有啟用 channels.zalouser.dangerouslyAllowNameMatching: true 時，才會在啟動時將名稱解析為 ID。
    • channels.zalouser.groupAllowFrom 控制允許群組中的哪些傳送者可以觸發機器人；可使用 accessGroup:<name> 參照靜態傳送者存取群組。
  • 設定精靈可以提示輸入群組允許清單。
  • 群組允許清單預設只依 ID 比對。除非啟用 channels.zalouser.dangerouslyAllowNameMatching: true，否則授權時會忽略未解析的名稱。
  • channels.zalouser.dangerouslyAllowNameMatching: true 是緊急相容模式，會重新啟用可變動的啟動時名稱解析，以及執行階段群組名稱比對。
  • 對一般群組訊息而言，groupAllowFrom 不會退回使用 allowFrom：若允許清單中的群組將其留空，該群組會對任何傳送者開放。已授權的控制命令（例如 /new）是例外；當 groupAllowFrom 為空時，命令傳送者檢查會退回使用 allowFrom。

範例：

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

群組提及閘控

  • channels.zalouser.groups.<group>.requireMention 控制群組回覆是否必須提及機器人。
  • 解析順序：群組 ID -> group:<id> 別名 -> 群組名稱／slug（以名稱為基礎的候選項目僅在 dangerouslyAllowNameMatching: true 時適用）-> * -> 預設值（true）。
  • 同時適用於允許清單群組及開放群組模式。
  • 引用機器人訊息會視為隱含提及，並啟用群組處理。
  • 已授權的控制命令（例如 /new）可以略過提及閘控。
  • 如果群組訊息因需要提及而被略過，OpenClaw 會將其儲存為待處理群組記錄，並在下一則處理的群組訊息中納入該訊息。
  • 群組記錄限制：依序使用 channels.zalouser.historyLimit、messages.groupChat.historyLimit，最後退回使用 50。

範例：

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

多帳號

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

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

環境變數

也可以透過環境變數選取設定檔：

變數 用途
ZALOUSER_PROFILE 當頻道或帳號設定中未設定 profile 時使用的設定檔名稱。
ZCA_PROFILE 舊版備援，僅在未設定 ZALOUSER_PROFILE 時使用。

設定檔名稱用於選取 OpenClaw 狀態中已儲存的 Zalo 登入認證資訊。解析順序：

  1. 設定中明確指定的 profile。
  2. ZALOUSER_PROFILE。
  3. ZCA_PROFILE。
  4. 非預設帳號使用帳號 ID，預設帳號則使用 default。

對於多帳號設定，建議在設定中為每個帳號指定 profile，避免單一環境變數導致多個帳號共用同一個登入工作階段。

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

  • OpenClaw 會在分派回覆前傳送輸入狀態事件（盡力而為）。
  • 頻道動作中的 zalouser 支援訊息表情回應動作 react。
    • 使用 remove: true 從訊息移除特定的表情回應 emoji。
    • 表情回應語意：表情回應
  • 對於包含事件中繼資料的傳入訊息，OpenClaw 會傳送已送達及已查看確認（盡力而為）。

疑難排解

登入狀態無法保留：

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

允許清單／群組名稱無法解析：

  • 在 allowFrom/groupAllowFrom 中使用數字 ID，並在 groups 中使用穩定的群組 ID。如果確實需要使用完全相符的好友／群組名稱，請啟用 channels.zalouser.dangerouslyAllowNameMatching: true。

從舊版外部 zca/命令列介面式設定升級：

  • 移除任何依賴外部 zca 程序的假設；頻道現在完全透過 zca-js 在程序內執行，不需要外部命令列介面執行檔。

相關內容

Was this useful?
On this page

On this page