Ana içeriğe atla

​
WhatsApp (Web kanalı)

Durum: WhatsApp Web (Baileys) üzerinden üretime hazır. Bağlı oturum(lar)ın sahibi ağ geçididir.

​
Kurulum (gerektiğinde)

  • Onboarding (openclaw onboard) ve openclaw channels add --channel whatsapp, ilk kez seçtiğinizde WhatsApp eklentisini yüklemeyi önerir.
  • openclaw channels login --channel whatsapp da, eklenti henüz mevcut değilse kurulum akışını sunar.
  • Geliştirme kanalı + git checkout: varsayılan olarak yerel eklenti yolunu kullanır.
  • Stable/Beta: varsayılan olarak @openclaw/whatsapp npm paketini kullanır.
Elle kurulum seçeneği kullanılmaya devam eder: 
openclaw plugins install @openclaw/whatsapp

Eşleştirme

Bilinmeyen göndericiler için varsayılan DM ilkesi eşleştirmedir.

Kanal sorun giderme

Kanallar arası tanılama ve onarım kılavuzları.

Ağ geçidi yapılandırması

Tüm kanal yapılandırma desenleri ve örnekleri.

​
Hızlı kurulum

1

WhatsApp erişim ilkesini yapılandırın

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

WhatsApp'ı bağlayın (QR)

openclaw channels login --channel whatsapp
Belirli bir hesap için:
openclaw channels login --channel whatsapp --account work
3

Ağ geçidini başlatın

openclaw gateway
4

İlk eşleştirme isteğini onaylayın (eşleştirme kipi kullanılıyorsa)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Eşleştirme isteklerinin süresi 1 saat sonra dolar. Bekleyen istekler kanal başına en fazla 3 ile sınırlıdır.
OpenClaw, mümkün olduğunda WhatsApp’ı ayrı bir numarada çalıştırmanızı önerir. (Kanal meta verileri ve kurulum akışı bu kurulum için optimize edilmiştir, ancak kişisel numara kurulumları da desteklenir.)

​
Dağıtım desenleri

Bu en temiz operasyonel kipidir:
  • OpenClaw için ayrı WhatsApp kimliği
  • daha net DM allowlist’leri ve yönlendirme sınırları
  • kendinize sohbet karışıklığı yaşama olasılığının daha düşük olması
Minimum ilke deseni:
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
Onboarding kişisel numara kipini destekler ve self-chat dostu bir temel yapılandırma yazar:
  • dmPolicy: "allowlist"
  • allowFrom kişisel numaranızı içerir
  • selfChatMode: true
Çalışma zamanında self-chat korumaları, bağlı self numarası ve allowFrom üzerinden çalışır.
Mevcut OpenClaw kanal mimarisinde mesajlaşma platformu kanalı WhatsApp Web tabanlıdır (Baileys).Yerleşik sohbet-kanalı kayıt defterinde ayrı bir Twilio WhatsApp mesajlaşma kanalı yoktur.

​
Çalışma zamanı modeli

  • WhatsApp soketi ve yeniden bağlanma döngüsünün sahibi ağ geçididir.
  • Giden gönderimler, hedef hesap için etkin bir WhatsApp dinleyicisi gerektirir.
  • Durum ve yayın sohbetleri yok sayılır (@status, @broadcast).
  • Doğrudan sohbetler DM oturum kurallarını kullanır (session.dmScope; varsayılan main, DM’leri aracının ana oturumunda birleştirir).
  • Grup oturumları yalıtılmıştır (agent:<agentId>:whatsapp:group:<jid>).

​
Erişim denetimi ve etkinleştirme

channels.whatsapp.dmPolicy doğrudan sohbet erişimini denetler:
  • pairing (varsayılan)
  • allowlist
  • open (allowFrom değerinin "*" içermesini gerektirir)
  • disabled
allowFrom, E.164 biçimli numaraları kabul eder (dahili olarak normalize edilir).Çoklu hesap geçersiz kılması: channels.whatsapp.accounts.<id>.dmPolicy (ve allowFrom) o hesap için kanal düzeyindeki varsayılanların önüne geçer.Çalışma zamanı davranışı ayrıntıları:
  • eşleştirmeler kanal izin deposunda kalıcı olarak saklanır ve yapılandırılmış allowFrom ile birleştirilir
  • herhangi bir allowlist yapılandırılmamışsa, bağlı self numarasına varsayılan olarak izin verilir
  • giden fromMe DM’leri hiçbir zaman otomatik eşleştirilmez

​
Kişisel numara ve self-chat davranışı

Bağlı self numarası allowFrom içinde de bulunduğunda, WhatsApp self-chat korumaları etkinleşir:
  • self-chat dönüşleri için okundu bilgilerini atlar
  • aksi halde kendinize ping atacak mention-JID otomatik tetikleme davranışını yok sayar
  • messages.responsePrefix ayarlanmamışsa, self-chat yanıtları varsayılan olarak [{identity.name}] veya [openclaw] olur

​
Mesaj normalizasyonu ve bağlam

Gelen WhatsApp mesajları, paylaşılan gelen zarfına sarılır.Alıntılanmış bir yanıt varsa, bağlam şu biçimde eklenir:
[<sender> id:<stanzaId> mesajına yanıt veriliyor]
<alıntılanan gövde veya medya yer tutucusu>
[/Yanıt veriliyor]
Mevcut olduğunda yanıt meta veri alanları da doldurulur (ReplyToId, ReplyToBody, ReplyToSender, gönderen JID/E.164).
Yalnızca medya içeren gelen mesajlar şu tür yer tutucularla normalize edilir:
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
Konum ve kişi payload’ları yönlendirmeden önce metinsel bağlama normalize edilir.
Gruplarda, işlenmemiş mesajlar arabelleğe alınabilir ve bot sonunda tetiklendiğinde bağlam olarak eklenebilir.
  • varsayılan sınır: 50
  • yapılandırma: channels.whatsapp.historyLimit
  • yedek: messages.groupChat.historyLimit
  • 0 devre dışı bırakır
Ekleme işaretçileri:
  • [Son yanıtınızdan bu yana sohbet mesajları - bağlam için]
  • [Geçerli mesaj - buna yanıt verin]
Kabul edilen gelen WhatsApp mesajları için okundu bilgileri varsayılan olarak etkindir.Genel olarak devre dışı bırakmak için:
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
Hesap başına geçersiz kılma:
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
Self-chat dönüşleri, genel olarak etkin olsa bile okundu bilgilerini atlar.

​
Teslimat, parçalama ve medya

  • varsayılan parça sınırı: channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • newline kipi paragraf sınırlarını (boş satırlar) tercih eder, ardından uzunluk açısından güvenli parçalamaya döner
  • resim, video, ses (PTT sesli not) ve belge payload’larını destekler
  • audio/ogg, sesli not uyumluluğu için audio/ogg; codecs=opus olarak yeniden yazılır
  • hareketli GIF oynatımı, video gönderimlerinde gifPlayback: true ile desteklenir
  • çoklu medya yanıt payload’ları gönderilirken başlıklar ilk medya öğesine uygulanır
  • medya kaynağı HTTP(S), file:// veya yerel yollar olabilir
  • gelen medya kaydetme sınırı: channels.whatsapp.mediaMaxMb (varsayılan 50)
  • giden medya gönderme sınırı: channels.whatsapp.mediaMaxMb (varsayılan 50)
  • hesap başına geçersiz kılmalar channels.whatsapp.accounts.<accountId>.mediaMaxMb kullanır
  • resimler sınırlara sığması için otomatik olarak optimize edilir (yeniden boyutlandırma/kalite taraması)
  • medya gönderme hatasında, sessizce yanıtı düşürmek yerine ilk öğe yedeği metin uyarısı gönderir

​
Tepki düzeyi

channels.whatsapp.reactionLevel, aracının WhatsApp’ta emoji tepkilerini ne kadar geniş kullandığını denetler:
DüzeyAck tepkileriAracının başlattığı tepkilerAçıklama
"off"HayırHayırHiç tepki yok
"ack"EvetHayırYalnızca ack tepkileri (yanıt öncesi alındı)
"minimal"EvetEvet (temkinli)Ack + temkinli yönlendirmeyle aracı tepkileri
"extensive"EvetEvet (teşvik edilir)Ack + teşvik edilen yönlendirmeyle aracı tepkileri
Varsayılan: "minimal". Hesap başına geçersiz kılmalar channels.whatsapp.accounts.<id>.reactionLevel kullanır. 
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​
Alındı onay tepkileri

WhatsApp, channels.whatsapp.ackReaction aracılığıyla gelen alımında anında ack tepkilerini destekler. Ack tepkileri reactionLevel ile geçitlenir — reactionLevel "off" olduğunda bastırılırlar. 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
Davranış notları:
  • gelen kabul edildikten hemen sonra gönderilir (yanıt öncesi)
  • hatalar günlüğe kaydedilir ancak normal yanıt teslimatını engellemez
  • grup kipi mentions, mention ile tetiklenen dönüşlerde tepki verir; grup etkinleştirmesi always ise bu denetimi atlama görevi görür
  • WhatsApp, channels.whatsapp.ackReaction kullanır (eski messages.ackReaction burada kullanılmaz)

​
Çoklu hesap ve kimlik bilgileri

  • hesap kimlikleri channels.whatsapp.accounts içinden gelir
  • varsayılan hesap seçimi: varsa default, yoksa yapılandırılmış ilk hesap kimliği (sıralı)
  • hesap kimlikleri arama için dahili olarak normalize edilir
  • geçerli kimlik doğrulama yolu: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • yedek dosya: creds.json.bak
  • ~/.openclaw/credentials/ içindeki eski varsayılan kimlik doğrulama, varsayılan hesap akışları için hâlâ tanınır/taşınır
openclaw channels logout --channel whatsapp [--account <id>], o hesap için WhatsApp kimlik doğrulama durumunu temizler.Eski kimlik doğrulama dizinlerinde, Baileys kimlik doğrulama dosyaları kaldırılırken oauth.json korunur.

​
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
  • 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

Belirti: kanal durumu bağlı olmadığını bildiriyor.Düzeltme:
openclaw channels login --channel whatsapp
openclaw channels status
Belirti: bağlı hesapta tekrarlanan bağlantı kopmaları veya yeniden bağlanma denemeleri var.Düzeltme:
openclaw doctor
openclaw logs --follow
Gerekirse channels login ile yeniden bağlayın.
Hedef hesap için etkin bir ağ geçidi dinleyicisi olmadığında giden gönderimler hızlıca başarısız olur.Ağ geçidinin çalıştığından ve hesabın bağlı olduğundan emin olun.
Şu sırayla kontrol edin:
  • groupPolicy
  • groupAllowFrom / allowFrom
  • groups allowlist girdileri
  • mention geçitlemesi (requireMention + mention desenleri)
  • openclaw.json içindeki yinelenen anahtarlar (JSON5): sonraki girdiler öncekileri geçersiz kılar, bu yüzden kapsam başına tek bir groupPolicy tutun
WhatsApp ağ geçidi çalışma zamanı Node kullanmalıdır. Bun, kararlı WhatsApp/Telegram ağ geçidi çalışması için uyumsuz olarak işaretlenmiştir.

​
Yapılandırma başvuru işaretçileri

Birincil başvuru: Yüksek sinyalli WhatsApp alanları:
  • erişim: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • teslimat: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
  • çoklu hesap: accounts.<id>.enabled, accounts.<id>.authDir, hesap düzeyi geçersiz kılmaları
  • işlemler: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • oturum davranışı: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

​
İlgili