WhatsApp (saluran Web)

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

Instal (sesuai kebutuhan)

Onboarding (openclaw onboard) dan openclaw channels add --channel whatsapp meminta untuk menginstal plugin WhatsApp saat pertama kali Anda memilihnya.
openclaw channels login --channel whatsapp juga menawarkan alur instal saat plugin belum tersedia.
Saluran dev + checkout git: default ke path plugin lokal.
Stable/Beta: default ke paket npm @openclaw/whatsapp.

Instal manual tetap tersedia:

openclaw plugins install @openclaw/whatsapp

Pairing

Kebijakan DM default adalah pairing untuk pengirim yang tidak dikenal.

Pemecahan masalah saluran

Diagnostik lintas saluran dan playbook perbaikan.

Konfigurasi gateway

Pola dan contoh konfigurasi saluran lengkap.

Penyiapan cepat

Konfigurasikan kebijakan akses WhatsApp

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

Tautkan WhatsApp (QR)

openclaw channels login --channel whatsapp

Untuk akun tertentu:

openclaw channels login --channel whatsapp --account work

Mulai gateway

openclaw gateway

Setujui permintaan pairing pertama (jika menggunakan mode pairing)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Permintaan pairing kedaluwarsa setelah 1 jam. Permintaan tertunda dibatasi hingga 3 per saluran.

OpenClaw merekomendasikan menjalankan WhatsApp pada nomor terpisah jika memungkinkan. (Metadata saluran dan alur penyiapan dioptimalkan untuk penyiapan tersebut, tetapi penyiapan nomor pribadi juga didukung.)

Pola deployment

Nomor khusus (disarankan)

Ini adalah mode operasional yang paling bersih:

identitas WhatsApp terpisah untuk OpenClaw
allowlist DM dan batas perutean yang lebih jelas
kemungkinan kebingungan obrolan sendiri lebih rendah

Pola kebijakan minimal:

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

Fallback nomor pribadi

Onboarding mendukung mode nomor pribadi dan menulis baseline yang ramah obrolan sendiri:

dmPolicy: "allowlist"
allowFrom menyertakan nomor pribadi Anda
selfChatMode: true

Saat runtime, perlindungan obrolan sendiri menggunakan nomor sendiri yang tertaut dan allowFrom.

Cakupan saluran khusus WhatsApp Web

Saluran platform pesan berbasis WhatsApp Web (Baileys) dalam arsitektur saluran OpenClaw saat ini.Tidak ada saluran pesan Twilio WhatsApp terpisah di registri saluran chat bawaan.

Model runtime

Gateway memiliki socket WhatsApp dan loop reconnect.
Pengiriman outbound memerlukan listener WhatsApp aktif untuk akun target.
Chat status dan broadcast diabaikan (@status, @broadcast).
Chat langsung menggunakan aturan sesi DM (session.dmScope; default main menggabungkan DM ke sesi utama agen).
Sesi grup diisolasi (agent:<agentId>:whatsapp:group:<jid>).
Transport WhatsApp Web mengikuti variabel environment proxy standar pada host gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / varian huruf kecil). Pilih konfigurasi proxy tingkat host daripada pengaturan proxy WhatsApp khusus saluran.

Kontrol akses dan aktivasi

Kebijakan DM
Kebijakan grup + allowlist
Mention + /activation

channels.whatsapp.dmPolicy mengontrol akses chat langsung:

pairing (default)
allowlist
open (mengharuskan allowFrom menyertakan "*")
disabled

allowFrom menerima nomor bergaya E.164 (dinormalisasi secara internal).Override multi-akun: channels.whatsapp.accounts.<id>.dmPolicy (dan allowFrom) didahulukan daripada default tingkat saluran untuk akun tersebut.Detail perilaku runtime:

pairing disimpan dalam allow-store saluran dan digabungkan dengan allowFrom yang dikonfigurasi
jika tidak ada allowlist yang dikonfigurasi, nomor sendiri yang tertaut diizinkan secara default
DM outbound fromMe tidak pernah dipairing secara otomatis

Akses grup memiliki dua lapisan:

Allowlist keanggotaan grup (channels.whatsapp.groups)
- jika groups dihilangkan, semua grup memenuhi syarat
- jika groups ada, itu bertindak sebagai allowlist grup ("*" diizinkan)
Kebijakan pengirim grup (channels.whatsapp.groupPolicy + groupAllowFrom)
- open: allowlist pengirim dilewati
- allowlist: pengirim harus cocok dengan groupAllowFrom (atau *)
- disabled: blokir semua inbound grup

Fallback allowlist pengirim:

jika groupAllowFrom tidak disetel, runtime menggunakan allowFrom sebagai fallback bila tersedia
allowlist pengirim dievaluasi sebelum aktivasi mention/balasan

Catatan: jika tidak ada blok channels.whatsapp sama sekali, fallback kebijakan grup runtime adalah allowlist (dengan log peringatan), meskipun channels.defaults.groupPolicy disetel.

Balasan grup secara default memerlukan mention.Deteksi mention mencakup:

mention WhatsApp eksplisit pada identitas bot
pola regex mention yang dikonfigurasi (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
deteksi reply-to-bot implisit (pengirim balasan cocok dengan identitas bot)

Catatan keamanan:

kutip/balas hanya memenuhi gating mention; itu tidak memberikan otorisasi pengirim
dengan groupPolicy: "allowlist", pengirim yang tidak ada di allowlist tetap diblokir meskipun mereka membalas pesan pengguna yang ada di allowlist

Perintah aktivasi tingkat sesi:

/activation mention
/activation always

activation memperbarui state sesi (bukan konfigurasi global). Ini dibatasi untuk owner.

Perilaku nomor pribadi dan obrolan sendiri

Saat nomor sendiri yang tertaut juga ada dalam allowFrom, perlindungan obrolan sendiri WhatsApp aktif:

lewati read receipt untuk giliran obrolan sendiri
abaikan perilaku auto-trigger mention-JID yang seharusnya mem-ping diri Anda sendiri
jika messages.responsePrefix tidak disetel, balasan obrolan sendiri default ke [{identity.name}] atau [openclaw]

Normalisasi pesan dan konteks

Envelope inbound + konteks balasan

Pesan WhatsApp masuk dibungkus dalam envelope inbound bersama.Jika ada balasan kutipan, konteks ditambahkan dalam bentuk ini:

[Membalas ke <sender> id:<stanzaId>]
<isi kutipan atau placeholder media>
[/Membalas]

Field metadata balasan juga diisi saat tersedia (ReplyToId, ReplyToBody, ReplyToSender, sender JID/E.164).

Placeholder media dan ekstraksi lokasi/kontak

Pesan inbound yang hanya berisi media dinormalisasi dengan placeholder seperti:

<media:image>
<media:video>
<media:audio>
<media:document>
<media:sticker>

Payload lokasi dan kontak dinormalisasi menjadi konteks tekstual sebelum perutean.

Injeksi riwayat grup tertunda

Untuk grup, pesan yang belum diproses dapat dibuffer dan diinjeksi sebagai konteks saat bot akhirnya dipicu.

batas default: 50
konfigurasi: channels.whatsapp.historyLimit
fallback: messages.groupChat.historyLimit
0 menonaktifkan

Penanda injeksi:

[Pesan chat sejak balasan terakhir Anda - untuk konteks]
[Pesan saat ini - balas pesan ini]

Read receipt

Read receipt diaktifkan secara default untuk pesan WhatsApp masuk yang diterima.Nonaktifkan secara global:

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

Override per akun:

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

Giliran obrolan sendiri melewati read receipt bahkan saat diaktifkan secara global.

Pengiriman, chunking, dan media

Chunking teks

batas chunk default: channels.whatsapp.textChunkLimit = 4000
channels.whatsapp.chunkMode = "length" | "newline"
mode newline memprioritaskan batas paragraf (baris kosong), lalu fallback ke chunking aman berdasarkan panjang

Perilaku media outbound

mendukung payload gambar, video, audio (voice-note PTT), dan dokumen
audio/ogg ditulis ulang menjadi audio/ogg; codecs=opus untuk kompatibilitas voice-note
pemutaran GIF animasi didukung melalui gifPlayback: true pada pengiriman video
caption diterapkan pada item media pertama saat mengirim payload balasan multi-media
sumber media dapat berupa HTTP(S), file://, atau path lokal

Batas ukuran media dan perilaku fallback

batas simpan media inbound: channels.whatsapp.mediaMaxMb (default 50)
batas kirim media outbound: channels.whatsapp.mediaMaxMb (default 50)
override per akun menggunakan channels.whatsapp.accounts.<accountId>.mediaMaxMb
gambar dioptimalkan otomatis (resize/sweep kualitas) agar sesuai dengan batas
saat pengiriman media gagal, fallback item pertama mengirim peringatan teks alih-alih diam-diam membuang respons

Tingkat reaksi

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

Tingkat	Reaksi ack	Reaksi yang diprakarsai agen	Deskripsi
`"off"`	Tidak	Tidak	Tidak ada reaksi sama sekali
`"ack"`	Ya	Tidak	Hanya reaksi ack (tanda terima pra-balasan)
`"minimal"`	Ya	Ya (konservatif)	Ack + reaksi agen dengan panduan konservatif
`"extensive"`	Ya	Ya (dianjurkan)	Ack + reaksi agen dengan panduan yang dianjurkan

Default: "minimal". Override per akun menggunakan channels.whatsapp.accounts.<id>.reactionLevel.

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

Reaksi acknowledgment

WhatsApp mendukung reaksi ack segera pada penerimaan inbound melalui channels.whatsapp.ackReaction. Reaksi ack dikendalikan oleh reactionLevel — reaksi ini disembunyikan saat reactionLevel adalah "off".

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

Catatan perilaku:

dikirim segera setelah inbound diterima (pra-balasan)
kegagalan dicatat ke log tetapi tidak memblokir pengiriman balasan normal
mode grup mentions bereaksi pada giliran yang dipicu mention; aktivasi grup always bertindak sebagai bypass untuk pemeriksaan ini
WhatsApp menggunakan channels.whatsapp.ackReaction (legacy messages.ackReaction tidak digunakan di sini)

Multi-akun dan kredensial

Pemilihan akun dan default

id akun berasal dari channels.whatsapp.accounts
pemilihan akun default: default jika ada, jika tidak id akun terkonfigurasi pertama (diurutkan)
id akun dinormalisasi secara internal untuk lookup

Path kredensial dan kompatibilitas legacy

path auth saat ini: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
file cadangan: creds.json.bak
auth default legacy di ~/.openclaw/credentials/ masih dikenali/dimigrasikan untuk alur akun default

Perilaku logout

openclaw channels logout --channel whatsapp [--account <id>] menghapus state auth WhatsApp untuk akun tersebut.Di direktori auth legacy, oauth.json dipertahankan sementara file auth Baileys dihapus.

Tools, actions, dan penulisan konfigurasi

Dukungan tool agen mencakup action reaksi WhatsApp (react).
Gating action:
- channels.whatsapp.actions.reactions
- channels.whatsapp.actions.polls
Penulisan konfigurasi yang diprakarsai saluran diaktifkan secara default (nonaktifkan melalui channels.whatsapp.configWrites=false).

Pemecahan masalah

Belum tertaut (memerlukan QR)

Gejala: status saluran melaporkan belum tertaut.Perbaikan:

openclaw channels login --channel whatsapp
openclaw channels status

Tertaut tetapi terputus / loop reconnect

Gejala: akun tertaut dengan disconnect berulang atau percobaan reconnect.Perbaikan:

openclaw doctor
openclaw logs --follow

Jika perlu, tautkan ulang dengan channels login.

Tidak ada listener aktif saat mengirim

Pengiriman outbound gagal cepat saat tidak ada listener gateway aktif untuk akun target.Pastikan gateway berjalan dan akun tertaut.

Pesan grup diabaikan secara tidak terduga

Periksa dalam urutan ini:

groupPolicy
groupAllowFrom / allowFrom
entri allowlist groups
gating mention (requireMention + pola mention)
kunci duplikat di openclaw.json (JSON5): entri yang lebih akhir menimpa entri sebelumnya, jadi pertahankan satu groupPolicy per cakupan

Peringatan runtime Bun

Runtime gateway WhatsApp harus menggunakan Node. Bun ditandai tidak kompatibel untuk operasi gateway WhatsApp/Telegram yang stabil.

Petunjuk referensi konfigurasi

Referensi utama:

Referensi konfigurasi - WhatsApp

Field WhatsApp dengan sinyal tinggi:

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

Overview

Messaging platforms

Configuration

WhatsApp

WhatsApp (saluran Web)

Instal (sesuai kebutuhan)

Pairing

Pemecahan masalah saluran

Konfigurasi gateway

Penyiapan cepat

Pola deployment

Model runtime

Kontrol akses dan aktivasi

Perilaku nomor pribadi dan obrolan sendiri

Normalisasi pesan dan konteks

Pengiriman, chunking, dan media

Tingkat reaksi

Reaksi acknowledgment

Multi-akun dan kredensial

Tools, actions, dan penulisan konfigurasi

Pemecahan masalah

Petunjuk referensi konfigurasi

Terkait

Overview

Messaging platforms

Configuration

​WhatsApp (saluran Web)

​Instal (sesuai kebutuhan)

Pairing

Pemecahan masalah saluran

Konfigurasi gateway

​Penyiapan cepat

​Pola deployment

​Model runtime

​Kontrol akses dan aktivasi

​Perilaku nomor pribadi dan obrolan sendiri

​Normalisasi pesan dan konteks

​Pengiriman, chunking, dan media

​Tingkat reaksi

​Reaksi acknowledgment

​Multi-akun dan kredensial

​Tools, actions, dan penulisan konfigurasi

​Pemecahan masalah

​Petunjuk referensi konfigurasi

​Terkait

WhatsApp (saluran Web)

Instal (sesuai kebutuhan)

Penyiapan cepat

Pola deployment

Model runtime

Kontrol akses dan aktivasi

Perilaku nomor pribadi dan obrolan sendiri

Normalisasi pesan dan konteks

Pengiriman, chunking, dan media

Tingkat reaksi

Reaksi acknowledgment

Multi-akun dan kredensial

Tools, actions, dan penulisan konfigurasi

Pemecahan masalah

Petunjuk referensi konfigurasi

Terkait