WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

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

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

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

​

Erişim denetimi ve etkinleştirme

​

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

• 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

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

​

Reaksiyon düzeyi

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

​

Onay reaksiyonları

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

• 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

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.

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.

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

{
  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 başvurusu işaretçileri

• Yapılandırma başvurusu - WhatsApp

• 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