WhatsApp

Status: siap produksi melalui WhatsApp Web (Baileys). Gateway mengelola sesi yang ditautkan; tidak ada kanal WhatsApp Twilio terpisah.

Instalasi

openclaw onboard dan openclaw channels add --channel whatsapp meminta Anda menginstal plugin saat pertama kali memilihnya; openclaw channels login --channel whatsapp menawarkan alur instalasi yang sama jika plugin belum tersedia. Checkout pengembangan menggunakan jalur plugin lokal; instalasi stabil/beta terlebih dahulu menginstal @openclaw/whatsapp dari ClawHub, dengan npm sebagai cadangan. Runtime WhatsApp dikirimkan di luar paket npm inti OpenClaw, sehingga dependensi runtime-nya tetap berada di plugin eksternal. Instalasi manual:

openclaw plugins install clawhub:@openclaw/whatsapp

Gunakan paket npm tanpa prefiks (@openclaw/whatsapp) hanya sebagai cadangan registri; sematkan versi yang tepat hanya untuk instalasi yang dapat direproduksi.

Penyiapan cepat

{channels: {whatsapp: {  dmPolicy: "pairing",  allowFrom: ["+15551234567"],  groupPolicy: "allowlist",  groupAllowFrom: ["+15551234567"],},},}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Pola penerapan

{  channels: {    whatsapp: {      dmPolicy: "allowlist",      allowFrom: ["+15551234567"],    },  },}

Model runtime

• Gateway mengelola soket WhatsApp dan perulangan penyambungan ulang.
• Pengawas memantau dua sinyal secara independen: aktivitas transportasi mentah WhatsApp Web dan aktivitas pesan aplikasi. Sesi yang sepi tetapi masih terhubung tidak dimulai ulang hanya karena tidak ada pesan yang baru-baru ini tiba; penyambungan ulang dipaksakan hanya ketika frame transportasi berhenti tiba selama jangka waktu internal tetap (tidak dapat dikonfigurasi pengguna) atau pesan aplikasi tetap tidak ada melampaui 4x batas waktu pesan normal. Tepat setelah penyambungan ulang untuk sesi yang baru-baru ini aktif, jangka waktu pertama tersebut menggunakan batas waktu pesan normal yang lebih pendek, bukan jangka waktu 4x. OpenClaw dapat membalas otomatis pesan luring yang dikirimkan lebih awal oleh Baileys selama penyambungan ulang tersebut, dengan batas sesuai masa berlaku deduplikasi ID pesan masuk; proses awal pertama tetap menggunakan perlindungan singkat terhadap riwayat usang.
• Pengaturan waktu soket Baileys dinyatakan secara eksplisit dalam web.whatsapp.*: keepAliveIntervalMs (interval ping aplikasi), connectTimeoutMs (batas waktu handshake pembukaan), defaultQueryTimeoutMs (waktu tunggu kueri Baileys, serta batas waktu pengiriman/kehadiran keluar dan tanda terima baca masuk OpenClaw).
• Pengiriman keluar memerlukan listener WhatsApp aktif untuk akun tujuan; jika tidak, pengiriman langsung gagal.
• Pengiriman grup melampirkan metadata penyebutan native untuk token @+<digits> dan @<digits> (dalam teks dan keterangan media) ketika token cocok dengan metadata peserta saat ini, termasuk grup berbasis LID.
• Obrolan status dan siaran (@status, @broadcast) diabaikan.
• Obrolan langsung menggunakan aturan sesi DM (session.dmScope; nilai default main menggabungkan DM ke dalam sesi utama agen). Sesi grup diisolasi per JID (agent:<agentId>:whatsapp:group:<jid>).
• Kanal/Buletin WhatsApp dapat menjadi target keluar eksplisit melalui JID native @newsletter, menggunakan metadata sesi kanal (agent:<agentId>:whatsapp:channel:<jid>) alih-alih semantik DM.
• Transportasi WhatsApp Web mematuhi variabel lingkungan proksi standar pada host Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, beserta varian huruf kecil). Utamakan konfigurasi proksi tingkat host daripada pengaturan per kanal.
• Saat messages.removeAckAfterReply diaktifkan, OpenClaw menghapus reaksi tanda terima setelah balasan yang terlihat berhasil dikirimkan.

Hubungi pemohon saat ini dengan MeowCaller (eksperimental)

Plugin dapat menyediakan whatsapp_call dalam giliran agen yang berasal dari WhatsApp. Fitur ini menggunakan MeowCaller untuk melakukan panggilan suara WhatsApp kepada pemohon berwenang saat ini dan memutar pesan TTS OpenClaw setelah panggilan dijawab. Alat ini tidak memiliki parameter nomor tujuan, sehingga perintah tidak dapat mengalihkan panggilan. Dinonaktifkan secara default.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Batasan: hanya panggilan audio keluar satu-ke-satu, tanpa nomor tujuan arbitrer, tanpa autentikasi bersama dengan koneksi obrolan, tanpa panggilan ke diri sendiri dari mode nomor pribadi atau obrolan dengan diri sendiri, audio hasil sintesis dibatasi hingga 60 detik, tidak ada tanda terima keterdengaran di sisi perangkat selain penyelesaian tahap jawaban/pemutaran/penutupan panggilan MeowCaller, dan OpenClaw menghentikan proses pendamping setelah jangka waktu terbatas 115–175 detik (mencakup fase koneksi, jawaban, pemutaran, dan penghentian MeowCaller).

Perintah persetujuan

WhatsApp dapat merender perintah persetujuan eksekusi dan plugin sebagai reaksi 👍/👎, yang dikendalikan oleh konfigurasi penerusan persetujuan tingkat atas:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec dan approvals.plugin bersifat independen; mengaktifkan WhatsApp sebagai kanal hanya menautkan transportasi dan tidak mengirimkan apa pun kecuali kelompok persetujuan yang sesuai diaktifkan dan dirutekan ke sana. Mode sesi mengirimkan persetujuan emoji native hanya untuk persetujuan yang berasal dari WhatsApp. Mode target menggunakan pipeline penerusan bersama untuk target eksplisit dan tidak membuat fan-out DM pemberi persetujuan secara terpisah.

Reaksi persetujuan WhatsApp memerlukan pemberi persetujuan eksplisit dalam allowFrom (atau "*"). defaultTo menetapkan target pesan default biasa, bukan daftar pemberi persetujuan. Perintah manual /approve tetap melewati jalur otorisasi pengirim WhatsApp normal sebelum penyelesaian persetujuan.

Hook Plugin dan privasi

Pesan WhatsApp masuk dapat memuat konten pribadi, nomor telepon, pengenal grup, nama pengirim, dan bidang korelasi sesi. WhatsApp tidak menyiarkan payload hook message_received masuk kepada plugin kecuali Anda mengaktifkannya:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Batasi pengaktifan ke satu akun di channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Aktifkan ini hanya untuk plugin yang Anda percayai untuk mengakses konten dan pengenal WhatsApp masuk.

Kontrol akses dan aktivasi

Binding ACP yang dikonfigurasi

WhatsApp mendukung binding ACP persisten melalui bindings[] tingkat atas:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

Percakapan langsung dicocokkan dengan nomor E.164; grup dicocokkan dengan JID grup WhatsApp. Daftar izin grup, kebijakan pengirim, dan gerbang penyebutan/aktivasi dijalankan sebelum OpenClaw memastikan sesi ACP yang terikat tersedia. Binding yang cocok memiliki rute tersebut—grup siaran tidak menyebarkan giliran itu ke sesi WhatsApp biasa.

Perilaku nomor pribadi dan percakapan dengan diri sendiri

Ketika nomor sendiri yang ditautkan juga terdapat dalam allowFrom, pengaman percakapan dengan diri sendiri diaktifkan: melewati tanda terima telah dibaca untuk giliran percakapan dengan diri sendiri, mengabaikan perilaku pemicu otomatis JID penyebutan yang akan memanggil diri Anda sendiri, dan secara default memberi awalan balasan [{identity.name}] (atau [openclaw]) ketika messages.responsePrefix tidak ditetapkan.

Normalisasi pesan dan konteks

[Replying to <sender> id:<stanzaId>]<quoted body or media placeholder>[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

Pengiriman, pemenggalan, dan media

Pengutipan balasan

channels.whatsapp.replyToMode mengontrol pengutipan balasan native (balasan keluar secara jelas mengutip pesan masuk):

Penggantian per akun: channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

Tingkat reaksi

channels.whatsapp.reactionLevel mengontrol seberapa luas agen menggunakan reaksi emoji:

Penggantian per akun: channels.whatsapp.accounts.<id>.reactionLevel.

{ channels: { whatsapp: { reactionLevel: "ack" } } }

Reaksi pengakuan

channels.whatsapp.ackReaction mengirim reaksi langsung saat pesan masuk diterima, dengan gerbang reactionLevel (ditekan ketika "off"):

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // always | mentions | never      },    },  },}

Catatan: dikirim segera setelah pesan masuk diterima (sebelum balasan); jika ackReaction tersedia tanpa emoji, WhatsApp menggunakan emoji identitas agen yang dirutekan dengan fallback ke "👀" (hilangkan ackReaction atau tetapkan emoji: "" agar tidak ada pengakuan); kegagalan dicatat dalam log tetapi tidak memblokir pengiriman balasan; mode grup mentions hanya bereaksi pada giliran yang dipicu penyebutan, sedangkan aktivasi grup always melewati pemeriksaan tersebut; WhatsApp hanya menggunakan channels.whatsapp.ackReaction (messages.ackReaction lama tidak berlaku di sini).

Reaksi status siklus hidup

Tetapkan messages.statusReactions.enabled: true agar WhatsApp mengganti reaksi pengakuan selama suatu giliran, alih-alih membiarkan emoji tanda terima statis, dengan berputar melalui status seperti dalam antrean, berpikir, aktivitas alat, Compaction, selesai, dan kesalahan:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Catatan: channels.whatsapp.ackReaction tetap mengontrol kelayakan untuk pesan langsung dan grup; status dalam antrean menggunakan emoji efektif yang sama seperti reaksi pengakuan biasa; WhatsApp memiliki satu slot reaksi bot per pesan, sehingga pembaruan siklus hidup mengganti reaksi saat ini di tempat; messages.removeAckAfterReply: true menghapus reaksi status akhir setelah durasi penahanan selesai/kesalahan yang dikonfigurasi; kategori emoji alat mencakup tool, coding, web, deploy, build, dan concierge.

Multi-akun dan kredensial

Alat, tindakan, dan penulisan konfigurasi

• Dukungan alat agen mencakup tindakan reaksi WhatsApp (react).
• Gerbang tindakan: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (tindakan yang sudah ada secara default bernilai true), channels.whatsapp.actions.calls (default false, lihat MeowCaller di atas).
• Penulisan konfigurasi yang dimulai oleh kanal diaktifkan secara default; nonaktifkan melalui channels.whatsapp.configWrites: false.

Pemecahan masalah

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Prompt sistem

WhatsApp mendukung prompt sistem bergaya Telegram untuk grup dan percakapan langsung melalui peta groups dan direct.

Resolusi untuk pesan grup: peta groups yang efektif ditentukan terlebih dahulu — jika akun mendefinisikan kunci groups sendiri dalam bentuk apa pun, kunci tersebut sepenuhnya menggantikan peta groups akar (tanpa penggabungan mendalam). Pencarian prompt kemudian dijalankan pada satu peta hasil tersebut:

1. Prompt khusus grup (groups["<groupId>"].systemPrompt): digunakan saat entri grup tersedia dan kunci systemPrompt-nya telah ditentukan. String kosong ("") menekan karakter pengganti dan tidak menerapkan prompt.
2. Prompt karakter pengganti grup (groups["*"].systemPrompt): digunakan saat entri grup tertentu tidak tersedia, atau tersedia tanpa kunci systemPrompt.

Resolusi untuk pesan langsung mengikuti pola yang sama terhadap peta direct dan direct["*"].

Perbedaan dari Telegram: Telegram menekan groups akar untuk setiap akun dalam penyiapan multiakun (bahkan akun yang tidak memiliki groups sendiri) guna mencegah bot menerima pesan grup dari grup yang bukan anggotanya. WhatsApp tidak menerapkan perlindungan tersebut — groups/direct akar diwarisi oleh setiap akun tanpa penggantian sendiri, berapa pun jumlah akunnya. Dalam penyiapan WhatsApp multiakun, tentukan peta lengkap secara eksplisit di bawah setiap akun jika Anda menginginkan prompt per akun.

Perilaku penting:

• channels.whatsapp.groups merupakan peta konfigurasi per grup sekaligus daftar grup yang diizinkan pada tingkat percakapan. Pada cakupan akar maupun akun, groups["*"] berarti "semua grup diizinkan" untuk cakupan tersebut.
• Hanya tambahkan systemPrompt karakter pengganti jika Anda memang ingin cakupan tersebut mengizinkan semua grup. Agar hanya sekumpulan ID grup tertentu yang memenuhi syarat, ulangi prompt pada setiap entri yang diizinkan secara eksplisit alih-alih menggunakan groups["*"].
• Penerimaan grup dan otorisasi pengirim merupakan pemeriksaan terpisah. groups["*"] memperluas grup yang dapat mencapai penanganan grup; ini tidak mengotorisasi setiap pengirim dalam grup tersebut — hal itu tetap dikendalikan oleh groupPolicy/groupAllowFrom.
• channels.whatsapp.direct tidak memiliki efek samping serupa untuk pesan langsung: direct["*"] hanya menyediakan konfigurasi default setelah pesan langsung diizinkan oleh dmPolicy bersama allowFrom atau aturan penyimpanan pemasangan.

Contoh:

{  channels: {    whatsapp: {      groups: {        // Gunakan hanya jika semua grup harus diizinkan pada cakupan akar.        // Berlaku untuk semua akun yang tidak menentukan peta groups sendiri.        "*": { systemPrompt: "Prompt default untuk semua grup." },      },      direct: {        // Berlaku untuk semua akun yang tidak menentukan peta direct sendiri.        "*": { systemPrompt: "Prompt default untuk semua percakapan langsung." },      },      accounts: {        work: {          groups: {            // Akun ini menentukan groups sendiri, sehingga groups akar sepenuhnya            // diganti. Untuk mempertahankan karakter pengganti, tentukan "*" secara eksplisit di sini juga.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Fokus pada manajemen proyek.",            },            // Gunakan hanya jika semua grup harus diizinkan dalam akun ini.            "*": { systemPrompt: "Prompt default untuk grup kerja." },          },          direct: {            // Akun ini menentukan peta direct sendiri, sehingga entri direct akar            // sepenuhnya diganti. Untuk mempertahankan karakter pengganti, tentukan "*" secara eksplisit di sini juga.            "+15551234567": { systemPrompt: "Prompt untuk percakapan langsung kerja tertentu." },            "*": { systemPrompt: "Prompt default untuk percakapan langsung kerja." },          },        },      },    },  },}

Penunjuk referensi konfigurasi

Referensi utama: Referensi konfigurasi - WhatsApp

Terkait

• Pemasangan
• Grup
• Keamanan
• Perutean kanal
• Perutean multiagen
• Pemecahan masalah