Zalo 個人版

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

# 內建 Plugin

Zalo Personal 在目前的 OpenClaw 發行版本中隨附為內建 Plugin，因此一般 套件化建置不需要另外安裝。

如果你使用的是較舊的建置，或是不包含 Zalo Personal 的自訂安裝， 請直接安裝 npm 套件：

• 透過 CLI 安裝：openclaw plugins install @openclaw/zalouser
• 釘選版本：openclaw plugins install @openclaw/[email protected]
• 或從原始碼 checkout 安裝：openclaw plugins install ./path/to/local/zalouser-plugin
• 詳細資訊：Plugins

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

# 快速設定（初學者）

1. 確認 Zalo Personal Plugin 可用。
   • 目前的套件化 OpenClaw 發行版本已內建它。
   • 較舊/自訂安裝可使用上方命令手動加入。
2. 登入（QR，在 Gateway 機器上）：
   • openclaw channels login --channel zalouser
   • 使用 Zalo 行動應用程式掃描 QR code。
3. 啟用頻道：

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

4. 重新啟動 Gateway（或完成設定）。
5. DM 存取預設使用配對；第一次聯絡時核准配對代碼。

# 它是什麼

• 完全透過 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 用戶端限制）。
• 預設會封鎖串流。

# 存取控制（DM）

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

channels.zalouser.allowFrom 應使用穩定的 Zalo 使用者 ID。在互動式設定期間，輸入的名稱可使用 Plugin 的程序內聯絡人查詢解析為 ID。

如果原始名稱保留在設定中，啟動時只會在啟用 channels.zalouser.dangerouslyAllowNameMatching: true 時解析它。若未選擇加入，執行期間的傳送者檢查僅依 ID 進行，原始名稱會在授權時被忽略。

透過以下方式核准：

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

# 群組存取（可選）

• 預設：channels.zalouser.groupPolicy = "open"（允許群組）。未設定時，使用 channels.defaults.groupPolicy 覆寫預設值。
• 使用以下設定限制為 allowlist：
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups（key 應為穩定的群組 ID；只有在啟用 channels.zalouser.dangerouslyAllowNameMatching: true 時，名稱才會在啟動時解析為 ID）
  • channels.zalouser.groupAllowFrom（控制允許群組中的哪些傳送者可以觸發 bot）
• 封鎖所有群組：channels.zalouser.groupPolicy = "disabled"。
• 設定精靈可提示輸入群組 allowlist。
• 啟動時，OpenClaw 只有在啟用 channels.zalouser.dangerouslyAllowNameMatching: true 時，才會將 allowlist 中的群組/使用者名稱解析為 ID 並記錄對應關係。
• 群組 allowlist 比對預設僅依 ID 進行。除非啟用 channels.zalouser.dangerouslyAllowNameMatching: true，否則未解析的名稱會在授權時被忽略。
• channels.zalouser.dangerouslyAllowNameMatching: true 是應急相容模式，會重新啟用可變的啟動名稱解析與執行期間群組名稱比對。
• 如果未設定 groupAllowFrom，執行期間會回退使用 allowFrom 進行群組傳送者檢查。
• 傳送者檢查同時適用於一般群組訊息和控制命令（例如 /new）。

範例：

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

# 群組提及門檻

• channels.zalouser.groups.<group>.requireMention 控制群組回覆是否需要提及。
• 解析順序：精確群組 id/名稱 -> 正規化群組 slug -> * -> 預設（true）。
• 這同時適用於列入 allowlist 的群組和開放群組模式。
• 引用 bot 訊息會視為群組啟用的隱含提及。
• 已授權的控制命令（例如 /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 profile。範例：

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

# 輸入中、回應和送達確認

• OpenClaw 會在發送回覆前傳送輸入中事件（盡力而為）。
• 訊息回應動作 react 在頻道動作中支援 zalouser。
  • 使用 remove: true 從訊息移除特定回應 emoji。
  • 回應語義：Reactions
• 對於包含事件中繼資料的傳入訊息，OpenClaw 會傳送已送達 + 已讀確認（盡力而為）。

# 疑難排解

登入沒有保留：

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

Allowlist/群組名稱未解析：

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

從舊的 CLI 型設定升級：

• 移除任何舊的外部 zca 程序假設。
• 此頻道現在完全在 OpenClaw 中執行，不需要外部 CLI 二進位檔。

# 相關

• 頻道概覽 — 所有支援的頻道
• 配對 — DM 驗證與配對流程
• 群組 — 群組聊天行為與提及門檻
• 頻道路由 — 訊息的工作階段路由
• Security — 存取模型與強化