WhatsApp

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

# Kurulum (isteğe bağlı)

• Onboarding (openclaw onboard) ve openclaw channels add --channel whatsapp, WhatsApp Plugin'ini ilk kez seçtiğinizde kurmanızı ister.
• 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: geçerli resmi sürüm etiketindeki npm paketi @openclaw/whatsapp kullanılır.

Manuel kurulum kullanılabilir kalır:

openclaw plugins install @openclaw/whatsapp

Geçerli resmi sürüm etiketini takip etmek için yalın paketi kullanın. Tam bir sürümü yalnızca tekrarlanabilir bir kurulum gerektiğinde sabitleyin.

Windows'ta WhatsApp Plugin'i, npm kurulumu sırasında PATH üzerinde Git'e ihtiyaç duyar çünkü Baileys/libsignal bağımlılıklarından biri bir git URL'sinden alınır. Git for Windows'ı kurun, ardından kabuğu yeniden başlatıp kurulumu tekrar çalıştırın:

winget install --id Git.Git -e

Portable Git de bin dizini PATH üzerindeyse çalışır.

# 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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Dağıtım desenleri

{
  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 izleyicisi, yalnızca gelen uygulama iletisi hacmini değil, WhatsApp Web aktarım etkinliğini kullanır; bu nedenle sessiz bir bağlı cihaz oturumu yalnızca yakın zamanda kimse ileti göndermediği için yeniden başlatılmaz. Daha uzun bir uygulama sessizliği üst sınırı, aktarım çerçeveleri gelmeye devam etse ancak izleyici penceresi boyunca hiçbir uygulama iletisi işlenmese yine de yeniden bağlanmayı zorlar; yakın zamanda etkin olan bir oturum için geçici bir yeniden bağlanmadan sonra, bu uygulama sessizliği denetimi ilk kurtarma penceresinde normal ileti zaman aşımını kullanır.
• Baileys soket zamanlamaları web.whatsapp.* altında açıktır: keepAliveIntervalMs WhatsApp Web uygulama ping'lerini, connectTimeoutMs açılış el sıkışması zaman aşımını ve defaultQueryTimeoutMs Baileys sorgu zaman aşımlarını kontrol eder.
• Giden gönderimler, hedef hesap için etkin bir WhatsApp dinleyicisi gerektirir.
• Grup gönderimleri, metin ve medya açıklamalarındaki @+<digits> ve @<digits> belirteçleri geçerli WhatsApp katılımcı meta verileriyle eşleştiğinde, LID destekli gruplar dahil olmak üzere yerel bahsetme meta verilerini ekler.
• Durum ve yayın sohbetleri yok sayılır (@status, @broadcast).
• Yeniden bağlanma izleyicisi, yalnızca gelen uygulama iletisi hacmini değil, WhatsApp Web aktarım etkinliğini izler: sessiz bağlı cihaz oturumları aktarım çerçeveleri devam ederken 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 temsilcinin ana oturumuna toplar).
• Grup oturumları yalıtılmıştır (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters, yerel @newsletter JID'leriyle açık giden hedefler olabilir. Giden newsletter 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şkenlerini dikkate alır (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / küçük harfli varyantlar). Kanal özelindeki WhatsApp proxy ayarları yerine ana makine düzeyi 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.

# 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 korelasyon alanları içerebilir. Bu nedenle, WhatsApp, açıkça dahil olmadığınız sürece gelen message_received kanca yüklerini Plugin'lere yayınlamaz:

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

Dahil olmayı tek bir hesaba kapsamlandı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

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

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

• kendi kendine sohbet turları için okundu bilgilerini atla
• aksi halde kendinize ping atacak bahsetme-JID otomatik tetikleme davranışını yok say
• messages.responsePrefix ayarlanmamışsa kendi kendine 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çalama ve medya

# Yanıt alıntılama

WhatsApp, giden yanıtların gelen mesajı görünür biçimde alıntıladığı yerel yanıt alıntılamayı destekler. Bunu channels.whatsapp.replyToMode ile kontrol edin.

Varsayılan "off" olur. Hesap başına geçersiz kılmalar channels.whatsapp.accounts.<id>.replyToMode kullanır.

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

# Reaksiyon düzeyi

channels.whatsapp.reactionLevel, ajanın WhatsApp üzerinde emoji reaksiyonlarını ne kadar geniş kullandığını kontrol eder:

Varsayılan: "minimal".

Hesap başına geçersiz kılmalar channels.whatsapp.accounts.<id>.reactionLevel kullanır.

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

# Onay reaksiyonları

WhatsApp, channels.whatsapp.ackReaction aracılığıyla gelen alındı bilgisinde anında onay reaksiyonlarını destekler. Onay reaksiyonları reactionLevel tarafından kapılanır — 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ıt öncesi)
• hatalar günlüğe kaydedilir ancak normal yanıt teslimini engellemez
• grup modu mentions, bahsetmeyle tetiklenen turlarda reaksiyon verir; grup etkinleştirme always bu denetim için baypas görevi görür
• WhatsApp channels.whatsapp.ackReaction kullanır (eski messages.ackReaction burada kullanılmaz)

# Çoklu hesap ve kimlik bilgileri

# Araçlar, eylemler ve config yazmaları

• Ajan araç desteği WhatsApp reaksiyon eylemini (react) içerir.
• Eylem kapıları:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Kanal tarafından başlatılan config yazmaları varsayılan olarak etkindir (channels.whatsapp.configWrites=false ile devre dışı bırakılır).

# Sorun giderme

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# Sistem istemleri

WhatsApp, groups ve direct haritaları 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 haritası önce belirlenir: hesap kendi groups değerini tanımlıyorsa, kök groups haritasını tamamen değiştirir (derin birleştirme yok). Ardından istem araması ortaya çıkan tek haritada çalışır:

1. Gruba özgü sistem istemi (groups["<groupId>"].systemPrompt): belirli grup girdisi haritada bulunduğunda ve systemPrompt anahtarı tanımlı olduğunda kullanılır. systemPrompt boş bir dize ("") ise joker bastırılır ve sistem istemi uygulanmaz.
2. Grup joker sistem istemi (groups["*"].systemPrompt): belirli grup girdisi haritada tamamen yoksa veya var olup systemPrompt anahtarı tanımlamıyorsa kullanılır.

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

Etkili direct haritası önce belirlenir: hesap kendi direct değerini tanımlıyorsa, kök direct haritasını tamamen değiştirir (derin birleştirme yok). Ardından istem araması ortaya çıkan tek haritada çalışır:

1. Doğrudan eşe özgü sistem istemi (direct["<peerId>"].systemPrompt): haritada ilgili eş girdisi bulunduğunda ve bu girdinin systemPrompt anahtarı tanımlı olduğunda kullanılır. systemPrompt boş dize ("") ise joker bastırılır ve hiçbir sistem istemi uygulanmaz.
2. Doğrudan joker sistem istemi (direct["*"].systemPrompt): ilgili eş girdisi haritada hiç yoksa veya varsa ancak systemPrompt anahtarı tanımlamıyorsa kullanılır.

Telegram çok hesaplı davranışından farkı: Telegram'da, çok hesaplı bir kurulumda kök groups, kendi groups ayarını tanımlamayan hesaplar dahil tüm hesaplar için kasıtlı olarak bastırılır; bunun amacı, bir botun ait olmadığı gruplardan grup mesajları almasını önlemektir. WhatsApp bu korumayı uygulamaz: kök groups ve kök direct, kaç hesap yapılandırılmış olursa olsun, hesap düzeyinde geçersiz kılma tanımlamayan hesaplar tarafından her zaman devralınır. Çok hesaplı bir WhatsApp kurulumunda hesap başına grup veya doğrudan istemler istiyorsanız, kök düzey varsayılanlara güvenmek yerine her hesabın altında haritanın tamamını açıkça tanımlayın.

Önemli davranış:

• channels.whatsapp.groups, hem grup başına yapılandırma haritası 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.
• Bir joker grup systemPrompt değerini yalnızca o kapsamın tüm grupları zaten kabul etmesini istiyorsanız ekleyin. Hâlâ yalnızca sabit bir grup ID kümesinin uygun olmasını istiyorsanız, istem varsayılanı için groups["*"] kullanmayın. Bunun yerine istemi açıkça izin verilen her grup girdisinde tekrarlayın.
• Grup kabulü ve gönderen yetkilendirmesi ayrı denetimlerdir. groups["*"], grup işlemeye ulaşabilen 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 ile kontrol edilir.
• channels.whatsapp.direct, DM'ler için aynı yan etkiye sahip değildir. direct["*"], yalnızca bir DM dmPolicy artı allowFrom veya eşleme deposu kurallarıyla zaten kabul edildikten sonra varsayılan bir 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.
            "[email protected]": {
              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 başvurusu işaretçileri

Birincil başvuru:

• Yapılandırma başvurusu - WhatsApp

Yüksek değerli WhatsApp alanları:

• erişim: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• teslim: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• çok hesaplı: accounts.<id>.enabled, accounts.<id>.authDir, hesap düzeyi geçersiz kılmalar
• operasyonlar: 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şleme
• Gruplar
• Güvenlik
• Kanal yönlendirme
• Çok aracılı yönlendirme
• Sorun giderme