WhatsApp

Status: siap produksi melalui WhatsApp Web (Baileys). Gateway memiliki sesi tertaut.

Instalasi (sesuai permintaan)

• Onboarding (openclaw onboard) dan openclaw channels add --channel whatsapp meminta Anda memasang Plugin WhatsApp saat pertama kali memilihnya.
• openclaw channels login --channel whatsapp juga menawarkan alur instalasi ketika Plugin belum tersedia.
• Channel dev + checkout git: default ke jalur Plugin lokal.
• Stable/Beta: memasang Plugin resmi @openclaw/whatsapp dari ClawHub terlebih dahulu, dengan npm sebagai fallback.
• Runtime WhatsApp didistribusikan di luar paket npm inti OpenClaw agar dependensi runtime khusus WhatsApp tetap berada bersama Plugin eksternal.

Instalasi manual tetap tersedia:

openclaw plugins install clawhub:@openclaw/whatsapp

Gunakan paket npm polos (@openclaw/whatsapp) hanya ketika Anda memerlukan fallback registry. Sematkan versi persis hanya ketika Anda memerlukan 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>

Panggil pemohon saat ini dengan MeowCaller (eksperimental)

Plugin WhatsApp dapat mengekspos whatsapp_call dalam giliran agen yang berasal dari WhatsApp. Tool ini menggunakan MeowCaller untuk melakukan panggilan suara WhatsApp ke pemohon resmi saat ini dan memutar pesan TTS OpenClaw setelah mereka menjawab. Tool ini tidak menerima nomor tujuan, sehingga prompt tidak dapat mengalihkan panggilan ke pihak ketiga. Kapabilitas eksperimental ini 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"

Batas saat ini:

• hanya panggilan audio keluar satu-ke-satu
• tanpa nomor tujuan arbitrer
• tanpa auth bersama dengan koneksi chat
• tanpa panggilan ke diri sendiri dari mode nomor pribadi/chat mandiri
• audio tersintesis dibatasi hingga 60 detik
• tanpa tanda terima keterdengaran di sisi handset selain penyelesaian jawab/pemutaran/tutup dari MeowCaller
• OpenClaw menghentikan proses pendamping setelah jendela terbatas 115-175 detik, termasuk fase koneksi, jawab, pemutaran, dan penghentian MeowCaller

Pola deployment

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

Model runtime

• Gateway memiliki soket WhatsApp dan loop koneksi ulang.
• Watchdog koneksi ulang menggunakan aktivitas transport WhatsApp Web, bukan hanya volume pesan aplikasi masuk, sehingga sesi perangkat tertaut yang sepi tidak dimulai ulang hanya karena belum ada yang mengirim pesan baru-baru ini. Batas hening aplikasi yang lebih panjang tetap memaksa koneksi ulang jika frame transport terus masuk tetapi tidak ada pesan aplikasi yang ditangani selama jendela watchdog; setelah koneksi ulang sementara untuk sesi yang baru-baru ini aktif, pemeriksaan hening aplikasi tersebut menggunakan timeout pesan normal untuk jendela pemulihan pertama.
• Timing soket Baileys eksplisit di bawah web.whatsapp.*: keepAliveIntervalMs mengontrol ping aplikasi WhatsApp Web, connectTimeoutMs mengontrol timeout handshake pembukaan, dan defaultQueryTimeoutMs mengontrol tunggu kueri Baileys plus batas operasi kirim/presence keluar lokal dan tanda terima baca masuk OpenClaw.
• Pengiriman keluar memerlukan listener WhatsApp aktif untuk akun target.
• Pengiriman grup melampirkan metadata mention native untuk token @+<digits> dan @<digits> dalam teks dan caption media ketika token cocok dengan metadata peserta WhatsApp saat ini, termasuk grup berbasis LID.
• Chat status dan broadcast diabaikan (@status, @broadcast).
• Watchdog koneksi ulang mengikuti aktivitas transport WhatsApp Web, bukan hanya volume pesan aplikasi masuk: sesi perangkat tertaut yang sepi tetap aktif selama frame transport berlanjut, tetapi stall transport memaksa koneksi ulang jauh sebelum jalur pemutusan jarak jauh yang lebih akhir.
• Chat langsung menggunakan aturan sesi DM (session.dmScope; default main menggabungkan DM ke sesi utama agen).
• Sesi grup diisolasi (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters dapat menjadi target keluar eksplisit dengan JID @newsletter native. Pengiriman newsletter keluar menggunakan metadata sesi channel (agent:<agentId>:whatsapp:channel:<jid>) alih-alih semantik sesi DM.
• Transport WhatsApp Web menghormati variabel lingkungan proxy standar pada host gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / varian huruf kecil). Lebih utamakan konfigurasi proxy tingkat host daripada pengaturan proxy WhatsApp khusus channel.
• Ketika messages.removeAckAfterReply diaktifkan, OpenClaw menghapus reaksi ack WhatsApp setelah balasan terlihat terkirim.

Prompt persetujuan

WhatsApp dapat merender prompt persetujuan exec dan Plugin dengan reaksi 👍 / 👎. Pengiriman dikontrol 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 channel hanya menautkan transport; itu tidak mengirim prompt persetujuan kecuali keluarga persetujuan yang cocok diaktifkan dan diarahkan ke WhatsApp. Mode sesi mengirim persetujuan emoji native hanya untuk persetujuan yang berasal dari WhatsApp. Mode target menggunakan pipeline penerusan bersama untuk target WhatsApp eksplisit dan tidak membuat fanout DM pemberi persetujuan terpisah.

Reaksi persetujuan WhatsApp memerlukan pemberi persetujuan WhatsApp eksplisit dari allowFrom atau "*". defaultTo mengontrol target pesan default biasa; itu bukan pemberi persetujuan persetujuan. Perintah manual /approve tetap melewati jalur otorisasi pengirim WhatsApp normal sebelum resolusi persetujuan.

Hook Plugin dan privasi

Pesan masuk WhatsApp dapat berisi konten pesan pribadi, nomor telepon, pengidentifikasi grup, nama pengirim, dan bidang korelasi sesi. Karena itu, WhatsApp tidak menyiarkan payload hook message_received masuk ke plugin kecuali Anda ikut serta secara eksplisit:

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

Anda dapat membatasi keikutsertaan ke satu akun:

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

Aktifkan ini hanya untuk plugin yang Anda percayai untuk menerima konten dan pengidentifikasi pesan WhatsApp masuk.

Kontrol akses dan aktivasi

Binding ACP yang dikonfigurasi

WhatsApp mendukung binding ACP persisten dengan entri 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" },      },    },  ],}

• Chat langsung cocok dengan nomor E.164 seperti +15555550123.
• Grup cocok dengan JID grup WhatsApp seperti 120363424282127706@g.us.
• Allowlist grup, kebijakan pengirim, dan gerbang mention atau aktivasi berjalan sebelum OpenClaw memastikan sesi ACP yang dikonfigurasi ada.
• Binding ACP terkonfigurasi yang cocok memiliki rute tersebut. Grup broadcast WhatsApp tidak menyebarkan giliran itu ke sesi WhatsApp biasa.

Perilaku nomor pribadi dan chat mandiri

Saat nomor mandiri yang tertaut juga ada di allowFrom, pengaman chat mandiri WhatsApp aktif:

• lewati tanda terima baca untuk giliran chat mandiri
• abaikan perilaku pemicu otomatis mention-JID yang jika tidak akan melakukan ping ke diri sendiri
• jika messages.responsePrefix tidak ditetapkan, balasan chat mandiri default ke [{identity.name}] atau [openclaw]

Normalisasi pesan dan konteks

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

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

{  channels: {    whatsapp: {      accounts: {        work: {          sendReadReceipts: false,        },      },    },  },}

Pengiriman, pemotongan, dan media

Pengutipan balasan

WhatsApp mendukung pengutipan balasan native, saat balasan keluar mengutip pesan masuk secara terlihat. Kontrol dengan channels.whatsapp.replyToMode.

Default adalah "off". Penimpaan per akun menggunakan channels.whatsapp.accounts.<id>.replyToMode.

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

Tingkat reaksi

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

Default: "minimal".

Penimpaan per akun menggunakan channels.whatsapp.accounts.<id>.reactionLevel.

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

Reaksi acknowledgment

WhatsApp mendukung reaksi ack langsung pada tanda terima masuk melalui channels.whatsapp.ackReaction. Reaksi ack dibatasi oleh reactionLevel — reaksi tersebut ditekan ketika reactionLevel adalah "off".

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

Catatan perilaku:

• 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 atur emoji: "" agar tidak mengirim reaksi ack
• kegagalan dicatat dalam log tetapi tidak memblokir pengiriman balasan normal
• mode grup mentions bereaksi pada giliran yang dipicu oleh mention; aktivasi grup always bertindak sebagai bypass untuk pemeriksaan ini
• WhatsApp menggunakan channels.whatsapp.ackReaction (messages.ackReaction lama tidak digunakan di sini)

Reaksi status siklus hidup

Atur messages.statusReactions.enabled: true agar WhatsApp mengganti reaksi ack selama satu giliran alih-alih membiarkan emoji tanda terima statis. Saat diaktifkan, OpenClaw menggunakan slot reaksi pesan masuk yang sama untuk status siklus hidup seperti antre, berpikir, aktivitas tool, compaction, selesai, dan galat.

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

Catatan perilaku:

• channels.whatsapp.ackReaction tetap mengontrol apakah reaksi status memenuhi syarat untuk pesan langsung dan grup.
• Reaksi status antre menggunakan emoji ack efektif yang sama seperti reaksi ack 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 masa tahan selesai/galat yang dikonfigurasi.
• Kategori emoji tool mencakup tool, coding, web, deploy, build, dan concierge.

Multi-akun dan kredensial

Tool, tindakan, dan penulisan konfigurasi

• Dukungan tool agen mencakup tindakan reaksi WhatsApp (react).
• Gate tindakan:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Penulisan konfigurasi yang dimulai oleh channel 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 chat langsung melalui peta groups dan direct.

Hierarki resolusi untuk pesan grup:

Peta groups efektif ditentukan terlebih dahulu: jika akun mendefinisikan groups miliknya sendiri, itu sepenuhnya menggantikan peta groups root (tanpa deep merge). Lookup prompt kemudian berjalan pada satu peta yang dihasilkan:

1. Prompt sistem khusus grup (groups["<groupId>"].systemPrompt): digunakan ketika entri grup spesifik ada di peta dan kunci systemPrompt-nya didefinisikan. Jika systemPrompt adalah string kosong (""), wildcard ditekan dan tidak ada prompt sistem yang diterapkan.
2. Prompt sistem wildcard grup (groups["*"].systemPrompt): digunakan ketika entri grup spesifik sepenuhnya tidak ada dari peta, atau ketika entri itu ada tetapi tidak mendefinisikan kunci systemPrompt.

Hierarki resolusi untuk pesan langsung:

Peta direct efektif ditentukan terlebih dahulu: jika akun mendefinisikan direct miliknya sendiri, itu sepenuhnya menggantikan peta direct root (tanpa deep merge). Lookup prompt kemudian berjalan pada satu peta yang dihasilkan:

1. Prompt sistem khusus langsung (direct["<peerId>"].systemPrompt): digunakan ketika entri peer spesifik ada di peta dan kunci systemPrompt-nya didefinisikan. Jika systemPrompt adalah string kosong (""), wildcard ditekan dan tidak ada prompt sistem yang diterapkan.
2. Prompt sistem wildcard langsung (direct["*"].systemPrompt): digunakan ketika entri peer spesifik sepenuhnya tidak ada dari peta, atau ketika entri itu ada tetapi tidak mendefinisikan kunci systemPrompt.

Perbedaan dari perilaku multi-akun Telegram: Di Telegram, groups root sengaja ditekan untuk semua akun dalam setup multi-akun — bahkan akun yang tidak mendefinisikan groups miliknya sendiri — untuk mencegah bot menerima pesan grup untuk grup yang bukan tempat bot tersebut berada. WhatsApp tidak menerapkan guard ini: groups root dan direct root selalu diwarisi oleh akun yang tidak mendefinisikan override tingkat akun, terlepas dari berapa banyak akun yang dikonfigurasi. Dalam setup WhatsApp multi-akun, jika Anda menginginkan prompt grup atau langsung per akun, definisikan peta lengkap di bawah setiap akun secara eksplisit alih-alih mengandalkan default tingkat root.

Perilaku penting:

• channels.whatsapp.groups adalah peta konfigurasi per grup sekaligus allowlist grup tingkat chat. Pada scope root atau akun, groups["*"] berarti "semua grup diterima" untuk scope tersebut.
• Hanya tambahkan wildcard grup systemPrompt ketika Anda sudah ingin scope tersebut menerima semua grup. Jika Anda masih ingin hanya kumpulan tetap ID grup yang memenuhi syarat, jangan gunakan groups["*"] untuk default prompt. Sebagai gantinya, ulangi prompt pada setiap entri grup yang secara eksplisit ada di allowlist.
• Penerimaan grup dan otorisasi pengirim adalah pemeriksaan terpisah. groups["*"] memperluas kumpulan grup yang dapat mencapai penanganan grup, tetapi itu sendiri tidak mengotorisasi setiap pengirim di grup tersebut. Akses pengirim tetap dikontrol secara terpisah oleh channels.whatsapp.groupPolicy dan channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct tidak memiliki efek samping yang sama untuk DM. direct["*"] hanya menyediakan konfigurasi chat langsung default setelah DM sudah diterima oleh dmPolicy ditambah allowFrom atau aturan pairing-store.

Contoh:

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

Penunjuk referensi konfigurasi

Referensi utama:

• Referensi konfigurasi - WhatsApp

Field WhatsApp bernilai tinggi:

• akses: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• pengiriman: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-akun: accounts.<id>.enabled, accounts.<id>.authDir, penimpaan tingkat akun
• operasi: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• perilaku sesi: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompt: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

Terkait

• Pemasangan
• Grup
• Keamanan
• Perutean channel
• Perutean multi-agent
• Pemecahan masalah