WhatsApp

Durum: WhatsApp Web (Baileys) üzerinden üretime hazır. Gateway, bağlı oturumların sahibidir; ayrı bir Twilio WhatsApp kanalı yoktur.

Kurulum

openclaw onboard ve openclaw channels add --channel whatsapp, ilk kez seçtiğinizde plugini kurmanızı ister; plugin eksikse openclaw channels login --channel whatsapp aynı kurulum akışını sunar. Geliştirme çalışma kopyaları yerel plugin yolunu kullanır; kararlı/beta kurulumları önce ClawHub'dan @openclaw/whatsapp kurar, başarısız olursa npm'e geri döner. WhatsApp çalışma zamanı, temel OpenClaw npm paketinin dışında sunulduğundan çalışma zamanı bağımlılıkları harici pluginle 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 bir 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

• Gateway, WhatsApp soketinin ve yeniden bağlanma döngüsünün sahibidir.
• 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) gelmeyi durdurduğunda veya uygulama mesajları normal mesaj zaman aşımının 4 katını aşacak kadar sessiz kaldığında yeniden bağlanmayı zorlar. Yakın zamanda etkin olan bir oturum yeniden bağlandıktan hemen sonra bu ilk süre, 4 katlık süre yerine daha kısa olan normal mesaj zaman aşımını kullanır. OpenClaw, Baileys'in bu yeniden bağlanmanın erken aşamasında ilettiği çevrimdışı mesajlara, gelen mesaj kimliği yinelenenleri ayıklama ömrüyle sınırlı olarak otomatik yanıt verebilir; ilk başlatma kısa eski geçmiş korumasını sürdürür.
• Giden gönderimler, hedef hesap için etkin bir WhatsApp dinleyicisi gerektirir; aksi takdirde gönderimler hızla başarısız olur.
• Grup gönderimleri, belirteç mevcut katılımcı meta verileriyle eşleştiğinde @+<digits> ve @<digits> belirteçleri için (metin ve medya açıklamalarında) LID destekli gruplar dahil olmak üzere yerel bahsetme meta verilerini 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 aracının ana oturumunda birleştirir). Grup oturumları her JID için yalıtılır (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Kanalları/Bültenleri, DM semantiği yerine kanal oturumu meta verilerini (agent:<agentId>:whatsapp:channel:<jid>) kullanarak yerel @newsletter JID'leri aracılığıyla açık giden hedefler olabilir.
• WhatsApp Web aktarımı, Gateway ana makinesindeki standart proxy ortam değişkenlerine (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, küçük harfli çeşitleri) uyar. Kanal başına ayarlar yerine ana makine düzeyinde proxy yapılandırmasını tercih edin.

Mevcut istekte bulunanı MeowCaller ile arayın (deneysel)

Plugin, WhatsApp kaynaklı aracı dönüşlerinde whatsapp_call sunabilir. Mevcut yetkili istekte bulunana WhatsApp sesli araması yapmak ve yanıt verdikten sonra bir OpenClaw TTS mesajı oynatmak için MeowCaller kullanır. Aracın hedef numara parametresi yoktur, bu nedenle bir istem çağrıyı yeniden 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ğrulama yok; kişisel numara/kendi kendine sohbet modundan kendi kendini arama yok; sentezlenen ses 60 saniyeyle sınırlıdır; MeowCaller'ın yanıtlama/oynatma/kapatma tamamlanması dışında telefon tarafında duyulabilirlik alındısı yoktur ve OpenClaw, yardımcı işlemi sınırlı bir 115-175 saniyelik süreden sonra durdurur (MeowCaller'ın bağlantı, yanıtlama, oynatma ve kapanma aşamalarını kapsar).

Onay istemleri

WhatsApp, yürütme ve plugin onay istemlerini üst düzey onay iletme yapılandırmasıyla denetlenen 👍/👎 tepkileri olarak işleyebilir:

{  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önlendirilmedikçe hiçbir şey göndermez. Oturum modu, yalnızca WhatsApp'tan kaynaklanan onaylar için yerel emoji onayları iletir. Hedef modu, açık hedefler için paylaşılan iletme işlem hattını kullanır ve ayrı onaylayıcı DM dağıtımı oluşturmaz.

WhatsApp onay tepkileri, allowFrom (veya "*") içinde açık onaylayıcılar gerektirir. defaultTo, onaylayıcı listesi değil, sıradan varsayılan mesaj hedeflerini ayarlar. Manuel /approve komutları, onay çözümlenmeden önce yine normal WhatsApp gönderen yetkilendirme yolundan geçer.

Soru tepkileri

Gizli olmayan, tek seçimli bir soru ve bir ile dört seçenek içeren ask_user istemi için WhatsApp, seçenek etiketlerinin yanında 1️⃣ ile 4️⃣ arasındaki değerleri gösterir. Yanıtlamak için iletilen isteme eşleşen numarayla tepki verin. OpenClaw, numarayı Gateway aracılığıyla kurallı seçeneğe eşler; eski veya yinelenen dokunuşlar yok sayılır. Çok sorulu, çok seçimli ve serbest metin istemleri yalnızca metin yanıtlı olarak kalır. Normal WhatsApp DM/grup kabul kuralları, tepki veren göndereni yetkilendirir.

Plugin kancaları ve gizlilik

Gelen WhatsApp mesajları kişisel içerik, telefon numaraları, grup tanımlayıcıları, gönderen adları ve oturum ilişkilendirme alanları taşıyabilir. WhatsApp, siz etkinleştirmedikçe gelen message_received kanca yüklerini pluginlere yayınlamaz:

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

Etkinleştirme kapsamını channels.whatsapp.accounts.<id>.pluginHooks.messageReceived altında tek bir hesapla sınırlayın. Bunu yalnızca gelen WhatsApp içeriği ve tanımlayıcıları konusunda güvendiğiniz pluginler 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 kısıtlaması, OpenClaw bağlı ACP oturumunun varlığını sağlamadan önce çalışır. Eşleşen bir bağlama rotanın sahibidir — yayın grupları bu etkileşimi sıradan WhatsApp oturumlarına dağıtmaz.

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

Bağlı öz numara allowFrom içinde de yer aldığında kendi kendine sohbet güvenlik önlemleri etkinleşir: kendi kendine sohbet etkileşimleri için okundu bilgilerini atlar, kendinize bildirim gönderecek bahsetme JID'si otomatik tetikleme davranışını yok sayar ve kanal/hesap responsePrefix değeri ayarlanmamışsa yanıtları varsayılan olarak [{identity.name}] (veya [openclaw]) değerine yönlendirir.

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 şekilde 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ı onayı tepkileri

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

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // her zaman | bahsetmeler | hiçbir zaman      },    },  },}

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 mevcut değilse "👀" değerine geri döner (onay tepkisi olmaması için ackReaction değerini atlayın veya emoji: "" olarak ayarlayın); hatalar günlüğe kaydedilir ancak yanıt teslimatını engellemez; grup modu mentions yalnızca bahsetmeyle tetiklenen etkileşimlerde tepki verirken grup etkinleştirmesi always bu denetimi atlar; WhatsApp yalnızca channels.whatsapp.ackReaction kullanır (eski messages.ackReaction burada geçerli değildir).

Yaşam döngüsü durumu tepkileri

WhatsApp'ın bir etkileşim sırasında statik bir alındı emojisi bırakmak yerine onay tepkisini değiştirmesini ve kuyrukta, düşünüyor, araç etkinliği, Compaction, tamamlandı ve hata gibi durumlar arasında geçiş yapmasını sağlamak için messages.statusReactions.enabled: true değerini ayarlayın:

{  messages: {    statusReactions: {      enabled: true,    },  },}

Notlar: channels.whatsapp.ackReaction, doğrudan mesajlar ve gruplar için uygunluğu denetlemeye devam eder; kuyrukta durumu, düz onay tepkileriyle aynı etkin emojiyi kullanır; WhatsApp'ta mesaj başına bir bot tepki yuvası bulunur, bu nedenle yaşam döngüsü güncellemeleri mevcut tepkiyi yerinde değiştirir ve son tamamlandı/hata durumundan sonra onay tepkisini geri yükler.

Çoklu hesap ve kimlik bilgileri

Araçlar, eylemler ve yapılandırma yazma işlemleri

• Agent araç desteği, WhatsApp tepki eylemini (react) içerir.
• Eylem geçitleri: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (mevcut eylemlerin varsayılanı 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 yazma işlemleri varsayılan olarak etkindir; channels.whatsapp.configWrites: false aracılığıyla devre dışı bırakın.

Sorun giderme

openclaw channels login --channel whatsappopenclaw channels status

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ı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 ve systemPrompt anahtarı tanımlı olduğunda kullanılır. Boş bir dize ("") joker karakteri bastırır ve hiçbir istem uygulamaz.
2. Grup joker karakteri istemi (groups["*"].systemPrompt): belirli grup girdisi mevcut olmadığında veya systemPrompt anahtarı olmadan mevcut olduğunda kullanılır.

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

Telegram'dan farkı: Telegram, bir botun üyesi olmadığı gruplardan grup mesajları almasını önlemek için çok hesaplı bir kurulumdaki her hesapta kök groups değerini bastırır (kendi groups değeri olmayan hesaplarda bile). WhatsApp bu korumayı uygulamaz — kök groups/direct, hesap sayısından bağımsız olarak kendi geçersiz kılması bulunmayan her hesap tarafından devralını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["*"], söz konusu kapsam için "tüm gruplar kabul edilir" anlamına gelir.
• Yalnızca söz konusu kapsamın tüm grupları kabul etmesini zaten istiyorsanız bir systemPrompt joker karakteri 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 tekrarlayın.
• Grup kabulü ve gönderen yetkilendirmesi ayrı denetimlerdir. groups["*"], hangi grupların grup işlemeye ulaşacağını genişletir; bu gruplardaki her gönderene yetki vermez — bu işlem groupPolicy/groupAllowFrom tarafından denetlenmeye devam eder.
• channels.whatsapp.direct, DM'ler için eşdeğer bir yan etkiye sahip değildir: direct["*"], yalnızca bir DM dmPolicy ile birlikte allowFrom veya eşleştirme deposu kuralları tarafından zaten kabul edildikten sonra varsayılan bir 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 eşlemesini tanımlar, dolayısıyla kök groups eşlemesi tamamen            // değiştirilir. Joker karakteri korumak için "*" değerini burada da açıkça tanımlayın.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Proje yönetimine odaklan.",            },            // Yalnızca bu hesapta tüm grupların kabul edilmesi gerekiyorsa kullanın.            "*": { systemPrompt: "İş grupları için varsayılan istem." },          },          direct: {            // Bu hesap kendi direct eşlemesini tanımlar, dolayısıyla kök direct girdileri            // tamamen değiştirilir. Joker karakteri korumak için "*" değerini burada da açıkça tanımlayın.            "+15551234567": { systemPrompt: "Belirli bir doğrudan iş sohbeti için istem." },            "*": { systemPrompt: "Doğrudan iş sohbetleri için varsayılan istem." },          },        },      },    },  },}

Yapılandırma başvurusu bağlantıları

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

İlgili

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