Zalo pribadi

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

Instalasi

Zalo Personal adalah plugin eksternal resmi yang 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 kanal:

{  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 itu

• Berjalan sepenuhnya di 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" ketika API Bot Zalo tidak tersedia.

Penamaan

ID kanal adalah zalouser untuk memperjelas bahwa integrasi ini mengotomatiskan akun pengguna Zalo pribadi (tidak resmi). zalo dicadangkan untuk kemungkinan 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 dipecah menjadi bagian-bagian sepanjang 2.000 karakter (batas klien Zalo).
• Streaming tidak didukung.

Kontrol akses (DM)

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

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

Jika nama mentah tetap ada dalam konfigurasi, proses awal hanya menetapkannya ketika channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan. Tanpa keikutsertaan eksplisit tersebut, pemeriksaan pengirim saat runtime hanya berdasarkan 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 harus berupa ID grup yang stabil; nama hanya ditetapkan ke ID saat proses awal 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 dirujuk dengan accessGroup:<name>.
• Wisaya konfigurasi dapat meminta daftar izin grup.
• Pencocokan daftar izin grup secara default hanya berdasarkan ID. Nama yang tidak dapat ditetapkan diabaikan untuk autentikasi kecuali channels.zalouser.dangerouslyAllowNameMatching: true diaktifkan.
• channels.zalouser.dangerouslyAllowNameMatching: true adalah mode kompatibilitas darurat yang mengaktifkan kembali penetapan nama yang dapat berubah saat proses awal dan pencocokan nama grup saat runtime.
• groupAllowFrom tidak beralih menggunakan allowFrom untuk pesan grup biasa: membiarkannya kosong pada grup dalam daftar izin akan membuka grup tersebut bagi semua pengirim. Perintah kontrol yang diotorisasi (misalnya /new) merupakan pengecualian; pemeriksaan pengirim perintah akan beralih menggunakan allowFrom ketika groupAllowFrom kosong.

Contoh:

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

Pembatasan berdasarkan penyebutan dalam grup

• channels.zalouser.groups.<group>.requireMention mengontrol apakah balasan grup memerlukan penyebutan.
• Urutan penetapan: ID grup -> alias group:<id> -> nama/slug grup (kandidat berbasis nama hanya berlaku ketika dangerouslyAllowNameMatching: true) -> * -> default (true).
• Berlaku untuk grup dalam daftar izin maupun mode grup terbuka.
• Mengutip pesan bot dihitung sebagai penyebutan implisit untuk aktivasi grup.
• Perintah kontrol yang diotorisasi (misalnya /new) dapat melewati pembatasan berdasarkan penyebutan.
• Ketika 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, kemudian messages.groupChat.historyLimit, lalu nilai cadangan 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 masuk Zalo yang disimpan dalam status OpenClaw. Urutan penetapan:

1. profile eksplisit dalam konfigurasi.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. ID akun untuk akun nondefault, 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 masuk yang sama.

Pengetikan, reaksi, dan konfirmasi pengiriman

• OpenClaw mengirim peristiwa pengetikan sebelum mengirimkan balasan (upaya terbaik).
• Tindakan reaksi pesan react didukung untuk zalouser dalam tindakan kanal.
  • 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

Sesi masuk tidak bertahan:

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

Nama daftar izin/grup tidak dapat ditetapkan:

• Gunakan ID numerik dalam allowFrom/groupAllowFrom dan ID grup yang 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 semua asumsi tentang proses zca eksternal; kanal kini berjalan sepenuhnya di dalam proses melalui zca-js, tanpa biner CLI eksternal.

Terkait

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