WhatsApp

Durum: WhatsApp Web (Baileys) üzerinden üretime hazır. Bağlı oturumların sahipliği Gateway'e aittir; ayrı bir Twilio WhatsApp kanalı yoktur.

Kurulum

openclaw onboard ve openclaw channels add --channel whatsapp, kanalı ilk seçtiğinizde Plugin'i yüklemenizi ister; Plugin eksikse openclaw channels login --channel whatsapp da aynı yükleme akışını sunar. Geliştirme çalışma kopyaları yerel Plugin yolunu kullanır; kararlı/beta kurulumları önce ClawHub'dan @openclaw/whatsapp paketini yükler, bu başarısız olursa npm'e başvurur. WhatsApp çalışma zamanı, temel OpenClaw npm paketinin dışında dağıtıldığından çalışma zamanı bağımlılıkları harici Plugin ile birlikte kalır. Manuel kurulum:

openclaw plugins install clawhub:@openclaw/whatsapp

Çıplak npm paketini (@openclaw/whatsapp) yalnızca kayıt defteri geri dönüşü için kullanın; tam sürümü yalnızca tekrarlanabilir bir kurulum için sabitleyin.

Hızlı kurulum

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

Dağıtım kalıpları

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

Çalışma zamanı modeli

• WhatsApp soketinin ve yeniden bağlanma döngüsünün sahipliği Gateway'e aittir.
• Bir gözetleyici iki sinyali bağımsız olarak izler: ham WhatsApp Web aktarım etkinliği ve uygulama mesajı etkinliği. Sessiz ancak bağlı bir oturum, yalnızca yakın zamanda mesaj gelmediği için yeniden başlatılmaz; yalnızca aktarım çerçeveleri sabit bir dahili süre boyunca (kullanıcı tarafından yapılandırılamaz) gelmezse veya uygulama mesajları normal mesaj zaman aşımının 4 katını aşacak kadar sessiz kalırsa yeniden bağlanmaya zorlanır. Yakın zamanda etkin olan bir oturum yeniden bağlandıktan hemen sonra ilk zaman aralığında 4 katlık süre yerine daha kısa olan normal mesaj zaman aşımı kullanılır. OpenClaw, Baileys'in bu yeniden bağlanmanın erken aşamasında teslim ettiği çevrimdışı mesajları, gelen mesaj kimliği tekilleştirme ömrüyle sınırlı olmak üzere otomatik yanıtlayabilir; ilk başlatmada kısa eski geçmiş koruması korunur.
• Baileys soket zamanlamaları web.whatsapp.* altında açıkça belirtilir: keepAliveIntervalMs (uygulama ping aralığı), connectTimeoutMs (başlangıç el sıkışması zaman aşımı), defaultQueryTimeoutMs (Baileys sorgu beklemelerinin yanı sıra OpenClaw'ın giden gönderim/durum ve gelen okundu bilgisi zaman aşımları).
• Giden gönderimler, hedef hesap için etkin bir WhatsApp dinleyicisi gerektirir; aksi durumda gönderimler hemen başarısız olur.
• Grup gönderimleri, belirteç mevcut katılımcı meta verileriyle eşleştiğinde metin ve medya açıklamalarındaki @+<digits> ve @<digits> belirteçlerine, LID destekli gruplar da dahil olmak üzere yerel bahsetme meta verileri ekler.
• Durum ve yayın sohbetleri (@status, @broadcast) yok sayılır.
• Doğrudan sohbetler DM oturum kurallarını kullanır (session.dmScope; varsayılan main, DM'leri ajanın ana oturumunda birleştirir). Grup oturumları JID başına yalıtılır (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Kanalları/Bültenleri, DM anlamlandırması yerine kanal oturumu meta verileri (agent:<agentId>:whatsapp:channel:<jid>) kullanılarak yerel @newsletter JID'leri üzerinden açık giden hedefler olabilir.
• WhatsApp Web aktarımı, Gateway ana makinesindeki standart proxy ortam değişkenlerini (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, küçük harfli çeşitleri) dikkate alır. Kanal başına ayarlar yerine ana makine düzeyinde proxy yapılandırmasını tercih edin.
• messages.removeAckAfterReply etkinleştirildiğinde OpenClaw, görünür bir yanıt teslim edildikten sonra onay tepkisini temizler.

MeowCaller ile mevcut istekte bulunan kişiyi arayın (deneysel)

Plugin, WhatsApp kaynaklı ajan dönüşlerinde whatsapp_call aracını sunabilir. MeowCaller kullanarak mevcut yetkili istekte bulunan kişiye WhatsApp sesli araması yapar ve kişi yanıt verdikten sonra bir OpenClaw TTS mesajı oynatır. Araçta hedef numara parametresi bulunmadığından bir istem aramayı başka bir yere yönlendiremez. Varsayılan olarak devre dışıdır.

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

Sınırlar: yalnızca bire bir giden sesli aramalar, rastgele hedef numara yok, sohbet bağlantısıyla paylaşılan kimlik doğrulaması yok, kişisel numara/kendi kendine sohbet modundan kişinin kendisini araması yok, sentezlenen ses en fazla 60 saniye, MeowCaller'ın yanıt/oynatma/kapatma tamamlanması dışında telefon tarafında duyulabilirlik alındısı yoktur ve OpenClaw, yardımcı işlemi MeowCaller'ın bağlantı, yanıt, oynatma ve kapatma aşamalarını kapsayan 115-175 saniyelik sınırlı bir sürenin ardından durdurur.

Onay istemleri

WhatsApp, üst düzey onay yönlendirme yapılandırmasıyla kontrol edilen çalıştırma ve Plugin onay istemlerini 👍/👎 tepkileri olarak gösterebilir:

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

approvals.exec ve approvals.plugin birbirinden bağımsızdır; WhatsApp'ı kanal olarak etkinleştirmek yalnızca aktarımı bağlar ve eşleşen onay ailesi etkinleştirilip oraya yönlendirilmediği sürece hiçbir şey göndermez. Oturum modu, yerel emoji onaylarını yalnızca WhatsApp kaynaklı onaylara teslim eder. Hedef modu, açık hedefler için paylaşılan yönlendirme işlem hattını kullanır ve onaylayıcı DM'lerine ayrı bir dağıtım oluşturmaz.

WhatsApp onay tepkileri, allowFrom (veya "*") içinde açıkça belirtilmiş onaylayıcılar gerektirir. defaultTo, onaylayıcı listesini değil sıradan varsayılan mesaj hedeflerini belirler. Manuel /approve komutları, onay çözümlenmeden önce normal WhatsApp gönderici yetkilendirme yolundan geçmeye devam eder.

Plugin kancaları ve gizlilik

Gelen WhatsApp mesajları kişisel içerik, telefon numaraları, grup tanımlayıcıları, gönderici adları ve oturum ilişkilendirme alanları içerebilir. Siz açıkça etkinleştirmediğiniz sürece WhatsApp, gelen message_received kanca yüklerini Plugin'lere yayınlamaz:

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

Etkinleştirmeyi channels.whatsapp.accounts.<id>.pluginHooks.messageReceived altında tek bir hesapla sınırlandırın. Bunu yalnızca gelen WhatsApp içeriği ve tanımlayıcıları konusunda güvendiğiniz Plugin'ler için etkinleştirin.

Erişim denetimi ve etkinleştirme

Yapılandırılmış ACP bağlamaları

WhatsApp, üst düzey bindings[] aracılığıyla kalıcı ACP bağlamalarını destekler:

{  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" },      },    },  ],}

Doğrudan sohbetler E.164 numaralarıyla, gruplar ise WhatsApp grup JID'leriyle eşleşir. Grup izin listeleri, gönderen politikası ve bahsetme/etkinleştirme geçidi, OpenClaw bağlı ACP oturumunun varlığını sağlamadan önce çalışır. Eşleşen bağlama yönlendirmenin sahibidir; yayın grupları bu turu sıradan WhatsApp oturumlarına dağıtmaz.

Kişisel numara ve kendi kendine sohbet davranışı

Bağlı kişisel numara allowFrom içinde de bulunduğunda kendi kendine sohbet korumaları etkinleşir: kendi kendine sohbet turlarında okundu bilgileri atlanır, kendinize bildirim gönderecek bahsetme JID'si otomatik tetikleme davranışı yok sayılır ve messages.responsePrefix ayarlanmamışsa yanıtlar varsayılan olarak [{identity.name}] (veya [openclaw]) ile başlar.

Mesaj normalleştirme ve bağlam

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

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

Teslimat, parçalara ayırma ve medya

Yanıt alıntılama

channels.whatsapp.replyToMode, yerel yanıt alıntılamayı denetler (giden yanıtlar gelen mesajı görünür biçimde alıntılar):

Hesap başına geçersiz kılma: channels.whatsapp.accounts.<id>.replyToMode.

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

Tepki düzeyi

channels.whatsapp.reactionLevel, ajanın emoji tepkilerini ne ölçüde kullandığını denetler:

Hesap başına geçersiz kılma: channels.whatsapp.accounts.<id>.reactionLevel.

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

Alındı tepkileri

channels.whatsapp.ackReaction, gelen ileti alındığında reactionLevel tarafından denetlenen anlık bir tepki gönderir ("off" olduğunda bastırılır):

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

Notlar: gelen ileti kabul edildikten hemen sonra (yanıttan önce) gönderilir; ackReaction, emoji olmadan mevcutsa WhatsApp yönlendirilen ajanın kimlik emojisini kullanır ve bulunamazsa "👀" değerine geri döner (alındı tepkisi olmaması için ackReaction değerini belirtmeyin veya emoji: "" ayarlayın); hatalar günlüğe kaydedilir ancak yanıt teslimatını engellemez; mentions grup modu yalnızca bahsetmeyle tetiklenen turlarda tepki verirken always grup etkinleştirmesi bu denetimi atlar; WhatsApp yalnızca channels.whatsapp.ackReaction değerini kullanır (eski messages.ackReaction burada geçerli değildir).

Yaşam döngüsü durum tepkileri

WhatsApp'ın bir tur sırasında sabit bir alındı emojisi bırakmak yerine alındı tepkisini kuyrukta, düşünüyor, araç etkinliği, Compaction, tamamlandı ve hata gibi durumlar arasında geçiş yaparak değiştirmesine izin vermek için messages.statusReactions.enabled: true ayarlayın:

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

Notlar: channels.whatsapp.ackReaction, doğrudan mesajlar ve gruplar için uygunluğu denetlemeye devam eder; kuyrukta durumu, düz alındı tepkileriyle aynı geçerli emojiyi kullanır; WhatsApp'ta mesaj başına bir bot tepki yuvası bulunduğundan yaşam döngüsü güncellemeleri geçerli tepkiyi yerinde değiştirir; messages.removeAckAfterReply: true, yapılandırılmış tamamlandı/hata bekleme süresinden sonra son durum tepkisini temizler; araç emoji kategorileri tool, coding, web, deploy, build ve concierge değerlerini içerir.

Birden çok hesap ve kimlik bilgileri

Araçlar, eylemler ve yapılandırma yazımları

• Aracı araç desteği, WhatsApp tepki eylemini (react) içerir.
• Eylem geçitleri: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (mevcut eylemler varsayılan olarak true), channels.whatsapp.actions.calls (varsayılan false; yukarıdaki MeowCaller bölümüne bakın).
• Kanal tarafından başlatılan yapılandırma yazımları varsayılan olarak etkindir; channels.whatsapp.configWrites: false ile devre dışı bırakın.

Sorun giderme

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>

Sistem istemleri

WhatsApp, groups ve direct eşlemeleri üzerinden gruplar ve doğrudan sohbetler için Telegram tarzı sistem istemlerini destekler.

Grup mesajlarının çözümlenmesi: Önce etkin groups eşlemesi belirlenir — hesap kendi groups anahtarını herhangi bir şekilde tanımlıyorsa kök groups eşlemesini tamamen değiştirir (derin birleştirme yapılmaz). Ardından istem araması, ortaya çıkan bu tek eşleme üzerinde çalışır:

1. Gruba özgü istem (groups["<groupId>"].systemPrompt): grup girdisi mevcut olduğunda ve systemPrompt anahtarı tanımlandığında kullanılır. Boş dize ("") joker karakteri baskılar ve hiçbir istem uygulamaz.
2. Grup joker karakter istemi (groups["*"].systemPrompt): belirli grup girdisi bulunmadığında veya systemPrompt anahtarı olmadan bulunduğunda kullanılır.

Doğrudan mesajların çözümlenmesi, direct eşlemesi ve direct["*"] üzerinde aynı kalıbı izler.

Telegram'dan farkı: Telegram, çok hesaplı bir kurulumda botun üyesi olmadığı gruplardan grup mesajları almasını engellemek için her hesapta kök groups öğesini baskılar (kendi groups öğesi olmayan hesaplarda bile). WhatsApp bu korumayı uygulamaz — hesap sayısından bağımsız olarak, kendi geçersiz kılması olmayan her hesap kök groups/direct öğelerini devralır. Çok hesaplı bir WhatsApp kurulumunda hesap başına istemler istiyorsanız tam eşlemeyi her hesabın altında açıkça tanımlayın.

Önemli davranış:

• channels.whatsapp.groups, hem grup başına yapılandırma eşlemesi hem de sohbet düzeyindeki grup izin listesidir. Kök veya hesap kapsamında groups["*"], ilgili kapsam için "tüm gruplar kabul edilir" anlamına gelir.
• Yalnızca ilgili kapsamın tüm grupları kabul etmesini zaten istiyorsanız joker karakterli bir systemPrompt ekleyin. Yalnızca sabit bir grup kimliği kümesini uygun tutmak için groups["*"] kullanmak yerine istemi açıkça izin verilen her girdide yineleyin.
• Grup kabulü ile gönderen yetkilendirmesi ayrı denetimlerdir. groups["*"], grup işlemeye ulaşan grupların kapsamını genişletir; bu gruplardaki her gönderene yetki vermez — bu, groupPolicy/groupAllowFrom tarafından denetlenmeye devam eder.
• channels.whatsapp.direct öğesinin DM'ler için eşdeğer bir yan etkisi yoktur: direct["*"], yalnızca bir DM dmPolicy ile allowFrom veya eşleştirme deposu kuralları tarafından zaten kabul edildikten sonra varsayılan yapılandırma sağlar.

Örnek:

{  channels: {    whatsapp: {      groups: {        // Yalnızca tüm grupların kök kapsamında kabul edilmesi gerekiyorsa kullanın.        // Kendi groups eşlemesini tanımlamayan tüm hesaplara uygulanır.        "*": { systemPrompt: "Tüm gruplar için varsayılan istem." },      },      direct: {        // Kendi direct eşlemesini tanımlamayan tüm hesaplara uygulanır.        "*": { systemPrompt: "Tüm doğrudan sohbetler için varsayılan istem." },      },      accounts: {        work: {          groups: {            // Bu hesap kendi groups öğesini tanımladığından kök groups öğesinin            // yerini tamamen alır. Joker karakteri korumak için "*" öğesini burada da açıkça tanımlayın.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Proje yönetimine odaklan.",            },            // Yalnızca tüm grupların bu hesapta kabul edilmesi gerekiyorsa kullanın.            "*": { systemPrompt: "İş grupları için varsayılan istem." },          },          direct: {            // Bu hesap kendi direct eşlemesini tanımladığından kök direct girdilerinin            // yerini tamamen alır. Joker karakteri korumak için "*" öğesini burada da açıkça tanımlayın.            "+15551234567": { systemPrompt: "Belirli bir iş doğrudan sohbeti için istem." },            "*": { systemPrompt: "Doğrudan iş sohbetleri için varsayılan istem." },          },        },      },    },  },}

Yapılandırma başvurusu yönlendirmeleri

Birincil başvuru: Yapılandırma başvurusu - WhatsApp

İlgili konular

• Eşleştirme
• Gruplar
• Güvenlik
• Kanal yönlendirme
• Çok aracılı yönlendirme
• Sorun giderme