WhatsApp

Status: siap produksi melalui WhatsApp Web (Baileys). Gateway mengelola sesi tertaut; tidak ada saluran Twilio WhatsApp terpisah.

Instalasi

openclaw onboard dan openclaw channels add --channel whatsapp meminta pemasangan plugin saat pertama kali Anda memilihnya; openclaw channels login --channel whatsapp menawarkan alur pemasangan yang sama jika plugin tidak tersedia. Checkout pengembangan menggunakan jalur plugin lokal; instalasi stabil/beta terlebih dahulu memasang @openclaw/whatsapp dari ClawHub, dengan npm sebagai fallback. 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 cakupan tambahan (@openclaw/whatsapp) hanya untuk fallback registri; sematkan versi persis 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 koneksi ulang.
• Watchdog melacak dua sinyal secara independen: aktivitas transportasi mentah WhatsApp Web dan aktivitas pesan aplikasi. Sesi yang senyap tetapi tetap terhubung tidak dimulai ulang hanya karena tidak ada pesan yang baru-baru ini tiba; koneksi ulang dipaksa hanya ketika frame transportasi berhenti tiba selama jangka waktu internal tetap (tidak dapat dikonfigurasi pengguna) atau pesan aplikasi tetap senyap melewati 4x waktu tunggu pesan normal. Tepat setelah koneksi ulang untuk sesi yang baru-baru ini aktif, jangka waktu pertama tersebut menggunakan waktu tunggu pesan normal yang lebih singkat, bukan jangka waktu 4x. OpenClaw dapat membalas otomatis pesan luring yang dikirim lebih awal oleh Baileys dalam koneksi ulang tersebut, dibatasi oleh masa berlaku deduplikasi ID pesan masuk; pengaktifan awal tetap menggunakan perlindungan singkat terhadap riwayat lama.
• Pengiriman keluar memerlukan listener WhatsApp aktif untuk akun tujuan; jika tidak, pengiriman segera gagal.
• Pengiriman grup melampirkan metadata sebutan native untuk token @+<digits> dan @<digits> (dalam teks dan keterangan media) ketika token cocok dengan metadata peserta saat ini, termasuk grup yang didukung LID.
• Obrolan status dan siaran (@status, @broadcast) diabaikan.
• Obrolan langsung menggunakan aturan sesi DM (session.dmScope; default main menggabungkan DM ke dalam sesi utama agen). Sesi grup diisolasi per JID (agent:<agentId>:whatsapp:group:<jid>).
• Saluran/Buletin WhatsApp dapat menjadi tujuan keluar eksplisit melalui JID native @newsletter, menggunakan metadata sesi saluran (agent:<agentId>:whatsapp:channel:<jid>), bukan 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 saluran.
• Dengan messages.removeAckAfterReply diaktifkan, OpenClaw menghapus reaksi tanda terima setelah balasan yang terlihat terkirim.

Hubungi pemohon saat ini dengan MeowCaller (eksperimental)

Plugin dapat mengekspos whatsapp_call dalam giliran agen yang berasal dari WhatsApp. Plugin ini menggunakan MeowCaller untuk melakukan panggilan suara WhatsApp kepada pemohon sah saat ini dan memutar pesan TTS OpenClaw setelah panggilan dijawab. Alat ini tidak memiliki parameter nomor tujuan, sehingga prompt 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 mandiri dari mode nomor pribadi/obrolan mandiri, audio hasil sintesis dibatasi hingga 60 detik, tanpa tanda terima keterdengaran di sisi handset selain penyelesaian jawab/pemutaran/tutup MeowCaller, dan OpenClaw menghentikan proses pendamping setelah jangka waktu terbatas 115-175 detik (mencakup fase koneksi, jawaban, pemutaran, dan penghentian MeowCaller).

Prompt persetujuan

WhatsApp dapat merender prompt 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 saluran hanya menautkan transportasi dan tidak mengirim 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 penyebaran 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.

Reaksi pertanyaan

Untuk prompt ask_user dengan satu pertanyaan non-rahasia, pilihan tunggal, dan satu hingga empat opsi, WhatsApp menampilkan 1️⃣ hingga 4️⃣ di samping label opsi. Berikan reaksi pada prompt yang dikirim dengan nomor yang sesuai untuk menjawabnya. OpenClaw memetakan nomor tersebut ke opsi kanonis melalui Gateway; ketukan kedaluwarsa atau duplikat diabaikan. Prompt multi-pertanyaan, multi-pilihan, dan teks bebas tetap hanya dapat dijawab melalui teks. Aturan penerimaan DM/grup WhatsApp normal mengotorisasi pengirim yang memberikan reaksi.

Hook plugin dan privasi

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

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

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

Kontrol akses dan aktivasi

Pengikatan ACP yang dikonfigurasi

WhatsApp mendukung pengikatan ACP persisten melalui bindings[] tingkat teratas:

{  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 pembatasan penyebutan/aktivasi dijalankan sebelum OpenClaw memastikan sesi ACP yang terikat tersedia. Pengikatan yang cocok memiliki rute tersebut — grup siaran tidak menyebarkan giliran itu ke sesi WhatsApp biasa.

Perilaku nomor pribadi dan percakapan dengan diri sendiri

Jika nomor sendiri yang ditautkan juga ada dalam allowFrom, pengaman percakapan dengan diri sendiri diaktifkan: melewati tanda pesan telah dibaca untuk giliran percakapan dengan diri sendiri, mengabaikan perilaku pemicu otomatis JID penyebutan yang akan melakukan ping kepada diri sendiri, dan mengarahkan balasan secara default ke [{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 terlihat 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 konfirmasi

channels.whatsapp.ackReaction mengirim reaksi langsung saat pesan masuk diterima, yang dibatasi oleh 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 ada tanpa emoji, WhatsApp menggunakan emoji identitas agen yang dirutekan dengan fallback ke "👀" (hilangkan ackReaction atau tetapkan emoji: "" agar tidak ada konfirmasi); kegagalan dicatat dalam log tetapi tidak memblokir pengiriman balasan; mode grup mentions bereaksi hanya 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 proses

Tetapkan messages.statusReactions.enabled: true agar WhatsApp mengganti reaksi konfirmasi selama suatu giliran alih-alih membiarkan emoji penerimaan statis, dengan beralih 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 antrean menggunakan emoji efektif yang sama seperti reaksi konfirmasi biasa; WhatsApp memiliki satu slot reaksi bot per pesan, sehingga pembaruan siklus hidup menggantikan reaksi saat ini secara langsung; messages.removeAckAfterReply: true menghapus reaksi status akhir setelah durasi penyimpanan selesai/kesalahan yang dikonfigurasi; kategori emoji alat mencakup tool, coding, web, deploy, build, dan concierge.

Multiakun 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 menggunakan true), channels.whatsapp.actions.calls (default false, lihat MeowCaller di atas).
• Penulisan konfigurasi yang dimulai oleh saluran diaktifkan secara default; nonaktifkan melalui channels.whatsapp.configWrites: false.

Pemecahan masalah

openclaw channels login --channel whatsappopenclaw channels status

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 miliknya sendiri, peta tersebut sepenuhnya menggantikan peta groups tingkat akar (tanpa penggabungan mendalam). Pencarian prompt kemudian dijalankan pada satu peta hasil tersebut:

1. Prompt khusus grup (groups["<groupId>"].systemPrompt): digunakan ketika entri grup tersedia dan kunci systemPrompt ditentukan. String kosong ("") menekan karakter pengganti dan tidak menerapkan prompt apa pun.
2. Prompt karakter pengganti grup (groups["*"].systemPrompt): digunakan ketika 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 tingkat akar untuk setiap akun dalam konfigurasi multiakun (bahkan akun yang tidak memiliki groups sendiri) agar bot tidak menerima pesan grup dari grup yang bukan tempatnya bergabung. WhatsApp tidak menerapkan perlindungan tersebut — groups/direct tingkat akar diwarisi oleh setiap akun tanpa penggantian sendiri, terlepas dari jumlah akun. Dalam konfigurasi 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 izin grup tingkat percakapan. Pada cakupan akar maupun akun, groups["*"] berarti "semua grup diterima" untuk cakupan tersebut.
• Hanya tambahkan karakter pengganti systemPrompt jika Anda memang ingin cakupan tersebut menerima semua grup. Agar hanya sekumpulan ID grup tertentu yang memenuhi syarat, ulangi prompt pada setiap entri yang secara eksplisit masuk daftar izin, alih-alih menggunakan groups["*"].
• Penerimaan grup dan otorisasi pengirim merupakan pemeriksaan terpisah. groups["*"] memperluas grup mana yang mencapai penanganan grup; tindakan ini tidak mengotorisasi setiap pengirim dalam grup tersebut — hal itu tetap dikontrol oleh groupPolicy/groupAllowFrom.
• channels.whatsapp.direct tidak memiliki efek samping yang setara untuk pesan langsung: direct["*"] hanya menyediakan konfigurasi default setelah pesan langsung diterima oleh dmPolicy beserta allowFrom atau aturan penyimpanan pemasangan.

Contoh:

{  channels: {    whatsapp: {      groups: {        // Gunakan hanya jika semua grup harus diterima pada cakupan akar.        // Berlaku untuk semua akun yang tidak mendefinisikan peta groups sendiri.        "*": { systemPrompt: "Prompt default untuk semua grup." },      },      direct: {        // Berlaku untuk semua akun yang tidak mendefinisikan peta direct sendiri.        "*": { systemPrompt: "Prompt default untuk semua percakapan langsung." },      },      accounts: {        work: {          groups: {            // Akun ini mendefinisikan groups sendiri, sehingga groups tingkat 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 diterima di akun ini.            "*": { systemPrompt: "Prompt default untuk grup kerja." },          },          direct: {            // Akun ini mendefinisikan peta direct sendiri, sehingga entri direct tingkat 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." },          },        },      },    },  },}

Petunjuk referensi konfigurasi

Referensi utama: Referensi konfigurasi - WhatsApp

Terkait

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