Zalo Personal (không chính thức)

Trạng thái: thử nghiệm. Tích hợp này tự động hóa tài khoản Zalo cá nhân qua zca-cli.

Cảnh báo: Đây là tích hợp không chính thức và có thể dẫn đến tài khoản bị khóa/cấm. Các bạn tự chịu trách nhiệm khi sử dụng nhé.

Yêu cầu Plugin

Zalo Personal được cung cấp dưới dạng plugin và không đi kèm với bản cài đặt gốc.

  • Cài qua CLI: openclaw plugins install @openclaw/zalouser
  • Hoặc từ source code: openclaw plugins install ./extensions/zalouser
  • Chi tiết: Plugins

Yêu cầu: zca-cli

Máy chạy Gateway phải có file thực thi zca trong PATH.

  • Kiểm tra: zca --version
  • Nếu chưa có, cài zca-cli (xem extensions/zalouser/README.md hoặc tài liệu chính thức của zca-cli).

Cài đặt nhanh (cho người mới)

  1. Cài plugin (xem phần trên).
  2. Đăng nhập (QR, trên máy chạy Gateway):
    • openclaw channels login --channel zalouser
    • Quét mã QR trong terminal bằng app Zalo trên điện thoại.
  3. Bật channel:
{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}
  1. Khởi động lại Gateway (hoặc hoàn tất onboarding).
  2. Truy cập DM mặc định dùng pairing; phê duyệt mã pairing khi có liên hệ đầu tiên.

Cơ chế hoạt động

  • Dùng zca listen để nhận tin nhắn đến.
  • Dùng zca msg ... để gửi phản hồi (text/media/link).
  • Được thiết kế cho trường hợp “tài khoản cá nhân” khi Zalo Bot API không khả dụng.

Đặt tên

Channel id là zalouser để làm rõ đây là tự động hóa tài khoản Zalo cá nhân (không chính thức). Mình giữ tên zalo cho tích hợp Zalo API chính thức trong tương lai.

Tìm ID (directory)

Dùng directory CLI để khám phá peers/groups và ID của chúng:

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

Giới hạn

  • Tin nhắn gửi đi được chia nhỏ thành ~2000 ký tự (giới hạn của Zalo client).
  • Streaming bị chặn mặc định.

Kiểm soát truy cập (DMs)

channels.zalouser.dmPolicy hỗ trợ: pairing | allowlist | open | disabled (mặc định: pairing). channels.zalouser.allowFrom chấp nhận user ID hoặc tên. Wizard sẽ chuyển tên thành ID qua zca friend find khi có thể.

Phê duyệt qua:

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

Truy cập nhóm (tùy chọn)

  • Mặc định: channels.zalouser.groupPolicy = "open" (cho phép nhóm). Dùng channels.defaults.groupPolicy để ghi đè mặc định khi chưa thiết lập.
  • Giới hạn bằng allowlist:
    • channels.zalouser.groupPolicy = "allowlist"
    • channels.zalouser.groups (key là group ID hoặc tên)
  • Chặn tất cả nhóm: channels.zalouser.groupPolicy = "disabled".
  • Configure wizard có thể nhắc nhập allowlist nhóm.
  • Khi khởi động, OpenClaw chuyển tên nhóm/user trong allowlist thành ID và ghi log mapping; các mục không tìm thấy sẽ giữ nguyên.

Ví dụ:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

Đa tài khoản

Các tài khoản ánh xạ tới zca profiles. Ví dụ:

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

Troubleshooting

Không tìm thấy zca:

  • Cài zca-cli và đảm bảo nó có trong PATH của Gateway process.

Đăng nhập không giữ được:

  • openclaw channels status --probe
  • Đăng nhập lại: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser