Zalo pribadi

Status: eksperimental. Integrasi ini mengotomatiskan akun Zalo pribadi melalui zca-js native, dalam proses, tanpa biner CLI eksternal.

Instalasi

Zalo Personal adalah plugin eksternal resmi, tidak disertakan dalam inti. Instal sebelum digunakan:

openclaw plugins install @openclaw/zalouser

• Sematkan versi: openclaw plugins install @openclaw/zalouser@<version>
• Dari checkout sumber: openclaw plugins install ./path/to/local/zalouser-plugin
• Detail: Plugin

Penyiapan cepat

1. Instal plugin (di atas).
2. Masuk (QR, pada mesin Gateway):
   • openclaw channels login --channel zalouser
   • Pindai kode QR dengan aplikasi seluler Zalo.
3. Aktifkan saluran:

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

4. Mulai ulang Gateway (atau selesaikan penyiapan).
5. Akses DM secara default menggunakan pemasangan; setujui kode pemasangan pada kontak pertama.

Apa ini

• Berjalan sepenuhnya dalam proses melalui pustaka zca-js (tanpa biner eksternal zca/openzca).
• Menggunakan pemantau peristiwa native (message, error) untuk menerima pesan masuk.
• Mengirim balasan secara langsung melalui API JS (teks/media/tautan).
• Dirancang untuk kasus penggunaan "akun pribadi" saat API Bot Zalo tidak tersedia.

Penamaan

ID saluran adalah zalouser untuk menegaskan bahwa ini mengotomatiskan akun pengguna Zalo pribadi (tidak resmi). zalo dicadangkan untuk potensi integrasi API Zalo resmi pada masa mendatang.

Menemukan ID (direktori)

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

Batasan

• Teks keluar dibagi menjadi potongan 2000 karakter (batas klien Zalo).
• Streaming tidak didukung.
• ID pesan masuk yang telah selesai disimpan selama 30 hari, dibatasi hingga 1000 entri terbaru per akun.

Ketahanan pesan masuk

OpenClaw menyimpan setiap callback pesan mentah zca-js sebelum memprosesnya. Pesan tertunda dilanjutkan dari antrean akun setelah Gateway dimulai ulang, dan pemrosesan tetap diserialkan per percakapan langsung atau grup.

Pemantau soket zca-js tidak menyediakan konfirmasi pengiriman atau secara otomatis memutar ulang pesan lama setelah tersambung kembali. Oleh karena itu, antrean tahan lama melindungi jendela kegagalan lokal setelah callback mencapai OpenClaw; antrean ini tidak dapat memulihkan pesan yang tidak pernah dikirimkan oleh soket. Tombstone pemutaran ulang terutama merupakan perlindungan terhadap callback berulang dengan ID pesan Zalo yang sama.

Kontrol akses (DM)

channels.zalouser.dmPolicy: pairing | allowlist | open | disabled (default: pairing).

channels.zalouser.allowFrom sebaiknya menggunakan ID pengguna Zalo yang stabil. Ini juga dapat merujuk ke grup akses pengirim statis (accessGroup:<name>). Selama penyiapan interaktif, nama yang dimasukkan dapat diubah menjadi ID menggunakan pencarian kontak dalam proses milik plugin.

Jika nama mentah tetap ada dalam konfigurasi, saat mulai nama tersebut hanya diubah jika channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan. Tanpa persetujuan eksplisit tersebut, pemeriksaan pengirim saat runtime hanya menggunakan ID dan nama mentah diabaikan untuk otorisasi.

Setujui melalui:

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

Akses grup (opsional)

• Default: channels.zalouser.groupPolicy = "allowlist" (grup memerlukan entri daftar izin eksplisit).
• Buka semua grup: channels.zalouser.groupPolicy = "open".
• Blokir semua grup: channels.zalouser.groupPolicy = "disabled".
• Dengan groupPolicy = "allowlist":
  • Kunci channels.zalouser.groups sebaiknya berupa ID grup yang stabil; nama diubah menjadi ID saat mulai hanya jika channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan.
  • channels.zalouser.groupAllowFrom mengontrol pengirim mana dalam grup yang diizinkan yang dapat memicu bot; grup akses pengirim statis dapat dirujuk dengan accessGroup:<name>.
• Wizard konfigurasi dapat meminta daftar izin grup.
• Pencocokan daftar izin grup secara default hanya menggunakan ID. Nama yang tidak dapat diubah diabaikan untuk autentikasi kecuali channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan.
• channels.zalouser.dangerouslyAllowNameMatching: true adalah mode kompatibilitas darurat yang mengaktifkan kembali pengubahan nama saat mulai yang dapat berubah dan pencocokan nama grup saat runtime.
• groupAllowFrom tidak menggunakan allowFrom sebagai fallback untuk pesan grup biasa: membiarkannya kosong pada grup dalam daftar izin akan membuka grup tersebut bagi pengirim mana pun. Perintah kontrol yang diotorisasi (misalnya /new) merupakan pengecualian; pemeriksaan pengirim perintah menggunakan allowFrom sebagai fallback saat groupAllowFrom kosong.

Contoh:

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

Pemfilteran berdasarkan penyebutan grup

• channels.zalouser.groups.<group>.requireMention mengontrol apakah balasan grup memerlukan penyebutan.
• Urutan resolusi: ID grup -> alias group:<id> -> nama/slug grup (kandidat berbasis nama hanya berlaku saat dangerouslyAllowNameMatching: true) -> * -> default (true).
• Berlaku baik untuk grup dalam daftar izin maupun mode grup terbuka.
• Mengutip pesan bot dianggap sebagai penyebutan implisit untuk aktivasi grup.
• Perintah kontrol yang diotorisasi (misalnya /new) dapat melewati pemfilteran berdasarkan penyebutan.
• Saat pesan grup dilewati karena penyebutan diwajibkan, OpenClaw menyimpannya sebagai riwayat grup tertunda dan menyertakannya pada pesan grup berikutnya yang diproses.
• Batas riwayat grup: channels.zalouser.historyLimit, lalu messages.groupChat.historyLimit, kemudian fallback 50.

Contoh:

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

Multiakun

Akun dipetakan ke profil zalouser dalam status OpenClaw. Contoh:

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

Variabel lingkungan

Pemilihan profil juga dapat berasal dari variabel lingkungan:

Nama profil memilih kredensial login Zalo yang tersimpan dalam status OpenClaw. Urutan resolusi:

1. profile eksplisit dalam konfigurasi.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. ID akun untuk akun non-default, atau default untuk akun default.

Untuk penyiapan multiakun, sebaiknya tetapkan profile pada setiap akun dalam konfigurasi agar satu variabel lingkungan tidak membuat beberapa akun berbagi sesi login yang sama.

Indikator pengetikan, reaksi, dan konfirmasi pengiriman

• OpenClaw mengirim peristiwa pengetikan sebelum mengirimkan balasan (upaya terbaik).
• Tindakan reaksi pesan react didukung untuk zalouser dalam tindakan saluran.
  • Gunakan remove: true untuk menghapus emoji reaksi tertentu dari pesan.
  • Semantik reaksi: Reaksi
• Untuk pesan masuk yang menyertakan metadata peristiwa, OpenClaw mengirim konfirmasi telah dikirim + telah dilihat (upaya terbaik).

Pemecahan masalah

Login tidak tersimpan:

• openclaw channels status --probe
• Masuk kembali: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Nama daftar izin/grup tidak dapat diubah:

• Gunakan ID numerik dalam allowFrom/groupAllowFrom dan ID grup stabil dalam groups. Jika Anda sengaja perlu menggunakan nama teman/grup yang persis, aktifkan channels.zalouser.dangerouslyAllowNameMatching: true.

Ditingkatkan dari penyiapan lama berbasis zca/CLI eksternal:

• Hapus asumsi apa pun tentang proses zca eksternal; saluran kini berjalan sepenuhnya dalam proses melalui zca-js, tanpa biner CLI eksternal.

Terkait

• Ikhtisar Saluran - semua saluran yang didukung
• Pemasangan - autentikasi DM dan alur pemasangan
• Grup - perilaku percakapan grup dan pemfilteran berdasarkan penyebutan
• Perutean Saluran - perutean sesi untuk pesan
• Keamanan - model akses dan penguatan