WhatsApp

Durum: WhatsApp Web (Baileys) üzerinden üretime hazır. Gateway bağlı oturumların sahibidir.

Kurulum (isteğe bağlı)

• Onboarding (openclaw onboard) ve openclaw channels add --channel whatsapp, WhatsApp Plugin'ini ilk seçtiğinizde kurmanız için istem gösterir.
• openclaw channels login --channel whatsapp, Plugin henüz mevcut değilse kurulum akışını da sunar.
• Geliştirme kanalı + git checkout: varsayılan olarak yerel Plugin yolunu kullanır.
• Stable/Beta: önce ClawHub'dan resmi @openclaw/whatsapp Plugin'ini kurar, yedek olarak npm kullanılır.
• WhatsApp çalışma zamanı, WhatsApp'a özgü çalışma zamanı bağımlılıkları harici Plugin'de kalsın diye çekirdek OpenClaw npm paketinin dışında dağıtılır.

Elle kurulum kullanılmaya devam eder:

openclaw plugins install clawhub:@openclaw/whatsapp

Çıplak npm paketini (@openclaw/whatsapp) yalnızca kayıt defteri yedeklemesine ihtiyaç duyduğunuzda kullanın. Tam bir sürümü yalnızca tekrarlanabilir bir kurulum gerektiğinde 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>

Geçerli istekte bulunan kişiyi MeowCaller ile arayın (deneysel)

WhatsApp Plugin'i, WhatsApp kaynaklı agent dönüşlerinde whatsapp_call aracını açığa çıkarabilir. Araç, geçerli yetkili istekte bulunan kişiye WhatsApp sesli araması yapmak için MeowCaller kullanır ve yanıt verdikten sonra bir OpenClaw TTS mesajı oynatır. Araç hedef numara kabul etmez, bu nedenle bir istem aramayı üçüncü bir tarafa yönlendiremez. Bu deneysel yetenek 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"

Geçerli sınırlar:

• yalnızca bire bir giden sesli aramalar
• rastgele hedef numara yok
• sohbet bağlantısıyla paylaşılan kimlik doğrulama yok
• kişisel numara/kendiyle sohbet modundan kendi kendine arama yok
• sentezlenen ses 60 saniyeyle sınırlıdır
• MeowCaller'ın yanıt/oynatma/kapatma tamamlanması dışında telefon tarafı duyulabilirlik alındısı yok
• OpenClaw, MeowCaller'ın bağlantı, yanıt, oynatma ve kapatma aşamaları dahil olmak üzere sınırlı 115-175 saniyelik bir pencereden sonra yardımcı süreci durdurur

Dağıtım kalıpları

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

Çalışma zamanı modeli

• Gateway, WhatsApp soketinin ve yeniden bağlanma döngüsünün sahibidir.
• Yeniden bağlanma watchdog'u yalnızca gelen uygulama mesajı hacmini değil, WhatsApp Web aktarım etkinliğini kullanır; böylece sessiz bir bağlı cihaz oturumu, yalnızca yakın zamanda kimse mesaj göndermedi diye yeniden başlatılmaz. Daha uzun bir uygulama sessizliği sınırı, aktarım çerçeveleri gelmeye devam ederken watchdog penceresi boyunca hiçbir uygulama mesajı işlenmezse yine de yeniden bağlanmayı zorlar; yakın zamanda etkin olmuş bir oturum için geçici yeniden bağlanmadan sonra, bu uygulama sessizliği kontrolü ilk kurtarma penceresi için normal mesaj zaman aşımını kullanır.
• Baileys soket zamanlamaları web.whatsapp.* altında açıktır: keepAliveIntervalMs WhatsApp Web uygulama ping'lerini kontrol eder, connectTimeoutMs açılış el sıkışması zaman aşımını kontrol eder ve defaultQueryTimeoutMs, Baileys sorgu beklemelerini ve OpenClaw'ın yerel giden gönderim/varlık ile gelen okundu bilgisi işlem sınırlarını kontrol eder.
• Giden gönderimler, hedef hesap için etkin bir WhatsApp dinleyicisi gerektirir.
• Grup gönderimleri, token geçerli WhatsApp katılımcı meta verileriyle eşleştiğinde, LID destekli gruplar dahil olmak üzere metin ve medya açıklamalarındaki @+<digits> ve @<digits> token'ları için yerel bahsetme meta verileri ekler.
• Durum ve yayın sohbetleri yok sayılır (@status, @broadcast).
• Yeniden bağlanma watchdog'u yalnızca gelen uygulama mesajı hacmini değil, WhatsApp Web aktarım etkinliğini izler: aktarım çerçeveleri devam ederken sessiz bağlı cihaz oturumları açık kalır, ancak aktarım durması daha sonraki uzak bağlantı kesme yolundan çok önce yeniden bağlanmayı zorlar.
• Doğrudan sohbetler DM oturum kurallarını kullanır (session.dmScope; varsayılan main, DM'leri agent ana oturumuna daraltır).
• Grup oturumları yalıtılmıştır (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Kanalları/Bültenleri, yerel @newsletter JID'leriyle açık giden hedefler olabilir. Giden bülten gönderimleri, DM oturum semantiği yerine kanal oturumu meta verilerini (agent:<agentId>:whatsapp:channel:<jid>) kullanır.
• WhatsApp Web aktarımı, Gateway ana makinesindeki standart proxy ortam değişkenlerine uyar (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / küçük harfli varyantlar). Kanala özgü WhatsApp proxy 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 WhatsApp ack tepkisini temizler.

Onay istemleri

WhatsApp, exec ve Plugin onay istemlerini 👍 / 👎 tepkileriyle işleyebilir. Teslimat, üst düzey onay iletme yapılandırması tarafından kontrol edilir:

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

approvals.exec ve approvals.plugin bağımsızdır. WhatsApp'ı kanal olarak etkinleştirmek yalnızca aktarımı bağlar; eşleşen onay ailesi etkinleştirilip WhatsApp'a yönlendirilmedikçe onay istemleri göndermez. Oturum modu, yerel emoji onaylarını yalnızca WhatsApp'tan kaynaklanan onaylar için teslim eder. Hedef modu, açık WhatsApp hedefleri için paylaşılan iletme işlem hattını kullanır ve ayrı onaylayıcı-DM yayılımı oluşturmaz.

WhatsApp onay tepkileri, allowFrom veya "*" üzerinden açık WhatsApp onaylayıcıları gerektirir. defaultTo, olağan varsayılan mesaj hedeflerini kontrol eder; bir onay onaylayıcısı değildir. Elle /approve komutları, onay çözümlemesinden önce yine normal WhatsApp gönderen yetkilendirme yolundan geçer.

Plugin kancaları ve gizlilik

WhatsApp gelen iletileri kişisel ileti içeriği, telefon numaraları, grup tanımlayıcıları, gönderen adları ve oturum ilişkilendirme alanları içerebilir. Bu nedenle, WhatsApp, siz açıkça etkinleştirmediğiniz sürece gelen message_received hook yüklerini Plugin'lere yayınlamaz:

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

Etkinleştirmeyi tek bir hesapla sınırlandırabilirsiniz:

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

Bunu yalnızca gelen WhatsApp ileti içeriğini ve tanımlayıcılarını almasına 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[] girdileriyle 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 +15555550123 gibi E.164 numaralarıyla eşleşir.
• Gruplar 120363424282127706@g.us gibi WhatsApp grup JID'leriyle eşleşir.
• Grup izin listeleri, gönderen ilkesi ve bahsetme veya etkinleştirme denetimi, OpenClaw yapılandırılmış ACP oturumunun var olduğundan emin olmadan önce çalışır.
• Eşleşen yapılandırılmış ACP bağlaması rotanın sahibidir. WhatsApp yayın grupları bu turu sıradan WhatsApp oturumlarına dağıtmaz.

Kişisel numara ve kendiyle sohbet davranışı

Bağlı kendi numarası allowFrom içinde de bulunduğunda, WhatsApp kendiyle sohbet korumaları etkinleşir:

• kendiyle sohbet turları için okundu bilgilerini atla
• aksi halde kendinize bildirim gönderecek bahsetme-JID otomatik tetikleme davranışını yoksay
• messages.responsePrefix ayarlanmamışsa, kendiyle sohbet yanıtları varsayılan olarak [{identity.name}] veya [openclaw] olur

İleti normalleştirme ve bağlam

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

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

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

Teslim, parçalara ayırma ve medya

Yanıt alıntılama

WhatsApp, giden yanıtların gelen iletiyi görünür şekilde alıntıladığı yerel yanıt alıntılamayı destekler. Bunu channels.whatsapp.replyToMode ile denetleyin.

Varsayılan "off" değeridir. Hesap bazında geçersiz kılmalar channels.whatsapp.accounts.<id>.replyToMode kullanır.

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

Tepki düzeyi

channels.whatsapp.reactionLevel, ajanın WhatsApp üzerinde emoji tepkilerini ne kadar geniş kullandığını denetler:

Varsayılan: "minimal".

Hesap bazında geçersiz kılmalar channels.whatsapp.accounts.<id>.reactionLevel kullanır.

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

Alındı onayı tepkileri

WhatsApp, channels.whatsapp.ackReaction üzerinden gelen alındığında anlık onay tepkilerini destekler. Onay tepkileri reactionLevel tarafından denetlenir; reactionLevel "off" olduğunda bastırılır.

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

Davranış notları:

• gelen mesaj kabul edildikten hemen sonra gönderilir (yanıttan önce)
• ackReaction, emoji olmadan varsa WhatsApp yönlendirilen ajanın kimlik emojisini kullanır, yoksa "👀" kullanır; onay tepkisi göndermemek için ackReaction öğesini atlayın veya emoji: "" ayarlayın
• hatalar günlüğe kaydedilir ancak normal yanıt teslimini engellemez
• grup modu mentions, bahsetmeyle tetiklenen turlarda tepki verir; grup etkinleştirme always, bu kontrol için atlama görevi görür
• WhatsApp channels.whatsapp.ackReaction kullanır (eski messages.ackReaction burada kullanılmaz)

Yaşam döngüsü durum tepkileri

WhatsApp'ın bir tur sırasında statik bir alındı emojisi bırakmak yerine onay tepkisini değiştirmesine izin vermek için messages.statusReactions.enabled: true ayarlayın. Etkinleştirildiğinde OpenClaw, sıraya alındı, düşünüyor, araç etkinliği, Compaction, tamamlandı ve hata gibi yaşam döngüsü durumları için aynı gelen mesaj tepki yuvasını kullanır.

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

Davranış notları:

• channels.whatsapp.ackReaction, durum tepkilerinin doğrudan mesajlar ve gruplar için uygun olup olmadığını hâlâ denetler.
• Sıraya alındı durum tepkisi, düz onay tepkileriyle aynı etkili onay emojisini kullanır.
• WhatsApp'ta mesaj başına bir bot tepki yuvası vardır, bu nedenle yaşam döngüsü güncellemeleri mevcut tepkiyi yerinde değiştirir.
• messages.removeAckAfterReply: true, yapılandırılan tamamlandı/hata bekletmesinden sonra son durum tepkisini temizler.
• Araç emoji kategorileri tool, coding, web, deploy, build ve concierge içerir.

Çoklu hesap ve kimlik bilgileri

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

• Ajan araç desteği WhatsApp tepki eylemini (react) içerir.
• Eylem kapıları:
  • 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

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 aracılığıyla gruplar ve doğrudan sohbetler için Telegram tarzı sistem istemlerini destekler.

Grup mesajları için çözümleme hiyerarşisi:

Etkili groups eşlemesi önce belirlenir: hesap kendi groups değerini tanımlıyorsa, kök groups eşlemesinin tamamen yerini alır (derin birleştirme yok). İstem araması daha sonra ortaya çıkan tek eşleme üzerinde çalışır:

1. Gruba özel sistem istemi (groups["<groupId>"].systemPrompt): belirli grup girdisi eşlemede varsa ve systemPrompt anahtarı tanımlıysa kullanılır. systemPrompt boş bir dizeyse (""), joker bastırılır ve sistem istemi uygulanmaz.
2. Grup joker sistem istemi (groups["*"].systemPrompt): belirli grup girdisi eşlemede tamamen yoksa veya varsa ancak systemPrompt anahtarı tanımlamıyorsa kullanılır.

Doğrudan mesajlar için çözümleme hiyerarşisi:

Etkili direct eşlemesi önce belirlenir: hesap kendi direct değerini tanımlıyorsa, kök direct eşlemesinin tamamen yerini alır (derin birleştirme yok). İstem araması daha sonra ortaya çıkan tek eşleme üzerinde çalışır:

1. Doğrudana özel sistem istemi (direct["<peerId>"].systemPrompt): belirli eş girdisi eşlemede varsa ve systemPrompt anahtarı tanımlıysa kullanılır. systemPrompt boş bir dizeyse (""), joker bastırılır ve sistem istemi uygulanmaz.
2. Doğrudan joker sistem istemi (direct["*"].systemPrompt): belirli eş girdisi eşlemede tamamen yoksa veya varsa ancak systemPrompt anahtarı tanımlamıyorsa kullanılır.

Telegram çoklu hesap davranışından farkı: Telegram'da kök groups, çoklu hesap kurulumundaki tüm hesaplar için, kendi groups değerini tanımlamayan hesaplar dahil, kasıtlı olarak bastırılır; bu, bir botun ait olmadığı gruplar için grup mesajları almasını önler. WhatsApp bu korumayı uygulamaz: kök groups ve kök direct, kaç hesap yapılandırılmış olursa olsun hesap düzeyi geçersiz kılma tanımlamayan hesaplar tarafından her zaman devralınır. Çoklu hesaplı bir WhatsApp kurulumunda hesap başına grup veya doğrudan istemler istiyorsanız, kök düzey varsayılanlara güvenmek yerine 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üzeyi grup izin listesidir. Kök veya hesap kapsamında groups["*"], o kapsam için "tüm gruplar kabul edilir" anlamına gelir.
• Joker grup systemPrompt değerini yalnızca o kapsamın zaten tüm grupları kabul etmesini istediğinizde ekleyin. Yine de yalnızca sabit bir grup kimliği kümesinin uygun olmasını istiyorsanız, istem varsayılanı için groups["*"] kullanmayın. Bunun yerine istemi açıkça izin listesine alınmış her grup girdisinde tekrarlayın.
• Grup kabulü ve gönderen yetkilendirmesi ayrı kontrollerdir. groups["*"], grup işlemeye ulaşabilecek grup kümesini genişletir, ancak tek başına bu gruplardaki her göndereni yetkilendirmez. Gönderen erişimi hâlâ ayrı olarak channels.whatsapp.groupPolicy ve channels.whatsapp.groupAllowFrom tarafından denetlenir.
• channels.whatsapp.direct, DM'ler için aynı yan etkiye sahip değildir. direct["*"], yalnızca bir DM dmPolicy artı allowFrom veya eşleştirme deposu kuralları tarafından zaten kabul edildikten sonra varsayılan doğrudan sohbet yapılandırması sağlar.

Örnek:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

Yapılandırma referansı işaretçileri

Birincil referans:

• Yapılandırma referansı - WhatsApp

Önemli WhatsApp alanları:

• erişim: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• teslim: 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.*, web.whatsapp.*
• oturum davranışı: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• istemler: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

İlgili

• Eşleştirme
• Gruplar
• Güvenlik
• Kanal yönlendirme
• Çoklu ajan yönlendirme
• Sorun giderme