Zalo pribadi

Status: eksperimental. Integrasi ini mengotomatiskan akun Zalo pribadi melalui zca-js native di dalam OpenClaw.

Plugin bawaan

Zalo Personal dikirim sebagai Plugin bawaan dalam rilis OpenClaw saat ini, sehingga build paket normal tidak memerlukan instalasi terpisah.

Jika Anda menggunakan build lama atau instalasi kustom yang mengecualikan Zalo Personal, instal paket npm secara langsung:

• Instal melalui CLI: openclaw plugins install @openclaw/zalouser
• Versi yang dipatok: openclaw plugins install @openclaw/zalouser@2026.5.2
• Atau dari checkout sumber: openclaw plugins install ./path/to/local/zalouser-plugin
• Detail: Plugin

Tidak diperlukan binary CLI zca/openzca eksternal.

Penyiapan cepat (pemula)

1. Pastikan Plugin Zalo Personal tersedia.
   • Rilis OpenClaw berpaket saat ini sudah membundelnya.
   • Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Login (QR, pada mesin Gateway):
   • openclaw channels login --channel zalouser
   • Pindai kode QR dengan aplikasi seluler Zalo.
3. Aktifkan channel:

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

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

Apa ini

• Berjalan sepenuhnya di dalam proses melalui zca-js.
• Menggunakan listener peristiwa native untuk menerima pesan masuk.
• Mengirim balasan langsung melalui API JS (teks/media/tautan).
• Dirancang untuk kasus penggunaan "akun pribadi" ketika Zalo Bot API tidak tersedia.

Penamaan

ID channel adalah zalouser untuk memperjelas bahwa ini mengotomatiskan akun pengguna Zalo pribadi (tidak resmi). Kami mencadangkan zalo untuk kemungkinan integrasi Zalo API resmi di masa mendatang.

Menemukan ID (direktori)

Gunakan CLI direktori untuk menemukan peer/grup dan ID-nya:

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

Batasan

• Teks keluar dipecah menjadi sekitar 2000 karakter (batas klien Zalo).
• Streaming diblokir secara default.

Kontrol akses (DM)

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

channels.zalouser.allowFrom harus menggunakan ID pengguna Zalo yang stabil. Ini juga dapat mereferensikan grup akses pengirim statis (accessGroup:<name>). Selama penyiapan interaktif, nama yang dimasukkan dapat di-resolve menjadi ID menggunakan pencarian kontak dalam proses milik Plugin.

Jika nama mentah tetap ada di config, startup hanya me-resolve-nya ketika channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan. Tanpa opt-in tersebut, pemeriksaan pengirim runtime hanya berbasis 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 = "open" (grup diizinkan). Gunakan channels.defaults.groupPolicy untuk mengganti default saat belum disetel.
• Batasi ke daftar izin dengan:
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups (key harus berupa ID grup yang stabil; nama di-resolve menjadi ID saat startup hanya ketika channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan)
  • channels.zalouser.groupAllowFrom (mengontrol pengirim mana dalam grup yang diizinkan yang dapat memicu bot; grup akses pengirim statis dapat direferensikan dengan accessGroup:<name>)
• Blokir semua grup: channels.zalouser.groupPolicy = "disabled".
• Wizard konfigurasi dapat meminta daftar izin grup.
• Saat startup, OpenClaw me-resolve nama grup/pengguna dalam daftar izin menjadi ID dan mencatat pemetaannya hanya ketika channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan.
• Pencocokan daftar izin grup secara default hanya berbasis ID. Nama yang tidak ter-resolve diabaikan untuk auth kecuali channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan.
• channels.zalouser.dangerouslyAllowNameMatching: true adalah mode kompatibilitas darurat yang mengaktifkan kembali resolusi nama startup yang dapat berubah dan pencocokan nama grup runtime.
• Jika groupAllowFrom tidak disetel, runtime melakukan fallback ke allowFrom untuk pemeriksaan pengirim grup.
• Pemeriksaan pengirim berlaku untuk pesan grup normal maupun perintah kontrol (misalnya /new, /reset).

Contoh:

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

Gate mention grup

• channels.zalouser.groups.<group>.requireMention mengontrol apakah balasan grup memerlukan mention.
• Urutan resolusi: id/nama grup persis -> slug grup yang dinormalisasi -> * -> default (true).
• Ini berlaku baik untuk grup dalam daftar izin maupun mode grup terbuka.
• Mengutip pesan bot dihitung sebagai mention implisit untuk aktivasi grup.
• Perintah kontrol yang diotorisasi (misalnya /new) dapat melewati gate mention.
• Ketika pesan grup dilewati karena mention diperlukan, OpenClaw menyimpannya sebagai riwayat grup tertunda dan menyertakannya pada pesan grup berikutnya yang diproses.
• Batas riwayat grup secara default adalah messages.groupChat.historyLimit (fallback 50). Anda dapat menimpanya per akun dengan channels.zalouser.historyLimit.

Contoh:

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

Multi-akun

Akun dipetakan ke profil zalouser dalam state OpenClaw. Contoh:

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

Variabel lingkungan

Plugin Zalo Personal juga dapat membaca pemilihan profil dari variabel lingkungan:

• ZALOUSER_PROFILE: nama profil yang digunakan ketika tidak ada profile yang disetel dalam config channel atau akun.
• ZCA_PROFILE: nama profil fallback legacy, digunakan hanya ketika ZALOUSER_PROFILE tidak disetel.

Nama profil memilih kredensial login Zalo yang tersimpan dalam state OpenClaw. Urutan resolusinya adalah:

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

Untuk penyiapan multi-akun, sebaiknya setel profile pada setiap akun dalam config agar satu variabel lingkungan tidak membuat beberapa akun berbagi sesi login yang sama.

Pengetikan, reaksi, dan acknowledgement pengiriman

• OpenClaw mengirim peristiwa mengetik sebelum mengirim balasan (upaya terbaik).
• Aksi reaksi pesan react didukung untuk zalouser dalam aksi channel.
  • Gunakan remove: true untuk menghapus emoji reaksi tertentu dari sebuah pesan.
  • Semantik reaksi: Reaksi
• Untuk pesan masuk yang menyertakan metadata peristiwa, OpenClaw mengirim acknowledgement terkirim + terlihat (upaya terbaik).

Pemecahan masalah

Login tidak tersimpan:

• openclaw channels status --probe
• Login ulang: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Nama daftar izin/grup tidak ter-resolve:

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

Upgrade dari penyiapan lama berbasis CLI:

• Hapus asumsi proses zca eksternal lama apa pun.
• Channel sekarang berjalan sepenuhnya di OpenClaw tanpa binary CLI eksternal.

Terkait

• Ringkasan Channel — semua channel yang didukung
• Pairing — autentikasi DM dan alur pairing
• Grup — perilaku chat grup dan gate mention
• Routing Channel — routing sesi untuk pesan
• Keamanan — model akses dan hardening