WhatsApp

​

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.

openclaw plugins install clawhub:@openclaw/whatsapp

​

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>

​

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

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

• 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

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

​

Plugin kancaları ve gizlilik

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

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

​

Erişim denetimi ve etkinleştirme

​

Yapılandırılmış ACP bağlamaları

{
  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ışı

• 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

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

​

Tepki düzeyi

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

​

Alındı onayı tepkileri

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

• 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

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

• 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 whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

Sistem istemleri

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.

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.

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

{
  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

• Yapılandırma referansı - WhatsApp

• 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